JSON 格式化工具

這個格式化工具接受什麼

解析器嚴格遵循 RFC 8259，比多數人預期的更嚴格。鍵必須使用雙引號；字串必須使用雙引號，不能用單引號。物件或陣列最後一個元素後面不能有逗號，沒有任何形式的註解語法，也沒有 NaN、Infinity 或 undefined。數字不能用十六進位表示，不能加正號，整數部分也不能以零開頭。

這種嚴格是刻意的，而不是吹毛求疵：接收端的每一個 JSON 解析器都會套用同樣的標準。在這裡能格式化的文件，在 Python、Go、Rust 與 PostgreSQL 中都能解析。只有在寬鬆解析器幫你猜測意圖後才能運作的文件，之後一定會在某處失敗，而且通常是在正式環境。

如果輸入中有註解或結尾逗號，那它就不是 JSON，而是 JSON5 或 JSONC，也就是 tsconfig.json 這類設定檔使用的寬鬆變體。這些都是真正存在、有實際用途的格式，為了變成合法 JSON 而刪掉註解，是會遺失資訊的修改。請在清楚這一點的前提下進行。

如何解讀錯誤訊息

解析失敗時，錯誤訊息會附上行號與欄號，這是根據引擎回報的字元位移計算出來的。要注意，這個位置是解析器放棄的地方，不一定是你出錯的地方：少了右大括號時，錯誤通常會回報在文件結尾，因為到那裡為止的內容都仍可能是合法的。

幾乎所有失敗都來自四個原因：右括號前多了逗號、字串或鍵用了單引號、從 JavaScript 物件字面值複製過來而沒有加引號的鍵，以及字串值中未跳脫的雙引號或換行。如果回報的欄位指向一個引號，那麼它前面的字串很可能提早結束了。

另一個常見情況是被截斷的文件。因大小限制或逾時而被切斷的回應，在值中途停止之前都能正常解析，所以錯誤會出現在最後一行，而不是任何有參考價值的位置。在文件中間到處搜尋之前，先檢查輸入的結尾。

解析再輸出會改變什麼

格式化會先解析文件，再重新序列化，所以過程中會有幾個地方被正規化，值得知道是哪些。

數字會變成 IEEE 754 雙精度浮點數。任何大於 9,007,199,254,740,991 的整數都會失去精度，這很重要，因為 64 位元資料庫 ID、Twitter 式的 Snowflake ID 與奈秒時間戳記都超過這條線。ID 9223372036854775807 會變成 9223372036854776000。若需要保持完整，請在資料中以字串存放。結尾的零也會消失：1.0 會格式化為 1，1e3 會變成 1000。

重複的鍵會合併，以最後一個為準，因為解析步驟會建立物件。除此之外鍵的順序都會保留，只有一個繼承自 JavaScript 物件的例外：看起來像非負整數的鍵會依數值排序，並移到其他鍵的前面。註解與原本的空白當然都會消失，因為兩者都無法在解析後保留。

樹狀檢視

格式化文字上方有一個可以收合的樹狀檢視。它的用途不同：在不需要捲動數千行縮排文字的情況下，掌握陌生回應的結構、找到你要的欄位在哪裡，以及它巢狀得有多深。把不關心的陣列收合起來，整個結構就能在一個畫面內看清楚。

複製按鈕複製的永遠是格式化後的文字，所以在樹狀檢視中探索，不會改變你貼回編輯器的內容。

JSON 的由來，以及它能裝什麼

JSON 由 Douglas Crockford 在 2000 年代初期定義，是 JavaScript 物件字面語法的一個子集；他的觀察是瀏覽器本來就能剖析它，而 XML 對多數 Web API 來說都太笨重了。它先被標準化為 RFC 4627，後來由 RFC 8259 與 ECMA-404 取代。而它之所以能席捲業界，很大一部分原因就在於整套文法只有一頁。

它的資料模型刻意做得很小：物件、陣列、字串、數字、布林值與 null，就這些。沒有日期型別、沒有二進位型別、不區分整數與浮點數、沒有註解，也沒有辦法讓文件的某一處指向另一處。

JSON 所有令人尷尬的地方，都是從這份清單延伸出來的。日期只能靠約定而不是型別，二進位資料必須編碼成文字，大整數會拖累一個數字通常以 double 剖析的格式，而需要註解的設定檔只能改用方言，或乾脆換一種格式。

