API 和契约

在现代软件系统中，应用很少直接与后端逻辑交互。相反，它们通过 API 进行通信，API 充当系统的受控入口。

客户端——例如浏览器、移动应用或另一个后端服务——会向某个特定的 API 端点发送请求。API 接收该请求，解析其中包含的信息，并将其转发给相应的后端逻辑。然后，后端执行必要的工作，例如从数据库中检索数据或执行应用规则，最后再把响应返回给客户端。

这种结构化通信使系统能够保持模块化。只要遵循 API 定义的请求和响应格式，前端应用、移动应用和外部服务就可以与同一个后端功能交互。

由于 API 定义了请求必须如何组织以及响应会是什么样子，它们在系统的不同部分之间创建了一个可预测的接口。这个接口使得独立开发的组件能够可靠地通信，而无需了解内部后端实现是如何工作的。

当客户端向 API 端点发送请求时，必须指定它想执行哪种操作。这个操作通过 HTTP 方法来表达。

HTTP 方法与端点 URL 一起工作，用来定义请求的含义。

例如，像 GET /users 这样的请求是在请求服务器检索用户数据。像 POST /users 这样的请求是在请求服务器创建一个新用户。像 DELETE /users/42 这样的请求则指示后端删除某个特定用户。

API 中通常会使用几种 HTTP 方法。

GET 从服务器检索现有数据。
POST 创建新资源。
PUT 用新数据替换现有资源。
PATCH 更新现有资源的一部分。
DELETE 从系统中移除资源。

通过将端点与 HTTP 方法结合起来，API 可以清晰地定义客户端被允许对系统资源执行的操作。

在 API 设计中，一种方法是围绕动作来组织端点，也就是每个 URL 都描述系统应该执行什么操作。例如，像 POST /createUser 这样的端点会直接把动作编码到 URL 中。

这种方式适合小型系统，但随着功能数量增加，会变得难以维护。端点会变得不一致，而且也更难预测新功能会如何暴露出来。

REST 采用了不同的方法，它把 API 围绕用户、订单或产品等资源来组织。它不会把动作编码到 URL 中，而是让端点表示资源，由 HTTP 方法来定义操作。

例如，POST /users 用于创建新用户，而 GET /users 用于获取用户。这种分离方式让整个 API 保持一致的模式。

因此，RESTful API 更容易理解、扩展和维护。开发者在接触新的端点时也更容易上手，因为它们遵循相同且可预测的设计。

REST 建立在一组设计原则之上，这些原则有助于 API 在系统不断增长时保持一致和可靠。

一个关键原则是无状态通信。每个请求都必须包含服务器处理它所需的全部信息。服务器不依赖之前的请求，这使系统更容易扩展和分布式部署。

另一个原则是基于资源的设计。API 将用户或订单等实体表示为资源，并使用像 /users 或 /orders 这样的 URL 来标识这些资源。

REST 还依赖标准的 HTTP 语义。GET、POST、PUT、PATCH 和 DELETE 等 HTTP 方法用于清晰地表达对资源执行的操作。

最后，REST 强制使用统一接口。端点遵循一致的模式，使 API 更容易理解，并减少在与系统不同部分交互时的混淆。

当服务器处理一个请求时，它必须将结果返回给客户端。HTTP 状态码提供了一种标准化的方式来描述该结果。

状态码按类别分组。2xx 范围内的代码表示成功，意味着请求已被正确处理。4xx 范围内的代码表示客户端错误，例如无效输入或缺少资源。5xx 范围内的代码表示服务器错误，意味着后端出现了问题。

常见示例包括 200 OK，表示请求成功，以及 201 Created，表示已创建一个新资源。像 400 Bad Request 这样的错误表示输入无效，而 401 Unauthorized 表示缺少或无效的身份验证。404 Not Found 响应表示请求的资源不存在，而 500 Internal Server Error 表示服务器发生故障。

客户端使用这些状态码来决定下一步如何处理。例如，客户端可能会在服务器错误后重试请求，或者在客户端错误后提示用户更正输入。

在分布式系统中，请求可能会失败、超时，或者被多次重试。因此，后端系统必须设计成能够安全地处理重复请求。

如果发送同一个请求多次后得到的最终状态相同，那么这个操作就被认为是幂等的。例如，调用 DELETE /users/10 一次会删除该用户。再次调用它不会再改变任何内容，因为该用户已经被删除了。

类似地，PUT /users/10 每次都会用相同的数据替换资源，因此重复请求不会产生额外的副作用。

相比之下，POST /orders 通常不是幂等的，因为每个请求都会创建一个新的订单。重复相同的请求可能会导致重复资源。

幂等性很重要，因为系统在发生故障时通常会自动重试请求。如果没有幂等性，重试可能会导致数据不一致、重复操作或意外的副作用。

随着后端系统不断演进，API 往往也需要变化。可能会添加新功能、更新数据格式，或者修改现有行为。

问题在于，Web 应用、移动应用或第三方集成等客户端依赖于现有的 API 行为。如果 API 在没有预警的情况下发生变化，这些客户端可能会出错。

API 版本控制通过允许同一个 API 同时存在多个版本来解决这个问题。旧客户端可以继续使用原始版本，而新客户端可以采用更新后的版本。

一种常见的方法是 URL 版本控制，即将版本包含在路径中，例如 /v1/users 和 /v2/users。另一种方法是 Header 版本控制，即客户端使用类似 Accept: application/vnd.api.v2 的 Header 来指定版本。

通过对 API 进行版本控制，后端系统可以安全演进，同时保持与现有客户端的兼容性。

API 契约就像客户端与后端系统之间的一份协议。它精确定义了通信应该如何进行，从而让双方能够无歧义地交互。

当客户端发送 HTTP 请求时，必须按照契约来做：使用正确的端点，提供预期的数据格式，并包含所有必需信息。后端系统会根据这些规则处理请求，并返回结构化的 HTTP 响应。

该契约定义了 API 的几个关键方面，包括可用的端点、请求数据的格式、响应的结构、状态码的含义，以及每个操作的预期行为。

有了这个契约，客户端就不需要了解后端内部是如何实现的。只要遵循定义好的接口，通信就能保持一致且可靠。

在实际开发中，API 契约对于前端和后端团队之间的协作，以及独立系统之间的集成都至关重要。