HTTP 与 Web 标准 / 系统课时

使用 PUT PATCH DELETE

使用 PUT PATCH DELETE

更新和删除接口最常见的问题,是把 PUT、PATCH、DELETE 都当成“改数据”的不同写法。本节把三者映射到资源目标状态,说明整体替换、局部修改和删除各自的语义、幂等性与常见响应方式。

学习目标

  • 判断整体替换、局部更新和删除分别应使用哪种方法
  • 理解 PUT、PATCH、DELETE 的幂等性差异
  • 根据操作结果选择常见的成功状态码并识别重复请求边界

三个方法表达三种资源意图

PUT 表示把目标 URI 的资源状态设置为请求所携带的表示,常用于整体替换;PATCH 表示只应用一组局部修改;DELETE 表示移除目标资源与当前功能之间的关联,至于底层是物理删除还是软删除,由服务端实现决定。

方法 典型意图 请求体 幂等语义
PUT 整体替换,或在允许时创建指定 URI 的资源 通常包含客户端负责字段的完整目标表示 是
PATCH 对资源应用局部修改 包含变更文档 不保证
DELETE 删除目标资源的有效关联 通常不需要 是

幂等关注的是“重复执行后的目标状态”,不是“每次响应必须完全相同”。例如第一次 DELETE 返回 204,第二次因为资源已不存在返回 404,仍不妨碍 DELETE 在语义上属于幂等方法。

PUT 与 PATCH 的边界

PUT 适合客户端知道并提交它所负责的完整目标表示。服务器生成的 ID、创建时间等只读字段不需要客户端伪造;真正重要的是,遗漏可写字段是否会被视为恢复默认值、清空或拒绝请求,必须由 API 合约说明。

PATCH 只提交变化本身,更适合修改少数字段。PATCH 并不天然幂等:某些补丁是“把名字设置为 X”,重复执行结果相同;另一些补丁可能是“数组尾部追加一个元素”,重复执行就会产生不同状态。

如果采用 JSON Merge Patch,通常使用 application/merge-patch+json;如果采用 JSON Patch,则使用 application/json-patch+json。两者的文档结构和 null 含义不同,客户端不能只看 PATCH 方法名就猜格式。

一个资源上的三种请求

以下为片段示例,假设服务定义了 /users/42,用户包含 name 与 email 两个客户端可写字段,并约定 PATCH 使用 JSON Merge Patch。报文用于展示方法与资源意图的对应关系,不代表公共服务的真实接口。

http
PUT /users/42 HTTP/1.1
Host: api.example.test
Content-Type: application/json

{"name":"Lin","email":"lin@example.test"}

PATCH /users/42 HTTP/1.1
Host: api.example.test
Content-Type: application/merge-patch+json

{"email":"new@example.test"}

DELETE /users/42 HTTP/1.1
Host: api.example.test

预期结果是:PUT 把客户端负责的用户表示设置为给定目标状态;PATCH 只把 email 改为 new@example.test;DELETE 让 /users/42 不再表示一个可用用户资源。若 API 支持通过 PUT 创建指定 URI,资源原本不存在时也可以返回 201 Created。

状态码要反映实际结果

已有资源被 PUT 或 PATCH 成功更新时,服务器可以返回 200 OK 并携带结果表示,也可以在无需响应体时返回 204 No Content。如果 PUT 按合约创建了新资源,使用 201 Created 更准确。

DELETE 成功且没有响应体时常用 204 No Content;如果需要返回删除结果或异步任务信息,可以选择其他符合接口合约的成功状态码。资源不存在时可以返回 404 Not Found,业务冲突可使用 409 Conflict。

更新接口还要考虑并发覆盖

即使方法选对了,两个客户端同时读取并更新同一资源仍可能造成“后写覆盖先写”。需要保护关键数据时,可以让服务器返回 ETag,客户端更新时发送 If-Match;版本不一致则拒绝写入,而不是静默覆盖。

因此,方法选择解决的是请求语义:PUT 设定整体目标状态,PATCH 应用局部变化,DELETE 移除资源。真正可靠的更新接口还需要把字段规则、补丁格式、状态码和并发条件写进 API 合约,客户端才能稳定重试和处理失败。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用 PUT PATCH DELETE

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

登录哪都通