2.3 HTTP 方法语义：契约的动词
2.3 HTTP 方法语义：契约的动词
本节摘要：HTTP 方法为每种资源操作分配标准动词：GET 读、POST 建、PUT 整体替换、PATCH 局部改、DELETE 删。本节的钥匙是"安全"与"幂等"两个词——安全指不产生副作用，幂等指重复执行结果一致。用这两个维度一张表能推演出所有方法的正确用法，还能处置 202、409、PUT 与 PATCH 边界这类复杂场景。
学习目标
阅读完本节，你应当能够：
- 解释"安全"与"幂等"两个概念，并各举一个容易混淆的例子。
- 默写出 GET、POST、PUT、PATCH、DELETE 的安全与幂等属性。
- 判断 PUT 与 PATCH 分别适配"整体替换"与"局部修改"场景。
- 用 202、409 等状态码处理异步与冲突类复杂动作。
两个词把一张方法表端出来
方法语义不需要背张表，只需要抓住两个核心概念，其余全都能推出来。
- 安全（Safe）：这个请求不会改变服务器上的资源状态。读请求就是安全的，写请求通常不安全。
- 幂等（Idempotent）：同一请求无论执行一次还是一百次，产生的效果一样。注意是"效果"一样，不是"响应码"必须一样——第一次删成功返回 204，之后资源已不存在返回 404，状态码不同，但"资源都不存在"这个最终效果一致，所以 DELETE 仍是幂等的。
二、一张表亮出全部答案
把五个方法的安全与幂等属性铺开看：
对应到表格更精确：
| 方法 | 安全 | 幂等 | 典型用途 | 边界情形 |
|---|---|---|---|---|
| GET | 是 | 是 | 读取资源、列表、详情 | 别用 GET 做删改副作用 |
| POST | 否 | 否 | 创建资源、触发非幂等动作 | 重复提交会产生重复资源 |
| PUT | 否 | 是 | 客户端指定 URI 的整体替换 | 也可用于"按整份替换创建" |
| PATCH | 否 | 通常是 | 只改其中几个字段 | 部分更新，语义要写清 |
| DELETE | 否 | 是 | 删除资源 | 二次删除同样让资源不存在 |
三、PUT 与 PATCH：整体 vs 局部
这是工程师最爱踩的边界之一。
- PUT：客户端提交一份完整表示，服务器用它对目标资源做"整体替换"。字段全给我，我整个换掉。因为整份替换具有确定性，所以幂等。
- PATCH：客户端只提交"要改哪些字段"的补丁，服务器只动这些字段。因为描述的是"改动"，必须以明确的补丁格式（JSON Patch 或 JSON Merge Patch）给出，语义要写清楚。
举一个可运行的例子。用户资源现有字段是名字与邮箱。要改邮箱：
PUT /users/99 HTTP/1.1 Content-Type: application/json {"name":"Alice","email":"alice@new.com","phone":null}
PUT 要带齐整份表示（即便 phone 要清空也得显式给 null）。而 PATCH 只发要动的：
PATCH /users/99 HTTP/1.1 Content-Type: application/merge-patch+json {"email":"alice@new.com"}
同理，PUT 如果客户端只发了 email，服务器不该把它当成"只改邮箱"，而应理解为"用这一份替换整个用户"——这正是两者最大的分歧点。POST 创建也是容易混淆处：POST 不指定 URI，服务器自建；PUT 指定 URI，幂等地放置。
四、复杂动作的处置：202 与 409
现实接口常有"不是一次就成一件事"的动作，方法语义就要会牺牲。两个典型：
- 202 Accepted：动作正在异步处理，还没出最终结果。比如发起一个耗时的退款申请，先回 202，随后客户端轮询任务资源拿结果。它把"立即返回结果"的标准让渡给了异步流程。
- 409 Conflict：请求与资源当前状态冲突。比如并发下订单状态已从"待支付"被改成"已支付"，你又来一笔支付即冲突；或创建时撞了唯一键。语义上强调"当前状态不匹配"，而非参数错。
⚠️ 常见坑：拿 400 表达一切"客户端的问题"。一个具体方法是配合"请求幂等键"做重复提交防护：客户端带一个
Idempotency-Key头，服务器对同一 key 的重复 POST 返回首次结果而非再造一份。这让不幂等的 POST 在重试场景下变安全。
五、TRACE、OPTIONS、HEAD 怎么想
主方法之外的几个也别忽略：OPTIONS 让客户端获知资源支持哪些方法（CORS 预检也用它）；HEAD 只回头部不回首体，用来探活；用法不多但"健康检查到底该用哪种请求"就有讲究。它们的共同点是"不改变资源状态"，天然安全，幂等性也好，基本不会出治理事故。
💡 关键直觉：方法语义这一关，把"安全 + 幂等"二字吃透，就能回答八成"这里该用哪个方法"的疑问；剩下的二成，靠 202、409、幂等键这些补丁来兜。
补一句最容易被忽略的：安全与幂等是"语义承诺"，不是"实现保证"。一个团队在 GET 里干了写库的脏活，从权限看它仍是"安全"的宣言，行为却不安全——这在并发与缓存下迟早翻车。方法选型必须与后台业务对齐：GET 的处理器里做了状态变更，就该承认是 POST 的职责，别仗着"能通"就把它钉在 GET 上。契约的动词只表达"承诺做什么"，不做就是不守约。
本节要点回顾
- 要点一：安全的请求不改状态，幂等的请求重复执行效果一致。
- 要点二：GET 安全幂等，POST 都不满足，PUT 与 DELETE 不安全但幂等。
- 要点三：PUT 整体替换、PATCH 局部修改，边界语义要写清。
- 要点四：复杂异步动作用 202，状态冲突用 409。
- 要点五：POST 的重复提交用幂等键做防护。
- 要点六：方法语义与幂等维度的结论，是第 2.7 节重试与并发策略的直接输入。
动词分配完毕，接下来处理"请求自备干粮"的无状态条款——它决定了服务器能不能横向堆机器、扛并发。