避免 JSON Diff 錯誤最可靠的方式,是把這個工具視為結構變更檢查器,而不是文字編輯器、修補引擎或移動偵測器。JSON Diff 會把兩個嚴格的 JSON 值當作已解析的資料來比較,而不是當作格式化後的位元組,並在 RFC 6901 JSON Pointer 路徑上回報新增、移除、變更與型別變更的項目,因此讀者幾乎所有的錯誤,都來自於套用從其他類別工具借來的心理預期。這個工具刻意忽略空白與物件成員順序,因為依據 RFC 8259,真實的 JSON 物件是無序的成員集合;它也刻意以位置方式回報陣列,而不會自行猜測項目的身分。光是這個設計選擇,就排除了使用者在初次接觸時會遇到的一半誤判投訴:在一側更改鍵的順序並不會產生幽靈差異,而將項目從索引 2 移到索引 5 則會產生多個差異。再加上嚴格的解析規則(不允許註解、不允許尾端逗號、不允許 undefined 或 NaN)、RFC 6901 的 JSON Pointer 跳脫規則,以及套用於每個數值輸入的 JavaScript Number 精度,可能出錯的面向已經夠廣,值得在貼上大型資料前先列一份檢查清單。

為何 JSON Diff 錯誤來自類別混淆
大多數 JSON Diff 錯誤,都來自於套用從其他類別工具借來的心理預期。如果你長年使用以行為基礎的文字差異工具,看到兩份 JSON 文件時的第一反應,就是逐字元比較,檢查縮排、大括號位置與尾端逗號。這個直覺立刻就會產生誤判,因為 RFC 8259 讓 token 之間的空白變得無意義,並明確定義物件為無序的成員集合。
相較之下,JSON Diff 會在任何比較之前,先用嚴格的 RFC 8259 解析器剖析兩側,因此在計算第一個新增或移除項目之前,縮排、換行與物件成員順序都已經被正規化掉。如果讀者在兩側貼上同一份文件但鍵的順序不同,會看到一份空的變更清單,此時正確的反應應該是鬆一口氣,而不是驚訝。這個工具不會把格式漂移標記為語意差異,這代表任何實際出現的變更,都代表值、鍵、型別或陣列位置上的真實變化,值得進一步調查。
另外三種混淆類別出現的頻率同樣很高。讀者預期會得到 JSON Patch 輸出(RFC 6902 運算),但實際收到的卻是供審閱用的變更清單。讀者預期陣列重排會被摘要成單一移動,但實際上比較是嚴格按位置進行。讀者預期會有任意精度整數運算,但解析器使用的是 JavaScript 的 IEEE 754 Number 型別,在比較前會先對某些輸入做四捨五入。知道你自己實際上處於哪一個類別,是本指南中所有其他章節的先決條件。
把變更清單當成可執行的 Patch
讀者使用 JSON Diff 時所犯最昂貴的一個錯誤,就是把複製出來的輸出當作 RFC 6902 JSON Patch,並套用到來源文件上。這個輸出既不是 JSON Patch,也不是 JSON Merge Patch、統一文字差異或結構描述遷移。它是一份產品定義的變更清單,記錄每一筆新增、移除、變更與型別變更項目,並附上其 RFC 6901 JSON Pointer 路徑以及變更前與變更後的值。
結構上的差異至關重要。JSON Patch 包含 add、remove、replace、move、copy 與 test 等具有套用語意的運算,而 JSON Diff 的變更清單中完全沒有運算,只有觀察記錄。這個工具絕不會宣稱某個被移除的值在周遭變更後還能還原,也絕不會發出 move 或 copy,更不會測試任何前置條件。如果你把這份變更清單貼進 JSON Patch 函式庫,期待它能重新執行,那個函式庫會拒絕每一筆項目。
安全的工作流程是:把變更清單用於審閱與 pull request,然後在自動套用任何變更之前,找一套有維護的 patch 實作並搭配應用程式專屬的測試。請自己逐一檢視項目,把每個路徑對應到你應用程式實際需要的運算,並在信任結果之前,先確認產生的文件能夠透過你的解析器完成往返。
誤讀 RFC 6901 路徑跳脫
JSON Pointer 路徑看起來像檔案路徑,但跳脫規則會讓從未讀過 RFC 6901 的讀者中招。在參照 token 內部,兩個字元具有特殊意義:斜線 / 會分隔 token,而波浪號 ~ 會引入跳脫序列。成員名稱中若包含這兩個字元,都必須編碼,否則像 /first/name 這樣的路徑,會靜悄悄地指向名為 first 與 name 的兩個子節點,而不是名為 first/name 的成員。
這個跳脫規則是精確且不對稱的。成員名稱中的字面斜線會變成 ~1,而字面波浪號會變成 ~0。順序很重要:~1 必須在 ~0 之後套用,以避免重複編碼。陣列位置使用純小數 token,例如 /0、/1、/12,而文件的根是空字串,在人類可讀的清單中顯示為 root,而不是開頭的斜線。
如果讀者複製了像 /settings/ui~1theme 這樣的路徑,並假設它指的是名為 ui/theme 的子節點,就會讀錯成員。修正後的路徑就是 /settings/ui~1theme——token 中間的 ~1 是真正的跳脫序列,而不是分隔符號。當你把這些路徑貼回自己的程式碼時,請依序將 ~1 解碼為 /、將 ~0 解碼為 ~,再把結果視為成員名稱。
| 成員名稱中的字元 | 編碼後的 token |
|---|---|
| / (斜線) | ~1 |
| ~ (波浪號) | ~0 |
| 純英數或底線 | 保持不變 |
將陣列重排誤讀為移動
JSON Diff 以位置方式比較陣列,回報的結果既不會多也不會少。JSON 中的陣列是有序的序列,比較時依序比對索引 0 對索引 0、索引 1 對索引 1,依此類推。這個工具不會猜測身分鍵、不會計算最長共同子序列,也不會把陣列當作集合處理,因為這些策略都仰賴資料契約,而且可能會掩蓋具有意義的順序變更。
實際上的後果是:將一個項目從索引 2 移到索引 5,會以一連串的變更呈現,而不是一個乾淨俐落的移動。舊索引處的項目會被回報為移除,新索引處則會以正確的值新增一個項目,而中間的索引都會被標記為變更,因為其內容已不再按位置對應。期待重排只會顯示為一行差異的審閱者,將會誤判這個變更的規模。
如果你的應用程式把陣列順序視為語意上無意義,請在貼入之前先把兩側正規化為標準順序。如果你的應用程式把陣列順序視為有意義,請逐字解讀這個位置的連鎖變更,並檢查新的順序是否就是實際想要的結果。
數值精度與數字邊界情況
所有數值輸入在進行任何比較之前,都會經過 JavaScript 的 IEEE 754 Number 型別,而這個選擇帶來三個讀者應該事先預期的後果。
第一,超過安全整數上限的整數,在解析器把資料交給比較流程時,可能就已經被四捨五入了。安全整數上限定義為 2^n − 1,其中 n 是有效位元數,JavaScript 定義 n = 53。代入之後,上限等於 2^53 − 1 = 9007199254740991。任何絕對值超過 9007199254740991 的整數,都無法保證能在比較中往返還原,因此兩個僅在第十六位有效數字之後才不同的長整數字串,可能會產生錯誤的「無變更」結果。
第二,細微的小數差異不會被保留。像 0.1 + 0.2 = 0.30000000000000004 這樣的值,在解析後的表示中就已存在,因此在數學上相等但文字上不同的「變更後」值,可能會依解析器實際產生的位元組而匹配或不相配。如果你需要精確的小數行為,請使用專為該契約設計的解析器與數值模型來比較來源。
第三,正零與負零會被視為相同的 JSON 數值,因為在 JavaScript 中 -0 === 0 為真。期待符號差異會被回報的讀者,將會對一份空的變更清單感到驚訝。對於金融或帶正負號大小的運算,請直接比較來源表示,而不是依賴瀏覽器的算術運算。
如何在不出錯的前提下進行 JSON Diff
以下是可以避開上述所有錯誤的工作流程。
- 在貼入之前,先用嚴格的 RFC 8259 解析器驗證兩側。註解、尾端逗號、undefined、NaN、Infinity、BigInt 語法與 JavaScript 物件實字,都會被 JSON Diff 拒絕;若有一側無法解析,則根本不會產生任何比較結果。
- 正規化你的心理預期,而不是資料本身。請先決定在你的契約中,物件鍵的順序是否重要(幾乎從來不重要)、陣列順序是否重要(通常重要),以及 JavaScript Number 的精度是否能夠接受你所比較的值。
- 把左右兩份文件貼入 JSON Diff——兩側的格式與物件成員順序可以不同,這個工具會把它們視為等價。
- 執行比較,並依其 RFC 6901 JSON Pointer 路徑逐一檢視每個新增、移除、變更或型別變更項目。確認路徑能正確解碼,特別留意代表 / 的 ~1 與代表 ~ 的 ~0。
- 對於陣列重排,請數一下項目數。一連串的 remove + add + 多個變更,是按位置的回報方式而非錯誤,代表的是真正的重排,而不是邏輯上的移動。
- 複製變更清單用於審閱。不要把它貼進期待 RFC 6902 語意的 JSON Patch 函式庫;這個輸出是供審閱用的變更清單,只包含變更前與變更後的值。
- 在自動套用任何變更之前,請為你的資料契約建立一套專屬的 patch 實作與測試。把這些測試套用於正式環境文件的快照,並驗證往返結果。
- 在把變更清單複製到記錄、工單或聊天串之前,請先檢視任何敏感的變更前後值。這個工具在本機執行,但審閱的軌跡未必留在本機。
輸入中工具拒絕處理的內容:替代做法
JSON Diff 刻意採嚴格標準,許多常見的近似 JSON 輸入會被拒絕,而非默默地強制轉換。任何形式的註解、結尾逗號、JavaScript 字面常數 undefined、IEEE 特殊值 NaN 與 Infinity、帶有 n 後綴的 BigInt 語法,以及省略鍵引號的裸 JavaScript 物件字面常數,全都無法通過嚴格的 RFC 8259 解析。正確的做法是使用真正的 JSON 解析器移除違規語法,再貼上清理後的結果。
來源文字中重複的成員名稱同樣是工具無法處理的,因為一般 JSON 解析在比較看到物件之前,就會將重複項目合併成單一項目。如果您的資料含有具意義的鍵重複,則需要使用保留重複鍵的非標準解析器,然後對產生的結構手寫差異比對。
每個輸入的上限為 500,000 個字元、巢狀深度 50 層比較,輸出則限制為 5,000 項變更。工具會回報失敗而非截斷較大的結果,以保護您不會得到看似完整卻只是部分答案的結果。若您的文件超過這些上限,請依已知的分割鍵切分比較,或使用專為大量資料設計的串流差異比對工具。
快速參考:變更類型
| 變更類型 | 觸發條件 | 項目內容 |
|---|---|---|
| added | 鍵僅出現在右側,或陣列位置僅存在於右側 | RFC 6901 路徑與右側值 |
| removed | 鍵僅出現在左側,或陣列位置僅存在於左側 | RFC 6901 路徑與左側值 |
| changed | 相同路徑、相同 JSON 類型、不同值 | RFC 6901 路徑、左側值與右側值 |
| type-changed | 相同路徑、不同 JSON 類型(例如數值變字串、物件變陣列,或 null 變布林值) | RFC 6901 路徑、左側值與右側值 |
每個項目皆以 RFC 6901 JSON Pointer 呈報,且物件成員名稱會排序以利結果可重現,因此對同一對文件執行兩次會以相同順序產生相同的變更清單。當整個成員被新增、移除或變更類型時,子樹可作為值出現,這讓即使結構差異很大的輸出仍易於閱讀。該工具已通過驗證的八個外部測試案例——changed、added、removed、type-changed、array index、slash escaping、tilde escaping 和 object-order equality——提供了固定的迴歸測試面向,您在正式環境採用結果前,也可據此測試您自己的預期。