拉取請求有 240 條更改的行,我恰好觸及了兩個值。就在那時,我認真對待了 JSON 金鑰的排序。一位隊友透過格式化程式運行了一個設定文件,重新排序了其金鑰,我手動編輯了其中兩個值,產生的差異是一堵不可讀的紅色和綠色牆,其中 238 行是簡單移動的金鑰。我的審稿人要求我重做,這是可以理解的。真正的變化在噪音中是看不見的。
我運行 [toolz。dev](/並且還構建 Laravel 和 WordPress 項目,這意味著我住在裡面 package.json, composer.json, tsconfig.json翻譯目錄,以及一百個其他致力於版本控制的 JSON 檔案。具有不可預測的鍵順序的 JSON 檔案對其中每一個都徵收少量、經常性的稅。將按字母順序排列的按鍵是修復方法,它是那些看起來像是表面上的更改之一,直到第一次為您節省浪費的程式碼審查。本指南涵蓋何時對 JSON 鍵進行排序、何時不排序以及如何在不破壞任何內容的情況下進行排序。
TL;DR: JSON 排序器重新排序物件'按字母順序鍵並重新序列化結果。按鍵順序不會改變 JSON 的含義,因為物件未按 JSON 標準排序,但一致的順序使檔案可讀並產生僅顯示更改值的乾淨版本控制差異。遞歸排序以到達嵌套對象,預設保持數組順序,因為數組是有序的,並選擇升序或降序、漂亮或縮小的輸出。這 json分類機 完全在瀏覽器中運作。
什麼是 JSON 分類器?
JSON 排序器取得 JSON 物件並將其鍵重新排列成字母順序,然後將其寫回。這些值未受影響。只有按鍵出現的順序會發生變化,這是安全的,因為 RFC 8259 將物件定義為無序集合:重新排序鍵不能改變文件的含義。所以 {"name":"toolz","author":"Liton"} 成為 {"author":"Liton","name":"toolz"}. 預設情況下,排序是遞歸的,這意味著每個嵌套物件內的鍵也被排序,一直到最深層。
這就是整個操作,它的簡單性才是重點。您不是在轉換資料、驗證模式或轉換格式。您正在對具有任意順序的事物施加可預測的順序。所有其他好處、可讀性、可比性、乾淨的差異都源自於單一的可預測順序。
排序鍵會改變我的 JSON 的意思嗎？
不,這就是排序安全的事實。在 JSON 標準 ECMA-404 中,物件被定義為名稱和值對的無序集合。該規範明確表明這些對的順序並不重要。任何符合的解析器都會讀取 {"a":1,"b":2} 和 {"b":2,"a":1} 正如完全相同的數據。當你的程式這樣做時 config.timeout 或者 data["name"],它透過名稱查找密鑰;它從不關心該密鑰寫在物件中的哪個位置。
有一個警告值得明確說明,因為總是有人問。極少數系統濫用 JSON 對象,就好像它們是被訂購的一樣,依賴插入順序進行顯示或處理。這是對格式的濫用,而不是它的屬性,但如果您正在向無法控制的系統提供信息,請在將已排序的文件提交到您無法檢查的管道之前進行測試。對於絕大多數現實世界的 JSON,設定檔、API 有效負載、鎖定檔案、翻譯目錄、排序鍵純粹是表示變化,對意義的影響為零。
數組則相反,差異很重要。 JSON 數組根據定義進行排序,其順序通常具有含義:一系列步驟、排名列表、一組座標,其中位置一是經度,位置二是緯度。重新排序數組可以默默地更改資料的內容。這就是為什麼該工具預設保留數組順序,並且僅在明確要求時對數組進行排序,即使如此,也僅適用於元素都是字串或所有數字的數組。
為什麼我要對 JSON 鍵進行排序？
標題原因是乾淨的差異,正是它改變了我的工作方式。版本控制工具逐行比較文件。當代表相同資料的兩個檔案以不同的順序寫入金鑰時,差異中充滿了移動的金鑰而不是更改的值。採用每個 JSON 檔案都是用排序的金鑰編寫的規則,問題就會消失:檔案的兩個版本僅在值實際不同的地方有所不同,因此審閱者會立即看到真正的更改。這正是許多行情和格式化程式提供排序金鑰選項的原因,也是工具喜歡的原因 jq 運送排序鍵標誌。
第二個原因是人類的可讀性。當您掃描大型設定檔尋找特定設定時,按字母順序告訴您要查看的位置。您不閱讀整個文件;您大致跳到鍵應該的位置,就像字典中的那樣。在有八十個鍵的文件上,這就是兩秒查找和完整掃描之間的差異。
第三個原因是文件之間的可比性。如果您的專案有 10 個 JSON 文件,它們都應該共享一個共同的結構,那麼以相同的方式對它們進行排序對於查看是否缺少密鑰或有一個額外的密鑰來說就變得微不足道了。分歧彼此相鄰排列,而不是隱藏在不同的位置。
第四個原因是規範化。一些工作流程需要 JSON 值的穩定、確定性表示,例如對其進行雜湊、快取或比較兩個有效負載的相等性,無論它們是如何序列化的。排序鍵是邁向規範形式的一步,儘管完整的規範 JSON 也規範化了空格和數字格式。
如何使用 JSON 分類器?
將 JSON 貼到輸入框中 json分類機,或載入樣本以查看輸出的形狀。輸入必須是有效的 JSON。如果不是,工具會報告解析錯誤及其位置,以便您可以在排序前修復雜散逗號或未關閉的括號。
然後選擇排序如何運作。選擇升序(A 到 Z),或降序(Z 到 A)。決定是否折疊大小寫,預設情況下該大小寫處於開啟狀態 Name, name, 和 NAME 坐在一起而不是分開,因為大寫字母按照原始字元順序在小寫字母之前排序。選擇是下降到您幾乎總是想要的嵌套對象,還是僅對頂層進行排序。如果您想要按順序排列字串或數字數組,請開啟數組排序;混合數組和物件數組始終保持原樣。
最後,選擇您的輸出樣式。為您將提交的可讀文件列印兩個空格、四個空格或選項卡縮進,或縮小到一行以儲存或傳輸的最小有效負載。執行排序,然後複製結果或下載它。金鑰計數告訴您重新排序了多少個金鑰,這是工具看到您期望的結構的快速健全性檢查。
上升、下降、遞歸:我想要哪些設定?
大多數時候,預設值是您想要的:上升、遞歸、不區分大小寫、漂亮地列印了兩個空格。這會產生可讀的、差異友好的文件,首先會激發排序。其他設定是針對特定情況存在的,下表是我如何決定的。
| 設定 | 預設 | 什麼時候改變它 |
|---|---|---|
| 命令 | 上升(A 到 Z) | 下降的情況很少見;當您想要最新或最高優先級的鍵(命名為最後排序)位於頂部時,它非常有用 |
| 遞歸 | 打開 | 僅當您想要重新排序頂級部分但保留每個部分內的手動調整順序時才關閉 |
| 忽略案例 | 打開 | 當您需要嚴格的代碼點順序時關閉,例如匹配另一個區分大小寫的工具 |
| 對數組進行排序 | 關閉 | 開啟真正的無序集合的數組,例如標籤或允許值的清單 |
| 漂亮的印刷品 | 打開 | 關閉以縮小以用於運輸或儲存 |
人們濫用的一種設定是數組排序。只有當您確定數組代表無序集合時,才將其開啟。標籤清單、一組允許的檔案副檔名或一袋功能標誌可以安全排序。管道步驟清單、路由表或任何位置暗示序列不存在的內容。如有疑問,請不要使用數組,因為工具'預設的保留順序永遠不會損壞您的數據,而默默地對錯誤的數組進行排序則不會。
這與其他 JSON 工具有何契合?
排序通常是小鏈中的一個步驟。當 JSON 達到小型且無法從 API 讀取時,我會將其運行到 JSON 格式化程式 首先縮排並驗證它,然後對密鑰進行排序以使其可掃描。當我準備排序後傳輸的有效負載時, JSON 小型化器 將其剝離回一行,並且由於按鍵已經排序,因此代表相同資料的兩個縮小有效負載逐字節相同,這對於快取和比較很方便。
對於結構工作而不是演示, JSON 展平器 將嵌套物件轉換為點鍵並返回,當您爭論配置為環境變數時,它會自然地與排序配對。當您完全需要另一種格式的資料時, JSON 到 YAML 轉換器 是下一站;轉換前的排序鍵也會為您提供具有可預測、可讀欄位順序的 YAML 檔案。如果您想了解這些如何組合在一起的更大圖景,我將其完整設定放在其中 web 開發人員工具包指南,以及更深層的格式化機制 JSON 格式化程式指南.
一個真實的例子:馴服一個包。json diff
讓我回顧一下本文開始的確切情況,因為它說明了為什麼設定選擇很重要。我有一個 package.json 哪裡 dependencies block 是按照安裝順序編寫的,大致是兩年多來新增套件的順序。一位新團隊成員運行了他們的編輯器#39; s format-on-save,它對依賴項進行排序,並將其與真正的更改一起提交:將一個套件從版本 4 提升到版本 5。
差異是一場災難。凹凸不平的依賴項下方的每個依賴項似乎都移動了,因為排序已經改變了它們的位置,因此審閱者看到單行升級有 30 行更改。修復方法不是爭論誰的編輯器是正確的。修復方法是對文件進行一次排序,將該排序作為自己的單獨更改提交,並帶有諸如 "sort package。json keys," 之類的訊息。然後,使版本在現在穩定的順序之上顛簸。此後,未來的每次依賴項變更都會產生乾淨的一行或兩行差異,因為該檔案已經按照每個人的順序排列's 工具想要放入它。
這就是我現在對任何生活在版本控制中的 JSON 所遵循的模式。在專用提交中對它進行排序一次,然後保持排序。這 json分類機 預設情況下,升序和遞歸,恰好產生 Prettier's 排序選項和 jq --sort-keys 產生,因此無論隊友碰巧運行哪個工具,文件都會保持穩定。我首先檢查的一件事是數組: package.json 沒有有意義的數組需要擔心,但具有有序數組(例如建置步驟清單)的檔案需要保留數組排序,這是預設值,因此序列得以保留。
哪些工具和格式對 JSON 金鑰進行排序?
對 JSON 金鑰進行排序是一種非常普遍的需求,它出現在整個生態系統中,這是一個好兆頭,這種做法是合理的,而不是個人的怪癖。命令列處理器 jq 有a --sort-keys 旗幟,常寫成 -S,這對其輸出中每個物件的鍵進行排序。 Prettier 程式碼格式化程式可以透過其配置對 JSON 中的鍵進行排序。許多 linter 提供排序鍵規則來標記原始程式碼中未排序的物件。語言標準庫公開相同的功能,例如 Python's json.dumps 接受a sort_keys=True 產生規範、排序輸出的參數。
基於瀏覽器的分類器添加的是快速、無需設定的情況。當您從 API 回應、日誌行或 Slack 訊息中看到 JSON 斑點,並且您現在只想以合理的順序閱讀它時,開啟頁面並貼上比連接格式化程式或刪除格式化程式更快。進入 shell。這與編輯器插件旁邊存在貼上即用格式化程式的原因相同:該工具滿足配置的管道未涵蓋的臨時需求。
我的 JSON 是私人的嗎?
是的。 JSON 使用 JavaScript 完全在您的瀏覽器中解析、排序和重新序列化。沒有任何內容上傳到伺服器、記錄或儲存在任何地方。這並不是 JSON 的小細節,因為 JSON 是秘密所在:API 回應攜帶令牌、帶有連接字串的設定檔、包含客戶記錄的有效負載。將其中任何一個貼上到將其發送到伺服器的工具中都是真正的風險,而這正是該工具旨在避免的風險。
你可以像我一樣驗證這個聲明。打開瀏覽器中的網路標籤'開發者工具並在排序時觀看它;頁面沒有留下任何請求。或斷開與互聯網的連接並繼續排序,因為一旦頁面加載,該工具就根本無法連接。客戶端處理是我建立的所有內容的預設處理,如果您關心它的更廣泛的參數,則 資料隱私指南 使案件完整。
常見問題
對 JSON 金鑰進行排序意味著什麼？
對 JSON 鍵進行排序 將物件的名稱值對重新排序為字母順序,而不更改任何值。物件{"name":"toolz","作者&引用;:"Liton"}變成{"author":"Liton","name":"toolz"}。只有按鍵的順序發生變化,因此文件表示的資料保持完全相同。
排序鍵會改變我的 JSON 的意思嗎？
不 。 在 JSON 標準 ECMA-404 中，物件是一組無序的名稱-值對，因此重新排序其鍵並不會改變其意義。 任何符合性解析器都會將排序和未排序的版本讀取為相同的資料。 該順序僅對人類可讀性和產生穩定的差異很重要。
嵌套物件是否也排序？
是的，預設。 遞歸排序開啟，因此文件中每個物件的鍵都在嵌套的每個層級上進行排序。 您可以關閉遞歸以僅對頂級鍵進行排序，並以原始順序保留嵌套物件。
排序器會重新排序數組嗎？
預設不是。 數組按定義排序，重新排序它們可以改變意義，因此該工具保留數組順序。 當您想要訂購時，可以選擇對元素為所有字串或所有數字的陣列進行排序；混合類型或包含物件的陣列始終保持原樣。
為什麼我要對 JSON 鍵進行排序？
最常見的原因是穩定的差異：當每個檔案以相同的字母順序寫入其密鑰時，版本控制區別只突出顯示更改的值而不是移動的鍵。 排序還使大型配置檔案和 API 響應更易於掃描和通過眼睛進行比較。
不區分大小寫的排序如何運作？
使用不區分大小寫的排序，將鍵進行比較，就像小寫一樣，因此名稱、名稱和名稱彼此相鄰分組，而不是分開，因為大寫字母在原始字元順序之前排序小寫字母。 將其關閉以嚴格按字元代碼點排序。
我可以縮小排序的 JSON 嗎？
是的。 選擇縮小的輸出以在沒有額外空格的情況下將排序的 JSON 取得，這是用於儲存或傳輸的最小形式。 對於可讀的檔案，請選擇使用二空間、四空或標籤縮排的漂亮輸出。
我的 json 上傳到任何地方了嗎？
不 。 JSON 在您的瀏覽器中按 JavaScript 解析和排序，從不傳輸、記錄或儲存。 您可以在排序時透過觀看網路標籤來驗證這一點，或者透過離線，該工具在沒有連線的情況下繼續工作。
由 [toolz。dev] 的建構者 Liton 撰寫(/。 我建立基於瀏覽器的開發人員工具並撰寫有關使用 JSON、Laravel 和 Web 的文章。
