Go JSONPatch JSON Patch 的 test 失败后怎样处理整次更新

Go JSONPatch 里的 JSON Patch test 失败时，最稳妥的处理不是继续写入后面的操作，而是把这次 Apply 当作失败更新：保留原文档，丢弃返回结果，并把错误交给上层决定重读、提示冲突或重试。test 只负责比较文档中的值；它不会替你回滚已经写入数据库的外部副作用。

官方地址：https://github.com/evanphx/json-patch

这个库同时支持 RFC 6902 JSON Patch 和 RFC 7396 JSON Merge Patch。本文只讨论 JSON Patch 的 test 操作，以及 test 失败后怎样保证“整次更新”不被部分提交。

背景：test 是前置条件，不是补丁回滚器

一个 JSON Patch 是按数组顺序解释的一组操作。test 会读取 path 指向的值，与操作里的 value 做结构比较；路径不存在或值不相等，当前操作就失败。它很适合表达“只有版本仍为 7 时才允许修改”这类乐观并发条件。

容易误解的地方是：test 不是数据库锁，也不是对外部 API 的撤销协议。它只能观察传给 Apply 的 JSON 文档。真正的整次更新边界，要由调用代码决定：只有 err == nil 时才把新文档交给持久化层。

旧写法的问题：先改状态，再判断 test 错误

错误的思路通常是把 patch 拆成若干操作，先把前面的 replace 写入数据库，遇到后面的 test 失败再补偿。这样一来，补偿逻辑必须知道每个字段的旧值，还要处理并发写入；一旦中途发生网络或事务错误，就很难保证原文档被完整恢复。

在 evanphx/json-patch 中，Apply 先解析输入文档，再按顺序处理各个操作；任一操作返回错误时，调用方拿到的是错误，不应把一个“不完整的新文档”当成成功结果。这个语义更适合“先在内存形成候选结果，再一次性提交”。

新规则：把 test 放在变更操作之前

下面的补丁把 /version 作为并发前置条件。JSON 块保持严格有效，字段含义直接写在代码块旁边：op 是操作类型，path 是 JSON Pointer 路径，value 是期望值。

[
  {"op":"test","path":"/version","value":7},
  {"op":"replace","path":"/status","value":"ready"},
  {"op":"replace","path":"/version","value":8}
]

如果当前文档的 version 不是 7，第一项就失败，后面的状态和版本替换不会成为可提交结果。如果版本匹配，才继续形成版本为 8 的候选文档。把判断放在前面，能让冲突尽早暴露，也避免在一次 Apply 中先做大量无意义变更。

package main

import (
    "fmt"

    jsonpatch "github.com/evanphx/json-patch/v5"
)

func applyWholeUpdate(original, patchJSON []byte) ([]byte, error) {
    // 先解析整组 RFC 6902 操作，解析失败时不进入持久化流程。
    patch, err := jsonpatch.DecodePatch(patchJSON)
    if err != nil {
        return nil, fmt.Errorf("decode patch: %w", err)
    }

    // Apply 只生成候选文档；只有无错误的结果才允许交给存储层。
    updated, err := patch.Apply(original)
    if err != nil {
        return nil, fmt.Errorf("apply patch rejected: %w", err)
    }
    return updated, nil
}

这里的关键不是把错误文字改成“部分成功”，而是让调用方把 updated 和错误路径分开：错误分支保留 original，成功分支才进入事务或版本条件写入。

兼容注意：Apply 成功不等于数据库已经安全提交

Apply 的成功只说明输入 JSON 能按这组操作得到新文档。若原文档来自数据库，仍然要把“读取当前版本、应用 patch、按版本条件写回”放进同一个事务，或者使用带版本条件的单条更新。否则两个请求都可能读取版本 7，各自通过本地 test，最后后写入者覆盖先写入者。

错误分支建议按三类处理：路径不存在或值不相等，返回并发冲突；补丁 JSON 解析失败，返回客户端格式错误；持久化失败，回滚事务并保留原始文档。不要在 test 失败后自动删改已经写入的字段，因为这会把补偿责任扩散到每个业务操作。

采用建议：把“候选结果”和“提交结果”分成两层

工程上可以固定成四个动作：先读取带版本的原文档；让 test 检查版本或业务前置条件；调用一次 Apply 生成候选 JSON；在事务或条件更新中提交候选 JSON。任何一步失败都返回错误，不把候选文档当作已生效状态。

如果业务还需要通知消息、缓存刷新或搜索索引更新，应在数据库提交成功后再发出，或使用 outbox 记录待发送事件。这样即使 test 失败，外部系统也不会收到一条与数据库状态不一致的“更新成功”消息。

相关问题

test 失败后能不能继续执行后面的 replace？

不应继续把这组 patch 当成成功更新。Apply 已经返回错误时，调用方应丢弃候选结果；如果确实要执行另一组规则，应重新读取文档并生成新的 patch。

test 能不能代替数据库乐观锁？

不能。它能检查传入 JSON 的版本字段，但不能单独保证数据库写回时版本仍未变化。最终提交仍需要事务、条件更新或数据库原生版本控制。

为什么不手动回滚前面的 replace？

因为手动补偿要维护每个操作的旧值，还会遇到并发和外部副作用。把 Apply 结果当作候选值，并只在成功事务中一次写入，边界更简单。

一句话总结：test 负责拒绝过期文档，Apply 负责生成候选文档，事务或条件写入负责决定整次更新是否真正生效。