開發者工具 · JSON 格式化程式和驗證程序
為什麼 JSON 沒有評論：設計決策及其解決方法
· 背景
json 標準 驗證
評論被故意從 JSON 中刪除。這篇文章解釋了原因，為什麼每次嘗試添加它們都會創建一種新格式，以及當配置檔案確實需要註釋時您的選擇是什麼。
破壞建構的評論
破壞建置的註解 - 新增至 JSON 配置和在第一個斜線處停止的解析器的有用註解。作者可能從 JavaScript 或支援 JSONC 的編輯器複製了模式，而部署工具則使用嚴格的 JSON。即使消費者拒絕第一個評論標記，語法突出顯示也可以使註釋看起來合法。
註解被拒絕，因為斜線不是掃描器期望值或成員的 JSON 標記。 ToolAcre 不會默默地剝離 JSONC 或 JSON5 語法。傳統的註解形屬性是普通資料，即使嚴格的 JSON 語法接受它，也可能違反應用程式模式。關於 JSON 設計的不受支持的歷史主張被省略或修正，而不是在沒有主要證據或可追溯的標準來源可用於驗證的情況下作為既定事實呈現。
Crockford 刪除評論的原因
Crockford 刪除註解的原因 - 後來的解釋說註釋已被用來攜帶解析指令，破壞了實作之間的互通性。相關的設計結果是標準 JSON 沒有註解標記。有關私人動機、準確年代或普遍行業反應的主張需要此存儲庫未提供的歷史來源。
因此，此處省略或修正了不受支持的歷史主張。可觀察的標準和解析器行為就足夠了：嚴格的 JSON 透過六種值類型和兩個容器交換資料，無需註釋通道。此限制阻止一個接收者將操作意義分配給另一個接收者忽略的文字，但它也使 JSON 不太適合手動維護配置。
驗證者對評論的報告內容
驗證器對評論報告的內容 — `//` 和 `/* */` 不在語法中，因此錯誤出現在帶有行和列的第一個斜杠上。掃描器並不反對紙條上的文字。它不能在該位置以 `/` 開頭任何有效的 JSON 值、成員名稱或分隔符號。
For `{"port":8080, // local only "secure":false}`，逗號有效，下一個合法標記應該是帶引號的屬性名稱或右大括號。斜杠違反了這項期望。僅刪除註釋會留下有效的分隔符號和下一個成員；刪除附近的標點符號可能會產生第二個錯誤。每次編輯後重新驗證準確的嚴格輸出。
新增評論的格式
新增註解的格式 — JSONC 允許圍繞其他熟悉的 JSON 語法進行註釋，而 JSON5 增加了便利性，例如不帶引號的標識符鍵和尾隨逗號。 Hjson 強調人工編輯和額外的寬鬆語法。 YAML 有自己的語法，包括註釋，而不僅僅是添加了註釋的 JSON 。
接受是特定於消費者的：編輯器設定和 TypeScript 配置可能使用允許註解的解析器，而套件清單或 API 正文可能需要嚴格的 JSON。 Kubernetes 通常會根據其工具使用 YAML 或 JSON。命名檔案和檔案處理中的實際格式；剝離擴充或呼叫每個物件符號「JSON」會隱藏相容性邊界。
嚴格 JSON 內的解決方法
嚴格 JSON 內部的解決方法 — 傳統的 `_comment` 或 `//` 鍵將解釋儲存為普通字串成員。它能夠通過嚴格的解析，因為鍵和值都使用標準標記。多個註釋需要唯一的鍵或數組，因為重複的成員名稱不可靠且可能會被解析器折疊。
解決方法變更資料模型。帶有 `additionalProperties: false` 的模式可以拒絕註釋，並應用程式可以將其作為真實配置保留或傳輸。外部檔案、相鄰的自述檔案或模式 `description` 通常提供更安全的解釋管道。僅當每個消費者明確允許並忽略它們時才使用評論形成員。
工作範例：附註解的設定檔案
工作範例：附註解的設定檔 — 以包含 `"timeout":30` 上方的 `// seconds before retry` 的 JSONC 來源開始。如果目標只接受 JSON，請使用理解 JSONC 的解析器來產生數據，然後將該資料序列化為嚴格的 JSON。部署的工件變成 `{"timeout":30}`，而維護的來源保留其解釋。
不要使用正規表示式刪除註解。斜線序列可以合法地出現在字串（例如 URL）內，區塊註解模式可以以文字替換錯誤處理的方式跨行。保持來源和產生的工件不同，驗證嚴格的結果並在建置中排程重新產生。這保留了作者註釋，而不假裝接收解析器支援它們。
這不包括什麼
這不包括什麼——如何配置單一解析器來接受註釋，這是特定於工具的並經常變化。一個庫中的許可選項不會改變 JSON 語法或保證另一個服務將接受相同的文字。檢查解析器、版本和目標，而不是依賴編輯器的顯示。
本文也避免了關於評論被刪除的確切時間、誰首先採用每種解決方法或是否單獨一個設計決策導致 JSON 受歡迎的不受支持的說法。這種歷史斷言需要獨立的主要來源。此處省略或更正；支援的結論僅限於當前嚴格的語法、儲存庫行為以及命名格式之間的操作差異。
重點： JSON 是一種資料交換格式，而不是配置語言
重點： JSON 是一種資料交換格式，而不是一種富含註釋的配置語言 - 並驗證器準確顯示註釋在哪裡違反了嚴格的語法。當人們需要註釋時，選擇使用工具正式支援的格式或維護產生單獨的嚴格工件的註釋來源。不要以為評論會被無害地忽略。
如果嚴格的 JSON 是強制性的，請將說明移至檔案或使用模式批准的元資料，然後驗證最終檔案。 ToolAcre 有意報告第一個斜杠，而不是靜默刪除材料，因為靜默轉換可能會更改字串或隱藏格式不匹配。歷史背景應該保持同樣的紀律：省略或糾正不受支持的主張，而可觀察的語法和解析器行為則得出結論。