PATCH 是什么
补丁方法对资源做局部修改，请求体是一份「补丁文档」，具体语义由媒体类型决定：有的格式描述如何合并字段，有的格式是一组增删改操作序列。它没有出现在最初的规范里，而是后来补充定义的，因此它到底是否幂等要看补丁内容——把字段设成固定值是幂等的，而在数组末尾追加元素则不是。需要整体覆盖时应当使用替换方法，两者语义不可互换。
基本信息
| 名称 | PATCH，定义见后续补充规范 |
|---|---|
| 作用 | 按补丁文档局部修改资源 |
| 幂等性 | 不保证；取决于补丁内容 |
| 媒体类型 | 决定补丁如何解释，必须显式声明 |
| 与替换方法区别 | 替换是整体覆盖，补丁是局部修改 |
典型使用场景
- 只改少量字段：用户资料里更新昵称或头像地址
- 精确控制数组：按索引增删元素而不是整体替换
- 状态机流转：只提交状态字段，避免提交必须带全量字段的接口
- 并发编辑：配合版本校验只提交差异部分
- 第三方部分更新：对方接口只接受差异字段的场景
补丁请求示例
补丁请求示例
curl -i -X PATCH https://api.example.com/users/101 \
-H 'Content-Type: application/merge-patch+json' \
-d '{"age":31}'
# 声明补丁类型很关键：用通用类型发送会被严格的接口拒绝
curl -i -X PATCH https://api.example.com/users/101 \
-H 'Content-Type: application/json-patch+json' \
-d '[{"op":"replace","path":"/age","value":31}]'常见补丁格式
| 媒体类型 | 用途 | 特点 |
|---|---|---|
| 合并式补丁 | 只给出要改的字段 | 实现简单，数组的处理规则需自行约定 |
| 操作序列补丁 | 按操作增删改特定路径 | 表达能力强，客户端实现成本高 |
| 简单字段更新 | 部分框架支持的表单式更新 | 兼容性好，语义较弱 |
使用要点
- 必须显式声明补丁媒体类型，否则严格的服务端会直接拒绝
- 需要整体覆盖时不要用补丁去模拟，未提及的字段在两种语义下结果完全不同
- 数组类字段尤其要明确约定：是整体替换还是追加，重复执行会给出不同结果
补丁是否幂等取决于内容：把字段设为固定值重复执行结果一致；而「在数组末尾追加一项」这类补丁重复执行会不断追加，因此不能对它做自动重试。
在需要清空字段的场景误用合并式补丁会失效：合并语义里「未提及」与「设为空」往往等价，无法表达「我要把这个字段删掉」，此时应当使用操作序列格式或换用替换方法。