HTTP 条件写入:用 ETag、If-Match 与数据库版本防止覆盖
本文目录
两个管理员都打开版本 7。甲先改标题并保存,乙随后用旧正文保存;接口两次都返回成功,甲的标题却消失了。这不是给按钮加 loading 就能解决的问题:按钮只能约束一个页面,服务端仍需拒绝基于旧版本的覆盖。
本篇讨论“更新已存在资源”的并发协议。创建订单的去重、失败任务重投属于幂等设计,不要把它们和版本冲突混成一种机制。
三个版本要分开
| 层次 | 保存什么 | 解决的问题 |
|---|---|---|
| 页面草稿 | 用户此刻正在输入的内容 | 保存响应不能抹掉新输入 |
| 读取基线 | 打开或成功保存时的 ETag | 告诉服务端本次编辑从哪里开始 |
| 数据库版本 | 每次成功变更递增的 revision | 通过原子条件防止同时覆盖 |
甲、乙都读到相同基线后,只有一个写入能让 revision 从 7 变成 8。另一个请求应该返回冲突并保留草稿,不能偷偷把它的基线更新为 8 后自动再写一次。
读取与写入契约
读取响应可使用下列契约:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-store
ETag: "article-42-r7"
{"id":"42","title":"原始标题","body":"正文","revision":7}
客户端保存时原样携带带引号的标签:
PUT /api/articles/42
If-Match: "article-42-r7"
Content-Type: application/json
{"title":"新标题","body":"新正文"}
If-Match 使用强比较;带 W/ 前缀的弱标签不能充当这里的精确版本令牌。正式实现还要按 HTTP 语法处理标签列表和星号,不能随便去掉引号再比较字符串。RFC 9110 的 If-Match 规则与 MDN If-Match给出了协议语义。
这个管理接口可以明确要求客户端必须提交读取时拿到的单个强标签;若只支持这一子集,应对其他形式明确拒绝,不能把不认识的值当成“没有限制”。缺少必要前置条件可返回 428,版本不匹配返回 412。业务状态不允许修改则另用业务错误,不把所有失败都叫版本冲突。
原子更新才是最后一道门
先 SELECT 比较版本,然后无条件 UPDATE,中间仍然存在竞态。应把所有修改入口统一为条件写入;后台、定时任务、导入和恢复历史版本都不能绕过。
UPDATE articles
SET title = $1,
body = $2,
revision = revision + 1,
updated_at = now()
WHERE id = $3
AND owner_id = $4
AND revision = $5
AND deleted_at IS NULL
RETURNING id, title, body, revision;
参数分别来自已校验的正文、路由 ID、已认证身份以及已验证的版本令牌。owner_id 不能直接信任请求体。多角色或多租户应用应替换为实际的授权条件,不能简单删除它来支持管理员。
返回零行表示本次条件更新没有成功;在完成必要的资源可见性检查后,给出不泄露隐藏资源的失败响应。需要区分“已删除”和“被更新”时,可在授权范围内重新读取,但它只是帮助解释失败,不能变成无条件重试依据。
PostgreSQL RETURNING允许在写入语句中取得结果。示例只返回必要字段,不把权限配置、密文或内部审计信息一并返回。
若写入还要生成历史记录,应在同一个事务内完成条件更新和历史快照插入;快照失败就回滚更新。若提交后还需发邮件或触发索引,用事务 Outbox处理,不把外部网络等待放进长事务。
ETag 和响应内容必须一致
用 revision 构造强标签有一个前提:同一个资源、同一种表示、同一个 revision 的响应内容不会悄悄变化。若正文变化却没有递增版本,这个协议失去意义;若不同语言或权限返回不同投影,标签也必须区分对应表示。
不能一边给完整正文发强标签,一边在同一版本下动态插入当前时间等变化字段。也不要用秒级 updated_at 代替严格递增版本:同一秒内两次修改可能得到一样的值。使用时间字段时至少要确认数据库精度和实际并发语义,版本整数通常更容易解释。
跨域前端要能读取 ETag,并允许发送 If-Match;这涉及 CORS 的暴露响应头与预检配置。即便允许了这些头,身份认证和资源权限仍必须独立检查,令牌从来不是访问凭据。
浏览器如何处理 412
先保留本地草稿,再取得最新的服务器版本,向用户展示“打开时版本、本地修改、服务器最新版本”的差异。只提供“再点一次保存”会诱导覆盖。
一种实用流程是:
- 读取时保存 baseContent 和 baseETag。
- 编辑得到 localContent;提交时捕获不可变快照。
- 成功后更新保存基线。若用户在请求期间继续输入,保留当前输入并继续标记未保存。
- 收到 412 后进入冲突状态;加载最新内容仅用于对比,不立即 reset 表单。
- 用户确认合并后,以最新 ETag 提交新的合并结果。
这属于三方合并思路,不必一开始就做完整 Git。先准确列出冲突字段、保留本地副本、允许复制或下载草稿,已经比静默覆盖可靠得多。表单与草稿分工讨论页面内的状态边界。
保存成功但响应丢了怎么办
网络超时并不证明事务没有提交。此时用旧 ETag 原样再写,通常会得到 412;它保护数据,却不能直接告诉用户第一次是否成功。
可以重新读取授权资源,比较持久化结果与提交快照;有业务命令 ID 时查询命令执行记录。涉及不可重复的外部副作用,还要引入幂等键和服务端结果记录。不要看到超时就换成最新 ETag 无条件重发,否则保护机制被客户端自己绕开。
可重复的验收
用两个独立客户端同时读取相同版本,控制两个保存请求在服务端交错到达;断言恰有一个更新成功、版本只增加一次、历史只新增一份。再覆盖缺头、弱标签、错误资源令牌、资源删除、无权限、历史插入失败以及提交成功后断网。
前端还要测保存期间继续输入、收到 412 后切页、退出账号、合并后再次冲突。测试目标是草稿和持久化数据都没有被误覆盖,不是只看到一个红色提示。
版本说明:示例为 PostgreSQL 参数化 SQL 与 HTTP 更新协议设计,不代表某个现有项目已经部署了此机制。应按项目当前数据库、代理层和表示序列化规则实现。
留言提交后直接公开,请友善交流。