计算机网络 / 系统课时
使用 PUT 替换资源
使用 PUT 替换资源
PUT 用于把目标资源写成客户端提交的完整表示,常见于“我知道资源地址,并希望它最终就是这个样子”的接口。理解它的关键是完整替换与幂等:同一请求重复发送,目标资源的最终状态应保持一致,而不是每次叠加变化。
学习目标
- 判断一个更新场景是否适合使用 PUT。
- 写出一次完整资源替换请求,并根据状态码验证结果。
- 区分“幂等”与“每次响应完全相同”这两个概念。
完整替换意味着什么
假设 /users/42 当前保存 name、email、role 三个可写字段。若接口约定 PUT 接收完整表示,那么客户端更新邮箱时也应提交其余可写字段;遗漏字段可能被清空、恢复默认值,或直接被服务器拒绝,具体规则必须由接口契约明确说明。
| 当前资源 | PUT 请求体 | 替换后 |
|---|---|---|
name=Lin |
name=Lin |
name=Lin |
email=old@example.com |
email=new@example.com |
email=new@example.com |
role=editor |
role=editor |
role=editor |
不要把 PUT 当成“只改提交的字段”。如果服务端实际上只更新出现的字段,那是接口自定义行为,语义更接近局部更新,应在文档中明确,避免客户端误删数据。
发出一次可验证的 PUT 请求
下面假设服务端提供 PUT /users/42,并要求完整提交三个可写字段。<PORT> 是实际服务端口;若接口需要鉴权,再按文档加入 Authorization 请求头。
curl --http1.1 -i -X PUT "http://localhost:<PORT>/users/42" -H "Content-Type: application/json" --data '{"name":"Lin","email":"new@example.com","role":"editor"}'预期输出:
HTTP/1.1 200 OK
Content-Type: application/json
{"id":42,"name":"Lin","email":"new@example.com","role":"editor"}有些接口更新成功后返回 204 No Content,这种情况没有响应体;若该资源原先不存在且服务器允许 PUT 创建它,则常见状态码是 201 Created。状态码选择由接口实现决定,但更新后资源状态应符合提交的表示。
幂等性看最终资源状态
幂等不等于“服务器只处理一次”,而是同一个 PUT 请求执行一次或多次,目标资源的最终状态等价。例如连续发送三次完全相同的请求,name、email、role 不应因为重复调用而继续累加或变化。
如果一次 PUT 把 loginCount 从 5 改成 6,重复请求后仍应是 6;若服务端每收到一次就执行 loginCount = loginCount + 1,最终变成 7、8,这就破坏了 PUT 的幂等语义。审计日志增加三条并不必然破坏幂等,因为判断重点是目标资源的语义状态。
处理并发更新与版本冲突
完整替换有一个常见风险:客户端 A 读取旧资源后修改邮箱,客户端 B 随后修改角色;如果 A 最后用旧版本完整 PUT,可能把 B 的角色修改覆盖掉。实际接口可用 ETag 与 If-Match 做条件更新,检测“我修改的是否仍是刚才读到的版本”。
例如资源返回 ETag: "v7" 时,客户端更新可带上 If-Match: "v7"。若资源已被别人改成新版本,服务器可返回 412 Precondition Failed,客户端重新读取后再决定如何合并。PUT 适合客户端掌握完整目标状态的场景;只掌握少数字段变化时,PATCH 通常更自然。