日期、金額與大數字

日期方面，已經定案的慣例是採用 UTC 的 ISO 8601，例如 2026-03-14T09:30:00Z。它可以直接按字典序排序，沒有歧義，而且每種語言都能剖析。其他做法都會惹麻煩：Unix 時間戳記會失去秒與毫秒之間的區別，而像 03/14/2026 這種在地化字串，一離開寫下它的國家就不知道該怎麼讀。

金額不應該用 JSON 數字表示。剖析器可以自由採用雙精度浮點數，於是 0.1 加 0.2 那類問題會隨著酬載一起送上門，而且不同語言的進位行為也不一樣。改用整數的最小幣別單位——19.99 英鎊寫成 1999——並把幣別放在另一個欄位，才是任何消費端都吃得下的表示法。

大型識別碼有同樣的問題，只是更尖銳。任何超過 2^53 的值在被剖析成 double 時都會失去精度，這涵蓋了 64 位元的資料庫 id 與 snowflake 類識別碼，因此它們在酬載裡應該是字串。這不是假設性的擔憂：好幾個大型 API 之所以同時回傳 id 與 id_str 兩個欄位，正是為了這件事。

大到放不進記憶體的檔案

會把整份文件建成物件的剖析器，需要好幾倍於檔案大小的記憶體，所以即使機器還有好幾 GB 可用，一份 500 MB 的匯出檔仍可能耗盡一個行程。有兩種做法可以避開這點。

第一種是以換行分隔的 JSON，其中每一行都是一份完整的文件，而整個檔案本身並不是合法的 JSON。它天生適合串流處理，追加成本很低，也是多數日誌管線與批次匯出格式採用的形式。第二種是串流剖析器——Python 的 ijson，其他語言則是 SAX 風格的讀取器——它一邊走訪檔案一邊發出事件，從不把整棵樹具現化出來。

在命令列上，jq 兩種都能處理，而且本身就很值得學：jq '.items[] | {id, name}' big.json 可以在不把文件載入編輯器的情況下取出一個投影。它的 --stream 旗標則涵蓋了連 jq 預設模式都會吃掉太多記憶體的情況。

一份 JSON 酬載的安全面向

在任何現代語言裡，剖析 JSON 本身都是安全的；風險出在剖析之後發生的事。最有名的是原型污染：在 JavaScript 中，把攻擊者可控的 JSON 未經過濾地合併進一個物件，可能設定到 __proto__，進而改變整個行程中每個物件的行為。深層合併類的工具函式一再把這個漏洞送進正式版，防禦方式是明確拒絕那些鍵，或改用沒有原型的物件。

絕對不要對 JSON 求值。在 JSON.parse 還不存在的年代，用 eval 來剖析是真實存在的做法，但它會執行任何送進來的東西。今天任何對資料動用 eval 的程式碼都是一項稽核缺失，而不是風格偏好。

還有兩件比較小、但值得知道的事。用瀏覽器會執行的內容型別去提供 JSON 陣列，正是早年 JSON hijacking 攻擊的基礎，這也是某些 API 至今仍會在回應開頭加上一行破壞迴圈的程式碼的原因。另外，重複的鍵在文法上是合法的，但不同剖析器的處理方式不同，這一點曾被用來讓驗證器看到的值，和應用程式最終讀到的值不一樣。

那些方言，以及何時該用

JSON5 加上了註解、尾隨逗號、不加引號的鍵，以及單引號字串。JSONC 則是更小的變體，Visual Studio Code 的設定檔與 tsconfig.json 都用它——本質上就是 JSON 加註解。兩者都不是 JSON，而且沒有專用套件的話，標準函式庫都剖析不了。

真正關鍵的分野是讀者是誰。由人維護的檔案能從註解中獲得極大好處，所以 JSON5、JSONC、YAML 或 TOML 在那裡都很合理。但要跨越網路傳輸的酬載就該是純粹的 JSON，因為接收端可能是任何語言、任何函式庫版本，而使用方言等於把一項互通性保證換成了一項相依套件。

當你把設定檔貼進嚴格的剖析器而它失敗時，通常代表這個檔案是某種方言，而不是壞掉了。為了讓剖析器通過而把註解刪掉，是在有損地刪改別人寫下的文件，所以請在副本上操作。