计算机网络 / 系统课时

使用 PATCH 局部更新

使用 PATCH 局部更新

PATCH 用于只提交资源中需要变化的部分,适合资料编辑、状态切换和少数字段修改。它与 PUT 的差别不只是“请求体更短”:PATCH 的请求体描述一次局部修改,而 PUT 通常提交目标资源的完整表示;PATCH 本身也不保证幂等。

学习目标

  • 判断局部字段修改何时应使用 PATCH。
  • 使用 JSON Merge Patch 写出可执行的局部更新请求。
  • 识别 PATCH 的幂等边界,并避免把“增量操作”误当成可重复请求。

局部更新只表达变化部分

假设 /users/42 有 name、email、role 三个字段,现在只修改邮箱。使用 PATCH 时,请求可以只携带 email,没有出现的 name 与 role 保持原值。这样客户端不必先拿到完整资源再原样回传未修改字段。

操作 请求重点 未提交字段
PUT 完整目标表示 可能被替换、清空或拒绝
PATCH 局部修改内容 通常保持不变
POST 创建或触发处理 由目标端点定义

PATCH 的具体语法由媒体类型决定。常见方案包括 JSON Merge Patch 的 application/merge-patch+json 和 JSON Patch 的 application/json-patch+json;两者格式不同,客户端不能只写 application/json 就默认服务器理解某一种补丁规则。

使用 JSON Merge Patch 修改字段

下面假设接口明确支持 JSON Merge Patch。请求只修改 email,其他字段不发送,因此保持原值。<PORT> 替换为实际服务端口。

bash
curl --http1.1 -i -X PATCH "http://localhost:<PORT>/users/42" -H "Content-Type: application/merge-patch+json" --data '{"email":"new@example.com"}'

预期输出:

text
HTTP/1.1 200 OK
Content-Type: application/json

{"id":42,"name":"Lin","email":"new@example.com","role":"editor"}

在 JSON Merge Patch 中,成员值设为 null 通常表示删除该成员,而不是“把它保持不变”。因此 {"email":null} 与“不提交 email”含义不同;是否允许删除还要服从服务端字段约束。

PATCH 不天然保证幂等

HTTP 没有把 PATCH 定义为幂等方法。一个“把邮箱设置为固定值”的 Merge Patch,重复执行通常得到相同最终状态;但“余额增加 10”“计数器加 1”这类操作每执行一次都会改变结果,因此不是幂等更新。

如果接口需要可安全重试,优先把补丁设计成“设置到某个明确值”,例如把 status 设置为 disabled,而不是“切换 status”。对于付款、扣库存等不能重复执行的业务,还应使用业务幂等键或条件请求,而不能仅凭 PATCH 方法本身判断是否可重试。

选择 PUT 还是 PATCH

可以用一个简单判断:客户端是否掌握资源更新后的完整目标状态。若答案是“是”,例如配置编辑器一次提交完整配置对象,PUT 更直接;若答案是“否,只改两个字段”,PATCH 能减少无关字段传输,也降低覆盖其他并发修改的概率。

即使使用 PATCH,并发冲突仍可能发生。例如两个人同时修改同一个字段,后到请求仍可能覆盖先到结果。需要严格并发控制时,同样可以配合 ETag、If-Match 或业务版本号;方法选择解决的是更新语义,版本检查解决的是并发一致性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 PATCH 局部更新

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通