這個錯誤教會了我停止將 JSON 視為文本,這讓我花了大部分週末的時間。我運行的 Laravel SaaS 上的支付網路掛鉤在提供者"不破壞&引用; API 更新 - 他們的話,來自變更日誌。我從日誌中取出更新前的有效負載,抓取一個新的有效負載,並將兩者放入常規文字差異中。每一行都亮起來。提供者已經切換了他們的序列化器,該序列化器按字母順序重新排序每個鍵,並將縮排從四個空格更改為兩個空格。六百條更改了行,在某個地方,有一個真正的區別。在找到它之前,我從上到下讀了兩次差值: amount 從號碼上改變了 1099 到字串 "1099". 螢幕上相同的字元。不同類型的。我們嚴格的比較拒絕了它,隊列將其重新埋入地下,文字差異將一個有意義的變化埋在了 599 個外觀變化之下。
That'是基本問題:JSON 是一種資料格式,但文字差異將其視為散文。關鍵順序、空格、縮排、尾隨換行符 - 對於 JSON 解析器來說,它們都沒有任何意義,並且所有這些都以基於行的比較中的變化的形式顯示。每 RFC 8259,JSON 物件是一個 無序 名稱/值對的集合。兩個文件可能逐字節不同且語意相同。逐行比較 JSON 的工具回答了錯誤的問題。
一個 JSON 差異工具 回答正確的一個。它將兩個文件解析為樹並進行比較 值:新增了該鍵,刪除了該鍵,該值從 X 更改為 Y,並且 - 保存我週末的值,如果它當時存在於我的瀏覽器選項卡中 - 該值已更改 類型. 當我為 toolz。dev 建立差異檢查器時,類型變更偵測是清單中的第一個功能,因為它's 文字差異在結構上無法浮出水面並且最常破壞真實系統的變更類別。
本指南涵蓋了結構比較的工作原理、陣列順序何時應該和應該以及#39;t matter 以及調試工作流程 - API 回歸、配置漂移、套件清單審核 - 其中 JSON diff 每週自行付費。
TL;DR: 將兩個 JSON 文件貼到 Toolz.dev JSON 差異檢查器 並進行結構比較:新增、刪除和更改具有精確路徑的鍵,例如
features.rateLimit或者users[3].email- 加上值變更時的單獨標記 類型 (the3000→"3000"錯誤)。關鍵順序和格式永遠不會產生誤報。所有內容都在您的瀏覽器中運行;沒有上傳任何內容。與配對 json 格式化程式 首先清理文件 文字差異工具 對於行實際上重要的內容。
從結構上差異 JSON 是什麼意思?
結構差異將兩個文件解析為實際的資料樹,並逐個鍵、逐個元素地將它們一起遊走。在每個節點,它都會問:這個鍵是否存在於兩側?這些值是同一類型嗎?它們相等嗎?輸出是't"第 14 行更改並引用; - it'有關您的資料的事實清單:
version改變自"1.4.0"到"1.5.0"features.metrics增加了價值trueport將類型從數字變更為字串tags[2]增加了價值"monitored"
每個差異都帶有完整的 JSON 路徑,因此在深度嵌套的文檔中,您確切地知道該查看的位置。 users[12].address.postalCode 告訴您哪個使用者、哪個字段,無需滾動。
與文字差異的對比在現實世界的文件中最為明顯。採取一個 package.json 透過不同的 npm 版本、後端團隊升級序列化器後的 API 回應或透過格式化程式運行的設定檔進行再生。文字差異:數百行更改。結構差異:實際發生的三個變化,或沒有的誠實答案 - "結構相同" - 這本身就很有價值。確認產生了有風險的重構 零 數據變化是我使用此工具的一半原因。
There'是一個讓行差異的地方,需要清楚。散文、程式碼、HTML,任何物理佈局有意義的東西 - that's 文字差異 領土。但 JSON'根據規範,佈局沒有任何意義,而假裝產生噪音的比較則必須用眼睛過濾。
為什麼類型變更值得擁有自己的類別?
因為他們'在資料的所有其他視圖中都是不可見的,並且它們以難以調試的方式破壞事物。
1099 和 "1099" 在日誌檔案、終端機和大多數文字差異中進行相同的渲染 - 引用在凌晨 2 點很容易錯過。但對於任何鍵入的消費者來說,它們都是不同的值。 JavaScript's === 拒絕比較。 JSON 模式聲明 "type": "integer" 驗證失敗。 Go 服務解組為 int64 傳回錯誤; Java 中的嚴格 Jackson 反序列化器拋出。 PHP 以寬鬆的比較而聞名,但當您啟用嚴格類型時(每個現代 Laravel 程式碼庫都應該這樣做) "1099" 不再是金錢,而是開始成為例外。
最討厭的部分是 在哪裡 這些變化來自。幾乎不是開發人員故意編輯值。它們來自序列化器交換、ORM 升級、遷移的資料庫列 INT 到 VARCHAR,一個對數字進行字串化的快取層,或一個善意的 API 網關 "標準化&引用;有效負載。沒有人為它們編寫更改日誌條目,因為沒有人知道它們發生了。
所以 json 差異檢查器 報告類型變更作為自己的類別 - ! 在可複製的報告中,與普通值變化不同 - 闡明了新舊類型。當你'正在盯著一個摘要說 0 added, 0 removed, 0 changed, 1 type changed#39;在你之前狩獵'你確切地知道是什麼樣的錯誤。讀過一條路徑。
如何將兩個 JSON 檔案與工具進行比較?
第 1 步:貼上兩個文件
原始(或已知良好)JSON 位於左側面板,更新(或可疑)JSON 位於右側面板。約定僅對於讀取輸出很重要:"新增&引用;表示出現在右側但不出現在左側,"刪除並引用;意味著相反。如果您'將工作環境與損壞的環境進行比較,請將工作放在左側,差異讀作 "損壞的東西改變了。&引用;
There'是一個載入範例按鈕,它用一個小的服務配置填充兩個面板,練習每種差異類型 - 值更改、添加、類型更改、數組增長 - 這是學習輸出讀取方式的最快方法。
步驟 2:決定數組順序是否重要
這是您需要考慮的一個選項,正確的答案取決於您的陣列 意思是- 更多關於下面的內容。預設值對順序敏感,與 JSON 規範相符。勾選&引用;忽略數組順序&引用;當您的數組是語意集合時。
第三步:比較
在比較任何內容之前,這兩個文件都會經過驗證。如果任何一方有語法錯誤 - 尾隨逗號、單引號、未引號鍵、常見的嫌疑 - 您將獲得解析器'確切的訊息,最重要的是 哪一邊 它來自。沒有無聲的失敗,沒有比較半解析垃圾。如果您'不確定您的 JSON 是否有效,請將其運行 json 格式化程式 第一的;它一步驗證並列印漂亮。
第四步:閱讀摘要,然後閱讀表格
摘要行按類別為您提供計數 - 新增、刪除、更改、類型更改 - 這通常是您所需要的。 &引用;47 新增、0 刪除、0 更改並引用; API 版本後,凹凸僅表示新欄位:安全。 &引用;新增 0 個,刪除 3 個&引用;表示您的消費者可能依賴的欄位剛剛消失:不安全。下表列出了每個差異及其路徑、舊值和新值,為了長值的可讀性而截斷。
第五步:複製報告
複製報告按鈕會產生純文字摘要 + / - / ~ / ! 標記和完整路徑 - 設計用於直接貼上到拉取請求評論、Slack 事件線程或票證中。 &引用;這裡'這正是舞台和製作配置和引用之間的變化;只需點擊一下即可獲得收據。
什麼時候應該忽略數組順序?
JSON 陣列依規格排序 - [1, 2] 和 [2, 1] 是不同的文檔,預設的比較尊重這一點。但規範描述了容器,而不是您的意圖,並且在實踐中陣列有兩種不同的方式使用:
數組為序列位置意味著:按順序執行的中間件鏈、遷移清單、排序的排行榜、分頁結果。重新排序這些是一個真正的變化 - 一個運行的中間件堆疊 auth 之後 handle 是一個不同的(並且可能損壞的)應用程式。保持訂單敏感性。
數組為集合(位置發生意外):標籤清單、角色分配、功能標誌、資料庫查詢傳回的 ID(沒有) ORDER BY. Postgres 完全有權在不同的運行中以不同的順序返回相同的行,如果您的差異因此而亮起,則 's 噪音。這就是 "忽略數組順序和引用;選項是 - 元素無論位置如何都匹配,所以 ["admin", "editor"] 等於 ["editor", "admin"].
我多年來比較 API 有效負載的經驗法則是:如果後端應用明確排序,則將數組視為序列;如果它沒有't,it'無論作者是否意識到,這是一個集合,並且順序不敏感的比較會告訴您有關資料的真相。
結構差異與文字差異與手動檢查
| 結構 JSON 差異 | 文字/行差異 | 盯著它看 | |
|---|---|---|---|
| 重新排序的密鑰 | 沒有報告差異 | 每移動一行都標記 | 很容易錯過的變化 |
| 重新格式化的空白 | 沒有報告差異 | 一切都標記了 | 不適用 |
類型更改 (1 → "1") |
標記為類型變更 | 排隊中的兩個角色 | 幾乎看不見 |
| 嵌套更改位置 | 確切路徑: a.b[2].c |
行號在 已格式化 文字 | 手動遍歷 |
| 數組重新排序(有意) | 標記(或忽略,您的選擇) | 已標記 | 取決於數組大小 |
| 最好 | JSON、API 有效負載、配置 | 代碼、散文、標記 | 兩行文檔 |
| 故障模式 | 有效的 JSON 上沒有 | 誤報掩蓋了真實的變化 | 人類疲勞 |
誠實的摘要:文字差異是'錯了,他們'正在回答不同的問題 - "位元組有變化嗎?"對於 JSON,您幾乎總是想要 "有嗎 數據 改變?引用;這些問題常常有不同的答案。
JSON Diff 的真實工作流程是什麼?
調試 API 回歸
我的網路掛鉤故事中的工作流程現已系統化:捕獲更改前的有效負載(日誌、錄製的固定裝置、測試套件和#39;快照)以及更改後的有效負載。左面板,右面板,比較。差異在幾秒鐘內告訴您提供者's changelog did't - 哪些欄位移動,哪些欄位更改類型,哪些欄位悄悄消失。每次第三方 API 宣布版本提升時,我都會這樣做 之前 舊版日落,並在升級票證中提交報告。
捕捉配置漂移
舞台作品,製作沒有't,兩者都是"從同一配置部署。和引用;他們是嗎?兩者都導出 - 環境 JSON,a docker inspect 輸出,一個 Kubernetes ConfigMap 傾倒 -o json- 並擴散它們。配置漂移幾乎總是一兩個鍵,路徑列會直接帶您到達那裡。這節拍 diff <(jq -S . a.json) <(jq -S . b.json) 在終端中,因為它也會捕捉類型變化,這 jq-歸一化文字差異幾乎呈現隱形。
查看鎖定檔案和清單變更
一個 package.json 或者 composer.json 這會因衝突的合併或框架升級後產生的 OpenAPI 規範而損壞:結構差異向您顯示依賴項更改,而不會產生再生格式的雜訊。對於 WordPress 外掛程式工作 - WP 將設定管理為 JSON - 我在版本之間差異匯出的設定模式,以確保重構沒有't 丟棄數千次安裝所依賴的金鑰。意外刪除顯示為 - 行;在 4,000 行設定匯出的文字差異中,它顯示為完全沒有。
驗證資料遷移
之前:將代表性記錄匯出為 JSON。遷移後:再次匯出。差異應準確顯示遷移的預期變化 沒有別的. & 引用;結構相同&引用;記錄上應該't已被觸及是您'將運行的最便宜的回歸測試。這與轉換表格導出很好地配對 csv 到 json 當資料以 CSV 形式從資料庫中出來時。
比較環境反應
在兩個環境中達到相同的端點,差異回應。開發中存在但在生產中缺少的欄位通常意味著特徵標誌、陳舊的部署或從未設定的環境變數。摘要通常僅計算計數即可診斷它。
為什麼客戶端處理對於此工具來說比大多數工具更重要?
考慮一下您貼上到 JSON diff 中的內容:使用客戶電子郵件的 API 回應、具有內部主機名稱的設定檔、帶有支付元資料的 Webhook 有效負載、資料庫匯出。這正是不得洩漏的數據,是在沒有人審核剛剛收到哪個線上工具時貼上的。
的 toolz。dev 差異檢查器 完全在瀏覽器中進行解析和比較。沒有請求將您的文件帶到任何地方;頁面載入後,該工具就會離線工作,您可以透過切斷網路並再次比較來驗證這一點。這是't 可以更改的高級功能或策略承諾 - it's 架構。比較邏輯是純 JavaScript,在記憶體中的兩個解析樹上運行。沒有伺服器元件可以將資料傳送到。
同樣的隱私論點也適用於整個工具箱 - it's 原因 toolz。dev 上的開發人員工具包 是瀏覽器先建置的 - 但差異工具是它'最尖銳的地方,因為比較 兩個 生產文件使貼上文件的曝光率加倍。
您能比較多大的文件?
比較訪問兩棵樹中的每個節點一次,因此工作與文件大小呈線性比例。在實踐中:數百 KB 的文件立即進行比較;在類似現代筆記型電腦的任何東西上,低個位數兆位元組在不到一秒的時間內完成;數十兆位元組可以工作,但你'會感覺到它,因為瀏覽器必須解析兩個文件並將兩個樹同時保存在記憶體中。
對於非常大的有效負載的兩個實用提示。首先,如果您只關心文件的一部分,請僅比較該子樹 - 貼上 response.data.items 來自兩側而不是整個信封。其次,如果差異產生數千個條目,則 's 通常一側的符號是不同的 形狀 (包裹在物件中的數組,額外的嵌套等級) - 在滾動之前檢查前幾條路徑;他們'會告訴你你是否'正在研究一種級聯的結構變化或數千種真實的結構變化。
問號
如何在線比較兩個 JSON 檔案？
打開 json 差異檢查器,將一份文件貼到左側面板,另一份貼到右側面板,然後按一下「比較」。您將獲得每個新增、刪除、變更和類型變更值的分類清單及其精確的 JSON 路徑。這兩個文件都完全在您的瀏覽器中處理 - 任何內容都不會上傳到任何伺服器。
當我的 JSON 資料相同時,為什麼文字差異會顯示如此多的變更?
因為文字差異可以比較行,而 JSON 允許以多種方式編寫相同的資料。重新排序的鍵、不同的縮排和空格都會在不更改資料的情況下更改文字。結構差異首先解析兩個文件並比較實際值,因此格式差異會產生零報告變更。
JSON 物件中的鍵順序重要嗎?
No。 RFC 8259 將 JSON 物件定義為名稱/值對的無序集合,因此 {"a":1,"b":2} 和 {"b":2,"a":1} 是同一個物件。差異檢查器透過鍵名比較對象,並且從不報告重新排序作為更改。相比之下,陣列元素順序預設很重要 - 陣列在規範中排序。
我什麼時候應該使用 "Ignore 數組順序"選項?
當您的數組是語義集而不是序列時使用它 - 標籤列表、角色集合、來自未排序資料庫查詢的 ID。帶有選項, [1,2,3] 和 [3,1,2] 比較相等。當位置有意義時,例如有序中間件鏈、排名結果或分頁列表,請將其關閉。
什麼是類型變更以及為什麼單獨標記?
類型變更是指 value's JSON 類型在文件之間有所不同,即使它看起來相似 - 數字 3000 成為字串 "3000" 是經典案例。它'單獨標記是因為它打破了嚴格類型的消費者、模式驗證和嚴格的平等檢查,同時在文字差異和日誌中幾乎看不見。它'這是 API 整合迴歸最常見的原因之一。
我可以與我的團隊分享比較結果嗎?
是的。複製報告按鈕會產生純文字差異報告 + (添加), - (已刪除), ~ (改變了),並且 ! (類型變更)標記和完整的 JSON 路徑,可滿足每個差異。它'其格式可乾淨地貼上到拉取請求註解、Slack 執行緒和問題追蹤器中。
將生產 API 回應貼到工具中安全嗎?
是的。解析和比較完全在瀏覽器中的 JavaScript 中運行 - 不會對您的資料提出網路請求,不會記錄或儲存任何內容,並且工具會保持離線工作。這使得包含客戶資料、內部主機名稱或憑證的有效負載變得安全,儘管在共享之前會編輯秘密 報告 還在你身上。
如果我的文件之一是 't 有效的 JSON,會發生什麼事?
該工具在比較之前驗證雙方並報告解析器'確切的錯誤訊息以及它來自哪一側 - 左或右。常見的罪魁禍首是尾隨逗號、單引號而不是雙引號以及未引號的鍵。修復報告的問題,或透過執行文件 json 格式化程式 要找到問題,請再次比較。
結構比較是那些可以改變哪些錯誤的工具之一 看. 文字差異答案&引用;位元組有變化嗎?&引用;;對於 JSON,重要的問題是 "資料有變化嗎?" - 對於運行系統的 API 有效負載、配置和清單 json 差異檢查器 在瀏覽器中,幾秒鐘內即可回答,您的資料永遠不會離開您的機器。更多 JSON 工作流程 - 格式化、驗證、轉換 - 即時 編碼工具指南.
