RESTful API 设计指南：HTTP 方法详解

RESTful API 设计指南：HTTP 方法详解

本文基于 RestApiTutorial.com 项目中的 HTTP 方法教程，深入解析 RESTful 服务设计中 HTTP 方法的最佳实践。作为 REST 架构风格的核心组成部分，HTTP 方法定义了客户端与服务器交互的基本操作。

HTTP 方法与 CRUD 操作对应关系

在 RESTful API 设计中，HTTP 方法与 CRUD（创建、读取、更新、删除）操作有着明确的对应关系：

| HTTP 方法 | CRUD 操作 | 集合资源 (如 /customers) | 单个资源 (如 /customers/{id}) | |-----------|-----------|--------------------------|-------------------------------| | POST | 创建 | 201 (Created)，返回包含新 ID 的 Location 头 | 404 (Not Found) 或 409 (Conflict) 如果资源已存在 | | GET | 读取 | 200 (OK)，返回客户列表（建议分页） | 200 (OK) 返回单个客户，404 如果 ID 无效 | | PUT | 更新/替换 | 405 (Method Not Allowed) 除非要替换整个集合 | 200 (OK) 或 204 (No Content)，404 如果 ID 无效 | | PATCH | 更新/修改 | 405 (Method Not Allowed) 除非要修改集合本身 | 200 (OK) 或 204 (No Content)，404 如果 ID 无效 | | DELETE | 删除 | 405 (Method Not Allowed) 除非要删除整个集合 | 200 (OK)，404 如果 ID 无效 |

主要 HTTP 方法详解

POST - 创建资源

POST 方法主要用于创建新资源，特别是创建从属资源。当创建新资源时，客户端应该向父资源发起 POST 请求，服务端负责将新资源与父资源关联并分配 ID。

关键特性：

• 非安全（修改服务器状态）
• 非幂等（多次相同请求可能创建多个资源）
• 成功时应返回 201 (Created) 状态码，并在 Location 头中包含新资源的 URI

示例场景：

• 创建新客户：POST /customers
• 为客户创建新订单：POST /customers/12345/orders

GET - 读取资源

GET 方法用于检索资源表示。在成功情况下返回 200 (OK) 和资源数据（通常为 JSON 或 XML），错误时返回 404 (Not Found) 或 400 (Bad Request)。

关键特性：

• 安全（不修改服务器状态）
• 幂等（多次相同请求效果相同）
• 不应通过 GET 暴露任何会修改资源的操作

示例场景：

• 获取客户信息：GET /customers/12345
• 获取客户订单列表：GET /customers/12345/orders

PUT - 更新/替换资源

PUT 方法主要用于完整更新资源，客户端需要提供资源的完整表示。PUT 也可用于创建资源（当客户端指定资源 ID 时），但这种做法不推荐。

关键特性：

• 非安全（修改服务器状态）
• 幂等（多次相同请求效果相同）
• 成功更新返回 200 (OK) 或 204 (No Content)
• 成功创建返回 201 (Created)

示例场景：

• 更新客户信息：PUT /customers/12345
• 替换订单内容：PUT /customers/12345/orders/98765

PATCH - 部分更新资源

PATCH 方法用于对资源进行部分修改，请求体只需包含要修改的字段而非完整资源。与 PUT 不同，PATCH 请求体应使用专门的补丁格式（如 JSON Patch）。

关键特性：

• 非安全（修改服务器状态）
• 默认非幂等（但可实现为幂等）
• 建议使用条件请求（如 If-Match 头）防止冲突

示例场景：

• 更新客户部分信息：PATCH /customers/12345
• 修改订单部分内容：PATCH /customers/12345/orders/98765

DELETE - 删除资源

DELETE 方法用于删除指定 URI 标识的资源。成功删除可返回 200 (OK) 带响应体，或 204 (No Content) 无响应体。

关键特性：

• 非安全（修改服务器状态）
• 幂等（资源删除后再次删除结果相同）
• 第二次删除可能返回 404 (Not Found)，这并不违反幂等性

示例场景：

• 删除客户：DELETE /customers/12345
• 删除客户所有订单：DELETE /customers/12345/orders

设计原则与最佳实践

1. 安全性：GET 和 HEAD 方法应该是安全的，不会修改服务器状态。

2. 幂等性：GET、PUT、DELETE 方法应该是幂等的，POST 和 PATCH 通常不是。

3. 资源命名：URI 应该表示资源而非动作，动作由 HTTP 方法表达。

4. 状态码使用：正确使用 HTTP 状态码传达操作结果。

5. 部分更新：优先使用 PATCH 而非 PUT 当只需更新部分字段时。

6. 批量操作：避免在集合资源上使用 PUT 或 DELETE，除非确实需要批量操作。

通过遵循这些 HTTP 方法的使用规范，可以设计出符合 REST 架构风格的、易于理解和使用的 API。正确使用这些方法不仅能提高 API 的可用性，还能使其更加健壮和可维护。