RESTful API 中的 HTTP 方法详解
在 RESTful API 设计中，HTTP 方法（HTTP Verbs） 是表达对资源操作意图的核心方式。不同的 HTTP 方法对应不同的语义，正确使用它们能让 API 更清晰、可预测和符合 REST 原则。
1. 核心 HTTP 方法及其在 REST 中的对应（CRUD 操作）
| HTTP 方法 | 对应 CRUD 操作 | 主要用途 | 是否安全（Safe） | 是否幂等（Idempotent） | 典型状态码（成功时） |
|---|---|---|---|---|---|
| GET | Read | 获取资源（单个或集合） | 是（不修改资源） | 是 | 200 OK |
| POST | Create | 创建新资源 | 否 | 否 | 201 Created |
| PUT | Update（替换） | 替换（全量更新）指定资源 | 否 | 是 | 200 OK 或 201 Created |
| PATCH | Update（部分） | 部分更新指定资源（只修改提供的字段） | 否 | 否（取决于实现） | 200 OK 或 204 No Content |
| DELETE | Delete | 删除指定资源 | 否 | 是 | 200 OK 或 204 No Content |
2. 每个方法的详细说明与使用规范
- GET
- 用于读取资源，不应产生副作用（不修改服务器状态）。
- 支持查询参数（Query Parameters）进行过滤、分页、排序等。
- 示例：
GET /users→ 获取用户列表GET /users/123→ 获取 ID 为 123 的用户GET /articles?tag=rest&limit=20&page=2→ 分页查询带标签的文章
- 注意：GET 请求应可缓存，长度有限制（通常 < 2048 字符）。
- POST
- 用于创建新资源，或执行非幂等的复杂操作（如触发流程）。
- 请求体（Body）携带新资源数据。
- 示例：
POST /users→ 创建新用户，返回 201 + Location 头部指向新资源 URIPOST /orders/123/pay→ （不推荐）触发支付（更推荐用资源方式设计）
- 注意：多次相同 POST 会创建多个资源（非幂等）。
- PUT
- 用于全量替换资源：如果资源不存在则创建（有时称为“upsert”），如果存在则完全替换。
- 客户端必须提供资源的完整表示（缺失字段通常会被置为 null 或默认值）。
- 示例：
PUT /users/123→ 用请求体完全替换 ID 为 123 的用户
- 注意：多次相同 PUT 结果相同（幂等）。
- PATCH
- 用于部分更新资源：只修改请求体中提供的字段，其他字段保持不变。
- 常见格式：JSON Patch（RFC 6902）、JSON Merge Patch（RFC 7396）或自定义对象。
- 示例：
PATCH /users/123→ Body:{ "name": "新名字" }只改名字
- 注意：幂等性取决于实现（JSON Merge Patch 是幂等的，某些自定义方式不是）。
- DELETE
- 用于删除资源。
- 通常不需要请求体，可选返回被删除的资源表示。
- 示例：
DELETE /users/123→ 删除 ID 为 123 的用户
- 注意：多次相同 DELETE 结果相同（幂等），可返回 204 No Content。
3. 其他不常用但有用的 HTTP 方法
| 方法 | 用途 | RESTful 中常见场景 |
|---|---|---|
| HEAD | 与 GET 相同，但只返回头部（无响应体） | 检查资源是否存在、获取元信息（如 Last-Modified） |
| OPTIONS | 获取资源支持的 HTTP 方法 | CORS 预检请求、API 文档发现 |
| TRACE | 回显请求（用于调试） | 很少使用，通常禁用以防安全风险 |
4. 安全（Safe）与幂等（Idempotent）的含义
- 安全方法：不会改变服务器状态（只读）。只有 GET 和 HEAD 是安全的。
- 幂等方法：多次执行效果与一次相同。GET、PUT、DELETE、HEAD、OPTIONS 是幂等的，POST 和 PATCH 通常不是（PATCH 取决于具体实现）。
幂等性对网络重试、缓存、负载均衡非常重要。
5. 实际案例对比
假设资源是用户（/users/123）：
| 操作 | 推荐 HTTP 请求 | 不推荐（RPC 风格） |
|---|---|---|
| 获取用户信息 | GET /users/123 | POST /getUser |
| 创建用户 | POST /users | GET /createUser |
| 更新用户姓名 | PATCH /users/123 { “name”: “张三” } | POST /updateUserName |
| 完全替换用户信息 | PUT /users/123 (完整用户对象) | POST /replaceUser |
| 删除用户 | DELETE /users/123 | POST /deleteUser |
6. 总结口诀
“查用 GET，增用 POST，全改 PUT，部分 PATCH，删用 DELETE”
正确使用 HTTP 方法是设计优秀 RESTful API 的基础，它能让你的接口更直观、更易维护，也更符合业界标准。如果你想看具体代码示例（如 Express、Spring Boot 中的路由定义）或其他进阶话题（如批量操作如何选择方法），随时告诉我！
