JSON Patch 生成器

比较两份 JSON 文档,得到把前者变成后者的 RFC 6902 补丁。全部在浏览器中运行。

这个工具做什么


它比较两份 JSON 文档,按 RFC 6902 定义的格式写出把前者变成后者的操作清单。不必为了说明一个字段变了而发送整份文档,你发送的就是改动本身。

什么时候用


用来构造 PATCH 请求的主体,用来记录配置文件两个版本之间改了什么,或者用来保存一份远比逐份完整副本小得多的审计记录。它也是一种快速手段,能查出两份看起来一样的文档究竟差在哪里。

它会生成哪些操作


操作含义
add在原本没有值的位置添加一个值,或者插入到数组中。
remove删除该位置上的值。
replace覆盖一个已经存在的位置上的值。
move把一个值从一个位置移到另一个位置。
copy把一个值复制到另一个位置。
test检查一个值,若不符则整个补丁作废。

这个工具只写 add、remove 和 replace。这三种足以表达任何改动,而一份能逐行读懂的补丁,比一份更短却要费神琢磨的补丁更有价值。另外三种同样属于 RFC 6902,符合规范的服务器都会接受。

路径是怎么回事


每个路径都是一个 JSON Pointer(RFC 6901):从文档根部开始、用斜杠分隔的一条路线,“/address/zipCode”指的是 address 里面的 zipCode 字段。数组位置用数字表示,所以“/skills/0”是第一项,而短横线表示数组末尾:“/skills/-”是追加。由于斜杠是分隔符,键名中若含有斜杠就写成 ~1,真正的波浪号写成 ~0。

关于输出的说明


比较是按字面进行的:逐个位置对比取值,因此在数组开头插入一项,会对后面每一项都产生一个 replace,而不是一次插入。对于带有稳定标识符的对象数组,按标识符生成的补丁总是比按位置生成的更小。

如何生成 JSON Patch


粘贴两份 JSON 文档并生成补丁。

  1. 把原始 JSON 粘贴到左边。
  2. 把修改后的 JSON 粘贴到右边。
  3. 点击“生成”,然后复制补丁。

常见问题


这个工具会上传我的数据吗?
不会。两份文档都留在你的浏览器里,补丁在你自己的机器上生成。

输出符合 RFC 6902 吗?
符合。每个操作都是一个带 op、path 的对象,add 和 replace 还带 value,而路径就是 RFC 6901 定义的 JSON Pointer。

它包含 move 和 copy 操作吗?
不包含。它只写 add、remove 和 replace,这三种足以表达任何改动,而且读起来容易得多。一次 move 不过是 remove 之后接一个 add。

补丁怎么应用?
把它发给接受 application/json-patch+json 的 API,或者用现成的库:Python 用 jsonpatch,JavaScript 用 json-patch,.NET 用 JsonPatchDocument,Java 用 json-patch,诸如此类。

它和 JSON Merge Patch 有什么区别?
JSON Merge Patch(RFC 7386)看起来就像文档本身,其中 null 表示“删除”。这让它易读,却无法保存一个真正的 null,也无法只改数组中的某一项。JSON Patch 更啰嗦,但什么都能表达。

Wikipedia — JSON Patch
Wikipedia — JSON
Wikipedia — Patch (computing)
Wikipedia — Diff
Wikipedia — REST