REST API 设计和命名约定指南

RESTful有效设计 API对于创建可扩展、可维护、易于使用的系统至关重要。虽然有一些标准，但许多标准不是严格的规则，而是指导 API 设计的最佳实践。广泛使用 API 架构模式是 MVC(模型-视图-控制器)，但本身无法解决 API 更精细的设计方面，如命名和结构。本文将逐步介绍建筑 REST API 基本准则。

1. 命名协议和资源设计 API 资源代表系统中的实体，如“用户”，通常围绕资源定义、“产品”或“订单”。资源可以是单个项目或集合，API 与这些资源互动应提供直观清晰的方式。

主要原则：面向资源：围绕资源而不是操作设计 API。资源应该被视为名词，而不是动词。例如：

/users 用于访问用户集合。 /users/{userId} 用于访问特定用户。 一致性：API 它应该是直观的。如果用户能从头开始 /users 为了获得资源列表，他们应该期望通过添加标识符来获得单个资源：/users/{userId}.

收集和单一资源：

复数名词表示资源集合:/users、/products。 单个资源通过附加资源的唯一标识符表示:/users/{userId}、/products/{productId}.

1. HTTP 方法定义操作，而不是 URI 正在执行的操作(无论是检索数据、创建新项目还是更新现有数据)都不应嵌入 URI 中。相反，HTTP 决定操作的方法。

常见的 HTTP 方法及其用例： GET：从服务器中检索数据。

示例：GET /products 返回所有产品列表。 示例： GET /users/{userId} 有指定的检索 userId 的用户。 POST：在服务器上创建新的资源。

示例：POST /users 创建新用户。 PUT：用新数据替换现有资源(完全更新)。

示例：PUT /users/{userId} 用新数据完全替换用户数据。 PATCH：现有资源(部分更新)部分更新。

示例：PATCH /users/{userId} 仅更新指定的属性，如电话号码。 DELETE：删除资源。

示例：DELETE /users/{userId} 删除指定 userId 的用户。

1. REST 中的无状态 REST API 它应该是无状态的，这意味着每个人都是无状态的 API 调用必须包含服务器处理请求所需的所有信息。这确保每个请求都是自给自足的，并且不依赖于以前的请求。

例子：当发出 GET 在获取用户详细信息时，即使之前的请求已经验证了用户的身份，请求也必须包含所需的授权令牌。这在分布式系统中非常重要，因为不同的请求可能会到达不同的服务器。

1. 避免特定于服务器的数据存储 任何单个 API 请求不应依赖于在特定服务器上存储临时数据。在分布式系统中，传输请求可能通过任何服务器传输，因此无论哪个服务器处理请求，都应实现相同的结果。这就是为什么会话状态不应该存储在单独的服务器上。

解决方案:对于会话管理，请使用集中或分布式存储系统(如 Redis）或者没有状态身份验证机制(例如(例如) JWT（JSON Web Token））。

1. 资源与数据库表 您的 API 数据库表和设计不应在数据库表中进行 API 端点之间有一对一的映射。 API 有意义的资源应该在逻辑上公开，这些资源可以从多个表或源中组合数据。

示例： GET /orders/{orderId} 结合订单，可以检索订单的详细信息order_items 以及客户表中的信息。

1. 数据类型的灵活性 REST API 不受数据库数据类型或表结构的限制。你可以是最适合你的 API 用消费者的方式建立你的反应。虽然 JSON 它是最常用的格式，但如有必要，您可以自由返回 XML 或 CSV 等待其他格式的数据。

示例：GET /reports/{reportId} 根据请求中的查询参数或标头，端点可以返回各种格式（JSON、CSV、PDF）的报告。 API 结构示例 为了将这些原则联系起来，这里有一个遵循这些最佳实践的原则 API 结构示例：

GET /products：检索所有产品。 GET /products/{productId}：详细检索特定产品的信息。 POST /products：创造新产品。 PUT /products/{productId}：用productid代替产品。 PATCH /products/{productId}：部分更新产品。 DELETE /products/{productId}：删除产品。 在这种结构中，资源被明确定义，HTTP 该方法规定了要采取的操作，以确保 API 干净直观。

**结论 **设计 RESTful API 不仅涉及路由的创建和处理 HTTP 方法。注重资源，利用资源。 HTTP 操作方法，遵守无状态，可创建直观、可维护、可扩展的方法 API。请记住，API 随着系统的发展，应灵活独立于特定的数据库结构，以提供更多的适应性。

遵循这些协议可以确保你 API 设计效率高，用户友好，最终增强 API 开发人员和消费者的体验。

以上是REST API 请关注图灵教育的其他相关文章，详细介绍设计和命名协议指南！