03 / 指南
審查之前先格式化並檢視 JSON
面向 API 負載與設定檔的審查流程:先美化列印,以樹狀結構檢視,再確定性地對比兩份文件——全程不把資料發往任何地方。
為什麼格式化排在第一位
壓縮過的 JSON 是為機器準備的:一行到底、沒有縮排、鍵的順序由序列化器隨手產生。讓眼睛去審查那堵牆,被移除的權限、被翻轉的開關、多出來的端點就會這樣溜過去。
美化列印也是你手邊最便宜的合法性檢查:一份解析失敗的文件在正式環境同樣不會正常運作,在審查分頁裡發現這一點,遠好過在部署日誌裡發現。
- 只改可讀性格式化是可讀性變換:它只改變空白與換行,從不改變資料,因此格式化副本總是可以安全地與原文件對照審查。
- 深度即訊號一致的縮排讓巢狀深度一目瞭然,而深度正是設定錯誤的藏身之處——放深一層的選項會被直接忽略。
- 交付期望的形態審查格式化副本,但交付系統期望的形態;美化列印是給人看的,不是給傳輸用的。
檢視樹,而不只是文字
樹狀檢視直接回答審查者真正關心的問題——有哪些鍵、每個值是什麼型別、結構有多深——而不必數括號。原始文字一個問題也答不快。
JSON Tree Viewer 明確解析:按下「解析 JSON」之前什麼也不渲染;非法輸入會得到帶位置的錯誤和修復提示,而不是靜默失敗。結果以可展開的樹呈現,逐節點顯示型別與數量,「Formatted」分頁則按你選擇的縮排展示正規化文件。
解析摘要回報節點數與最大深度,可快速對照負載應有的規模。保留的原型鍵會被拒絕,因此惡意負載無法在你檢視時偽裝成無害資料。
樹還讓審查對話更具體:「items 的第三個元素 price 為 null」是任何人都能秒級驗證的評論,而壓縮行裡的位元組偏移不是。
開啟 JSON Tree Viewer確定性地 diff 兩份文件
一旦鍵的順序變化,用眼睛對比兩份 JSON 就會失效。結構化 diff 解析兩側,回報真正變化的部分——新增、刪除與修改的值——與順序和空白無關。
Text & JSON Diff 提供三種模式:行、字元與 JSON。JSON 模式是審查用的確定性模式:兩份文件先被解析,再逐值比較,因此重排的鍵與重排的空白會正確地回報為完全相同。
對於非 JSON 文字,行與字元模式帶有忽略空白和換行符正規化開關,摘要會計數新增、刪除與修改。負載與設定用 JSON 模式;當一側根本不是合法 JSON 時,退回行模式。
確定性的意義不止於方便:兩位審查者執行同一比較必須得到同一答案,否則審查就變成了關於工具的扯皮,而不是關於變更的決策。
開啟 Text & JSON Diff了解本機執行環境的限制
這些是帶有明確上限的本機執行環境,規模面向審查負載,而不是批量資料處理。知道上限,就知道什麼時候該改用桌面工具。
上限之所以存在,是因為解析與 diff 就在你正在閱讀的同一個分頁裡執行;誠實的上限好過卡死的頁面,而且工作區會把超限回報為明確錯誤,而不是靜默截斷。
- 檢視器上限JSON Tree Viewer 接受最大 256 KiB 輸入、40 層巢狀與 10,000 個節點——應付 API 回應或設定檔綽綽有餘。
- Diff 上限Text & JSON Diff 每側最多比較 256 KiB,最多回報 10,000 條差異記錄,超出即宣告比較過於複雜。
- 超出瀏覽器更大的匯出——資料庫傾印、日誌歸檔、產生的夾具——屬於桌面編輯器或命令列工具,而不是瀏覽器分頁。
五分鐘審查清單
一個能在大多數負載問題進入正式環境之前攔下它們的簡短流程。
對生產方的範例資料和真實負載都跑一遍清單;與現實不符的夾具和錯誤一樣會讓審查失效。
- 解析先格式化並解析:確認文件合法,並掃一眼節點數與深度是否符合預期。
- 檢視檢視樹:檢查葉子處的型別——數字識別碼以字串形式到達,是經典的整合錯誤。
- Diff用 JSON 模式與上一個已知良好版本 diff,逐條讀完所有回報的變化再批准。
讓負載留在你的裝置上
審查負載常常包含客戶記錄、權杖或內部網址。本機檢視器把這些材料留在分頁裡:文字由執行在你裝置上的程式碼解析,整個操作過程中不參與任何網路傳輸。
正是這條邊界,讓這些工具可以在審查中處理真實的預發佈負載。它並不免除你自己的責任:匯出的檔案、剪貼簿內容與樹的螢幕截圖,一旦離開工作區仍由你謹慎處理。
如果必須在審查中分享負載片段,只貼上能說明問題的最小摘錄,並先隱去識別碼——與支援渠道要求的紀律相同。
為什麼「本機檢視」是可信的說法。
了解瀏覽器執行環境如何把資料留在裝置上,以及如何驗證你用來審查的任何工具的資料路徑。