介绍

在现代 Web 开发中，API 一致性对于开发人员的生产力起着至关重要的作用。

不一致的端点 (URL)、不正确的 HTTP 方法以及将所有错误包装在 200 OK 状态代码中会导致混乱、错误和浪费的开发周期。

本文回顾了设计易于理解和集成的可扩展、自记录 REST API 的最佳实践。

1. 原则 1：面向资源的 URL（使用名词）

REST 的核心原则是 URI 代表资源（名词），而 HTTP 方法（动词） 代表对这些资源执行的操作。

要避免的端点（URL 中的动词）

• POST /getUsers（获取用户列表）
• POST /deletePost?id=123（删除帖子）
• POST /create_comment（创建评论）

将动作动词混合到 URL 中会创建冗余端点并破坏标准命名模式。

优化设计

对资源的复数名词进行标准化，并让 HTTP 方法决定操作。

• 使用复数名词： 对复数名词进行标准化（例如 /users、/posts、/comments），以保持 API 中的路由一致性。

2. 原则 2：正确的 HTTP 方法使用和幂等性

修改资源时，了解 HTTP 方法之间的语义差异并尊重它们的幂等性非常重要。

• PUT（替换）： 将整个目标资源替换为上传的有效负载。此操作是幂等，因为多次发送相同的请求会产生相同的状态。
• PATCH（部分更新）： 对资源应用部分修改。
• POST（创建）： 提交数据以创建新资源。此操作是非幂等，因为重复请求将导致多个资源实例。

尊重这些方法语义允许客户端应用程序安全地重试失败的网络请求。

3. 原则 3：利用 HTTP 状态代码

在将实际错误状态嵌入到 JSON 负载中时，请勿将所有 API 响应包装在 200 OK 代码中。这是一种常见的反模式。

反模式反应

• HTTP 标头： 200 OK
• 响应正文：

  {
    "status": "error",
    "errorCode": 404,
    "message": "User not found"
  }
  

标准 API 状态代码

• **200 OK：**请求成功（常用于GET、PUT和PATCH）。
• 201 Created： 已成功创建新资源（用于 POST）。
• 204 No Content： 请求成功，但没有要返回的有效负载（用于 DELETE）。
• 400 Bad Request: 客户端发送了无效的负载参数（验证失败）。
• 401 Unauthorized: 请求缺少有效的身份验证凭据。
• 403 Forbidden: 客户端已通过身份验证，但无权访问资源。
• 404 Not Found: 请求的资源不存在。
• 500 Internal Server Error: 表示服务器端崩溃或数据库故障的一般错误。

4. 原则 4：过滤、排序和分页

检索资源集合（例如 /posts）时，避免创建用于排序或过滤的自定义端点。相反，使用查询参数。

查询参数示例

• 过滤： GET /posts?category=tech （仅获取技术帖子）
• 排序： GET /posts?sort=-createdAt （按创建日期降序排序）
• 分页： GET /posts?page=2&limit=20 （获取第 2 页，限制为 20 项）

5. 原则 5：API 版本控制

为了防止在更新 API 架构时破坏客户端应用程序，请始终包含版本控制。最常见的方法是路径版本控制：

• 路径版本控制： /api/v1/users

这允许您部署新版本 (/api/v2/...)，同时为旧客户端保持 /api/v1/ 处于活动状态。

结论

设计干净、一致的 REST API 端点可以简化集成并减少新开发人员的入职时间。

1. 在 URI 路径中使用复数名词表示资源。
2. 使用标准 HTTP 状态代码（201、400、403、404）传达结果。
3. 使用查询参数进行过滤、排序和分页。

遵循这些指南将帮助您构建可维护且对开发人员友好的 API。