PUT 与 PATCH

这两种方法都会修改现有资源，区别在于请求体的含义。PUT 请求体代表完整的新状态：原则上，省略的字段会被移除或重置。PATCH 请求体则描述了更改内容，格式由服务器决定——可以是部分对象，也可以是操作列表（例如 JSON Patch）。

工作原理

根据定义，PUT 请求是幂等的：发送两次相同的完整表示会得到相同的结果。而 PATCH 请求则不一定幂等，因为像"append to this list"或"increment"这样的操作，执行两次与执行一次的结果不同。这就是为什么 PATCH 请求尤其需要 If-Match 机制的原因：它可以拒绝重试的 PATCH 请求，而不是重复发送。

误解

这个 PATCH 请求实际上就是"PUT without the fields you did not change" 。很多 API 都这样实现，但方法本身并没有明确说明——合并式的 PATCH 请求和 JSON PATCH 文档都是 PATCH 请求，但语义截然不同。而且很多"PUT"接口实际上会进行合并而不是替换，所以务必测试一下你的接口在缺少某个字段的情况下会如何操作。

点击这里试试

Pizza API 接受对 PATCH /pizza/v1/orders/{id}的部分更新，而 Protocol Lab 接受对 PATCH /protocol/v1/documents/{id}的 RFC 6902 JSON Patch；字符 PUT 端点替换并检查 If-Match。

相关内容

• What JSON Patch is
• 安全且等效的方法

资料来源

• HTTP semantics — RFC 9110
• HTTP caching — RFC 9111

其他术语

• JSON补丁 — 用于将 JSON 文档的更改描述为操作列表的标准格式 (RFC 6902)。
• 安全且等效的方法 — HTTP 方法的两个独立属性决定了客户端可以重试哪些方法。
• ETag — 用于表示形式的不透明版本标识符，用于避免重新发送该表示形式并检测冲突的写入。
• 重试后 — 响应头告诉客户端在重试之前要等待多长时间，以秒或日期为单位。
• 指数退避 — 一种重试策略，其中每次等待时间都比上一次更长，并添加随机性，以防止客户端同步重试。
• 请求超时 — 客户端在放弃请求之前等待响应的最长时间。

阅读英文版

所有术语 · 测试技巧 · 全部 39 个模拟 REST API

最后更新时间 2026年10月16日