HTTP/1.1 9 种请求方法实战：从 CRUD 到 RESTful API 设计的 3 个关键映射

HTTP/1.1 请求方法实战从 CRUD 到 RESTful API 设计的 3 个关键映射在构建现代 Web 应用时HTTP 协议作为应用层通信的基础其请求方法的设计直接影响着 API 的清晰度和可维护性。本文将深入探讨如何将 HTTP/1.1 的 9 种请求方法与数据库 CRUD 操作和 RESTful 设计原则进行实战映射帮助开发者构建更规范的 API 接口。1. HTTP 方法与 CRUD 操作的核心映射HTTP 协议定义了一组标准方法每种方法都有其特定的语义和用途。理解这些方法与数据库基本操作CRUD的对应关系是设计 RESTful API 的第一步。1.1 基础方法对照表HTTP 方法CRUD 操作语义描述幂等性GETRead获取资源是POSTCreate创建新资源否PUTUpdate完整替换现有资源是PATCHUpdate部分修改现有资源否DELETEDelete删除指定资源是幂等性说明一个方法如果多次执行产生的结果与单次执行相同则称为幂等方法。这在网络请求重试等场景中尤为重要。1.2 特殊用途方法解析除了基础的 CRUD 对应方法外HTTP 还定义了几种特殊用途的方法HEAD与 GET 类似但只返回响应头不返回实体主体。常用于检查资源是否存在验证缓存有效性通过 Last-Modified 或 ETagHEAD /users/123 HTTP/1.1 Host: api.example.comOPTIONS获取目标资源支持的通信选项。在 CORS 预检请求中扮演重要角色OPTIONS /users HTTP/1.1 Host: api.example.com Access-Control-Request-Method: POST Access-Control-Request-Headers: Content-Type响应示例HTTP/1.1 200 OK Allow: GET, POST, OPTIONS Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: Content-TypeTRACE用于诊断回显服务器收到的请求。注意生产环境应禁用此方法以防止安全风险。CONNECT用于建立隧道连接主要在 HTTPS 代理场景使用。2. RESTful API 设计的三层映射RESTful 架构风格强调资源的表现层状态转移。要实现良好的 RESTful 设计需要建立从 URI 到 HTTP 方法再到业务操作的三层映射关系。2.1 资源URI设计规范RESTful API 的核心是资源导向URI 设计应遵循以下原则使用名词而非动词表示资源正确/users错误/getUsers层级关系表达/集合/元素/子集合/子元素 示例/users/123/orders/456版本控制建议URI 路径中/v1/users自定义头中Accept: application/vnd.example.v1json2.2 方法到操作的完整映射示例以用户管理系统为例展示完整的 API 设计用户资源操作HTTP 方法URI状态码获取用户列表GET/users200 OK创建新用户POST/users201 Created获取单个用户GET/users/{id}200 OK 或 404 Not Found全量更新用户PUT/users/{id}200 OK 或 204 No Content部分更新用户PATCH/users/{id}200 OK删除用户DELETE/users/{id}204 No Content订单子资源操作HTTP 方法URI状态码获取用户所有订单GET/users/{id}/orders200 OK创建用户新订单POST/users/{id}/orders201 Created获取特定订单详情GET/users/{id}/orders/{orderId}200 OK2.3 状态码使用指南正确的状态码返回是 RESTful API 的重要组成部分2xx 成功200 OK通用成功状态201 Created资源创建成功204 No Content成功但无内容返回4xx 客户端错误400 Bad Request请求参数错误401 Unauthorized需要认证403 Forbidden无权限访问404 Not Found资源不存在405 Method Not Allowed方法不允许5xx 服务端错误500 Internal Server Error通用服务端错误503 Service Unavailable服务不可用3. 创建与更新操作的高级决策在实际 API 设计中POST、PUT 和 PATCH 的选择常常引发讨论。本节将提供清晰的决策框架。3.1 POST vs PUT 创建决策POST 创建资源的特点客户端不知道最终资源标识符服务端决定资源存储位置典型响应HTTP/1.1 201 Created Location: /users/123PUT 创建资源的特点客户端指定资源标识符必须是幂等操作典型响应HTTP/1.1 201 Created (首次创建) 或 HTTP/1.1 200 OK (后续更新)决策树是否由客户端指定资源ID? ├── 是 → 使用PUT └── 否 → 使用POST3.2 PUT vs PATCH 更新决策PUT 全量更新示例PUT /users/123 HTTP/1.1 Content-Type: application/json { name: 新用户名, email: newexample.com, age: 30 }注意未包含的字段可能被置为nullPATCH 部分更新示例JSON Merge PatchPATCH /users/123 HTTP/1.1 Content-Type: application/merge-patchjson { email: updatedexample.com }PATCH 部分更新示例JSON PatchPATCH /users/123 HTTP/1.1 Content-Type: application/json-patchjson [ { op: replace, path: /email, value: updatedexample.com } ]决策树是否需要保留未指定字段的现有值? ├── 是 → 使用PATCH └── 否 → 使用PUT3.3 批量操作的特殊处理对于批量操作可以采用以下模式批量创建POST /users/bulk HTTP/1.1 Content-Type: application/json [ { name: 用户1, email: user1example.com }, { name: 用户2, email: user2example.com } ]批量更新PATCH /users/bulk HTTP/1.1 Content-Type: application/json-patchjson { operations: [ { op: replace, path: /1/email, value: newexample.com }, { op: remove, path: /2/age } ] }4. 实战中的边界情况处理即使遵循了所有规范实际开发中仍会遇到需要特殊处理的场景。4.1 非CRUD操作的处理对于如激活用户、重置密码等非CRUD操作推荐以下处理方式作为子资源动作POST /users/123/activate使用自定义动词谨慎使用POST /users/123?actionactivate作为字段更新PATCH /users/123 Content-Type: application/json { status: active }4.2 并发控制策略处理资源并发修改的常用方法Last-Modified If-Unmodified-SinceGET /users/123 HTTP/1.1 200 OK Last-Modified: Wed, 21 Oct 2025 07:28:00 GMT PUT /users/123 If-Unmodified-Since: Wed, 21 Oct 2025 07:28:00 GMTETag If-MatchGET /users/123 HTTP/1.1 200 OK ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4 PUT /users/123 If-Match: 33a64df551425fcc55e4d42a148795d9f25f89d44.3 异步操作处理对于耗时操作可采用异步模式立即返回202 AcceptedHTTP/1.1 202 Accepted Location: /queue/12345 Retry-After: 120客户端轮询状态GET /queue/12345 HTTP/1.1 200 OK { status: processing, progress: 60, estimated_completion: 2025-10-21T08:00:00Z }或使用WebHook回调机制。