企业官网建设流程全解析

RESTful API 中的 HTTP 方法详解

在 RESTful API 设计中，HTTP 方法（HTTP Verbs）是表达对资源操作意图的核心方式。不同的 HTTP 方法对应不同的语义，正确使用它们能让 API 更清晰、可预测和符合 REST 原则。

1. 核心 HTTP 方法及其在 REST 中的对应（CRUD 操作）

2. 每个方法的详细说明与使用规范

1. GET

   • 用于读取资源，不应产生副作用（不修改服务器状态）。
   • 支持查询参数（Query Parameters）进行过滤、分页、排序等。
   • 示例：
     • GET /users→ 获取用户列表
     • GET /users/123→ 获取 ID 为 123 的用户
     • GET /articles?tag=rest&limit=20&page=2→ 分页查询带标签的文章
   • 注意：GET 请求应可缓存，长度有限制（通常 < 2048 字符）。

2. POST

   • 用于创建新资源，或执行非幂等的复杂操作（如触发流程）。
   • 请求体（Body）携带新资源数据。
   • 示例：
     • POST /users→ 创建新用户，返回 201 + Location 头部指向新资源 URI
     • POST /orders/123/pay→ （不推荐）触发支付（更推荐用资源方式设计）
   • 注意：多次相同 POST 会创建多个资源（非幂等）。

3. PUT

   • 用于全量替换资源：如果资源不存在则创建（有时称为“upsert”），如果存在则完全替换。
   • 客户端必须提供资源的完整表示（缺失字段通常会被置为 null 或默认值）。
   • 示例：
     • PUT /users/123→ 用请求体完全替换 ID 为 123 的用户
   • 注意：多次相同 PUT 结果相同（幂等）。

4. PATCH

   • 用于部分更新资源：只修改请求体中提供的字段，其他字段保持不变。
   • 常见格式：JSON Patch（RFC 6902）、JSON Merge Patch（RFC 7396）或自定义对象。
   • 示例：
     • PATCH /users/123→ Body:{ "name": "新名字" }只改名字
   • 注意：幂等性取决于实现（JSON Merge Patch 是幂等的，某些自定义方式不是）。

5. DELETE

   • 用于删除资源。
   • 通常不需要请求体，可选返回被删除的资源表示。
   • 示例：
     • DELETE /users/123→ 删除 ID 为 123 的用户
   • 注意：多次相同 DELETE 结果相同（幂等），可返回 204 No Content。

3. 其他不常用但有用的 HTTP 方法

4. 安全（Safe）与幂等（Idempotent）的含义

• 安全方法：不会改变服务器状态（只读）。只有GET和HEAD是安全的。
• 幂等方法：多次执行效果与一次相同。GET、PUT、DELETE、HEAD、OPTIONS是幂等的，POST 和 PATCH通常不是（PATCH 取决于具体实现）。

幂等性对网络重试、缓存、负载均衡非常重要。

5. 实际案例对比

假设资源是用户（/users/123）：

6. 总结口诀

“查用 GET，增用 POST，全改 PUT，部分 PATCH，删用 DELETE”

正确使用 HTTP 方法是设计优秀 RESTful API 的基础，它能让你的接口更直观、更易维护，也更符合业界标准。如果你想看具体代码示例（如 Express、Spring Boot 中的路由定义）或其他进阶话题（如批量操作如何选择方法），随时告诉我！