Free Online Developer Tools - ULID, UUID, NanoID, CUID, Snowflake ID, JWT Decoder, Base64, JSON Formatter & More

工具菜单

JSON Patch

在浏览器中应用 RFC 6902 JSON Patch。查看 add、remove、replace、move、copy 和 test,包括 JSON Pointer 转义以及数组下标如何移动。

JSON Patch

Apply RFC 6902 JSON Patch operations to transform JSON documents.

Runs locally
JSON
Ln 1, Col 10 B
Empty
JSON
Ln 1, Col 10 B
Empty
JSON
Ln 1, Col 10 B
Empty

JSON Patch 是什么

JSON Patch(RFC 6902)是一组操作,用来把一份 JSON 文档变成另一份。每个操作有 op 和 path。path 是 JSON Pointer(RFC 6901):从根开始、用斜杠分隔的路径。六种操作是 add、remove、replace、move、copy 和 test。

列表有顺序。后面的操作看到的是前面的操作改过的文档。test 不修改文档。它检查某个位置当前是否等于期望值。接口用它来拒绝补丁:如果别人已经改过这个字段,补丁就不该再写上去。

本页在你的浏览器里应用补丁。文档和补丁都不会上传。

指针如何指向一个值

空指针 "" 表示整份文档。"/name" 是 name 成员。"/tags/0" 是数组的第一个元素,从 0 开始数。add 里的 "/tags/-" 表示追加到末尾。键名里的 "~" 写成 "~0",键名里的 "/" 写成 "~1"。先解码 "~1" 再解码 "~0",本页就是这样做的,因此键名里真正的 "~1" 不会被破坏。

键 a/b 写成 /a~1b。键 c~d 写成 /c~0d。
{ "op": "add", "path": "/a~1b", "value": 1 }
{ "op": "remove", "path": "/c~0d" }

一份可跟着算的补丁

从下面的文档开始。test 确认 name 仍是 Ada。replace 改掉名字。带 "/tags/-" 的 add 追加 snowflake,数组变成 ["ulid", "uuid", "snowflake"]。add 创建 address.country。随后 remove "/tags/0" 删掉的是 ulid,因为下标指的是这一步当时的数组。结果是第三段。

文档
{
  "name": "Ada",
  "tags": ["ulid", "uuid"],
  "address": { "city": "Hanoi" }
}
补丁
[
  { "op": "test", "path": "/name", "value": "Ada" },
  { "op": "replace", "path": "/name", "value": "Ada Lovelace" },
  { "op": "add", "path": "/tags/-", "value": "snowflake" },
  { "op": "add", "path": "/address/country", "value": "VN" },
  { "op": "remove", "path": "/tags/0" }
]
结果
{
  "name": "Ada Lovelace",
  "tags": ["uuid", "snowflake"],
  "address": { "city": "Hanoi", "country": "VN" }
}

move、copy 和 test

move 删掉 from 上的值,再把它加到 path。copy 只加不删,源还在。把数组元素 move 到同一数组更靠后的下标很容易错,因为删除会让后面的元素前移。test 把当前值和 value 比较。不相等时,本页会停下来并报错,不会假装后面的操作已经生效。RFC 6902 要求任一操作失败则整个补丁失败。调用方应把结果当成要么全部成功,要么什么都没有。

什么时候用它

  • 你在写局部更新,想看到一份真实操作列表之后的文档,而不是在脑子里对 diff。
  • 你需要前置条件。把 test 放在前面,过期的客户端就不能覆盖已经变过的字段。
  • 你在 JSON Patch 和 JSON Merge Patch(RFC 7396)之间选择。Merge Patch 是一份局部文档:对象会合并,数组被整段替换,null 表示删除成员。它不能向数组追加,也不能表达 test。

常见坑

  • 数组下标会动。先删 /tags/0 再删 /tags/1,删掉的不是原来的第一项和第二项。第一次删除之后,原来的第二项已经在下标 0。
  • replace 要求路径已经存在。add 会创建缺少的对象成员,带 "-" 的 add 会追加。用 replace 写一个新字段会失败。
  • RFC 6902 的路径区分大小写。本页有 Ignore Case 选项,而且默认打开。它会掩盖一个写错的键。要符合规范时请关掉。
  • Strict Path Validation 是本页的选项,不属于 RFC。当你希望缺少的中间对象直接报错,而不是让 add 继续往下走时,把它打开。
  • 补丁不是可以随便重排的 diff。move 和 remove 依赖前面的步骤。不想手写时,用改前和改后的文档生成操作列表。

JSON Patch 和相邻格式

格式你发送的内容它做不到的事
JSON Patch(RFC 6902)有序的 op 对象列表没有隐式修改:每一处变化都是一条操作
JSON Merge Patch(RFC 7396)一份局部文档向数组追加,或测试前置条件。null 表示删除
JSON diff 视图两份完整文档它展示差异。除非把它变成补丁,否则它还不是要 POST 的正文

问题

/tags/- 是什么意思?

在 add 操作里,指针最后一段如果是单独的 -,表示追加到数组末尾。它不是名叫 "-" 的成员。在其他操作里,- 不是特殊下标。

为什么 remove 删错了数组元素?

每条操作看到的是上一条留下的文档。删除之后,后面的下标指向别的元素。先删较大的下标,或者根据更新后的文档重新生成补丁。

键名里有斜杠怎么写?

要转义。键名中的 / 变成 ~1,键名中的 ~ 变成 ~0。指针 /a~1b 指向成员 a/b。/c~0d 指向成员 c~d。

test 失败会回滚前面的操作吗?

在实现正确的服务器上,test 失败会拒绝整个补丁,包括写在它前面的操作。不要假设客户端可以留下一份改了一半的文档。把 test 放在前置条件必须成立的位置。

Ignore Case 属于 RFC 6902 吗?

不属于。JSON Pointer 的成员名必须逐字匹配。Ignore Case 是本页的开关,默认是开的。要符合规范就关掉它。

请作者喝杯咖啡,支持开发更多好用的工具