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" 不会被破坏。
{ "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 是本页的开关,默认是开的。要符合规范就关掉它。