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 文件並產生修補內容。
- 把原始 JSON 貼到左邊。
- 把修改後的 JSON 貼到右邊。
- 按下「產生」,然後複製修補內容。
常見問題
這個工具會上傳我的資料嗎?
不會。兩份文件都留在你的瀏覽器裡,修補內容在你自己的電腦上產生。
輸出符合 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