TOML 轉 JSON

TOML 是寫給人改的：它有節標題、可以加註解、支援多行字串和點號鍵，強調「設定看起來像一份文件」。JSON 是寫給程式用的：只有物件和陣列，沒有註解，鍵必須嚴格加引號。把 TOML 轉成 JSON 的那一刻，設定檔正式從「人維護」進入「機器消費」的鏈路——下游可能是介面、是 Schema 驗證器、是除錯控制台，也可能是某種語言執行時。這一步的意義，是把人友善的寫法整理成程式可信的輸入。

形態會變，意義應當保持

转换后的 JSON 看起来跟原文件完全不同：注释没了、空行没了、节标题没了、点号写法被还原成嵌套对象。这都是正常的——JSON 本身不承担这些“可读性元素”。真正必须守住的，是结构层面的等价：每一个 `[table]` 应当对应一个对象，每一个值的类型应当保留，每一个键在 TOML 里能怎样访问，在 JSON 里就应当按同样的逻辑路径访问。

TOML 的構件如何映射到 JSON

TOML 和 JSON 共享大多数基础类型，只是写法不一样。提前记住映射关系，可以在转换前就预判输出结构，也可以在转换后一眼看出“哪里不对”。

• `[server]`、`[database.primary]` 這樣的表節會變成巢狀 JSON 物件，每多一個點號就多一層巢狀。
• `[[entries]]` 表数组对应同一个键下的对象数组，每出现一次 `[[entries]]` 就追加一个对象。
• 内联表 `{ ... }` 和数组 `[ ... ]` 在 TOML 里就是接近 JSON 的写法，几乎是一对一翻译。
• 整数、浮点、布尔、字符串保留类型；多行字符串和字面量字符串拍平成普通的 JSON 字符串，但内容保持一致。
• TOML 的日期与时间在 JSON 里只能用字符串表示（JSON 没有原生日期类型），这本身没问题，前提是下游知道按 ISO 8601 字符串去解析它。
• 注释和空行在 JSON 里没有对应概念，会被丢弃——它们是“文件”的一部分，不是“数据”的一部分。

一句話原則：對每一處「你為什麼這樣寫 TOML」，去檢查轉換後的 JSON 是否仍然不含歧義地表達了同樣的意圖。

如何使用這個工具

1. 先在 TOML 轉 JSON 中准备一份有代表性的需要转成 JSON 供接口、解析器或審查工具使用的 TOML 配置檔案，不要一开始就處理最大或最敏感的真实内容。
2. 执行處理流程并產生映射 TOML 表节和值的 JSON 文字后，優先檢查表节、数组、布尔值、字元串、嵌套結構，以及原檔案中的注释或排版是否携带额外含义，再判断结果是否真的可用。
3. 只有当结果已经適合用于配置迁移、解析器輸入、接口 payload 准备和工具審查，并且不再触发這条风险提醒时，才複製或下载輸出：TOML 注释和排版意圖在轉換后不会保留，因此應把審查重点放在資料結構而不是檔案外观上。

TOML 轉 JSON 範例

這個 TOML 轉 JSON 示例使用有代表性的需要转成 JSON 供接口、解析器或審查工具使用的 TOML 配置檔案，展示產生后的映射 TOML 表节和值的 JSON 文字，便于你先確認表节、数组、布尔值、字元串、嵌套結構，以及原檔案中的注释或排版是否携带额外含义，再把同样設定用于真实輸入。

範例輸入

title = "ToolKit Online"
draft = false

預期輸出

{
  "title": "ToolKit Online",
  "draft": false
}

一份小型 TOML 與對應的 JSON

# TOML
title = "Sample"
enabled = true

[server]
host = "localhost"
port = 8080

[database.primary]
url = "postgres://localhost/app"
pool = 20

[[entries]]
name = "alpha"
weight = 1.5

[[entries]]
name = "beta"
weight = 2.0

# JSON
{
  "title": "Sample",
  "enabled": true,
  "server": { "host": "localhost", "port": 8080 },
  "database": { "primary": { "url": "postgres://localhost/app", "pool": 20 } },
  "entries": [
    { "name": "alpha", "weight": 1.5 },
    { "name": "beta", "weight": 2.0 }
  ]
}

什麼時候應該把 TOML 轉成 JSON

TOML 是给人用的源头，JSON 是大多数自动化工具的输入。这两类受众需要共享同一份数据时，转换就是中间那座桥。

• 把設定傳給只接受 JSON 的 HTTP 介面或 Schema 驗證器。
• 排查一份较大的 TOML 文件：把它转成 JSON 后丢进浏览器 DevTools 的对象树里，往往比逐行翻原文件更快定位结构。
• 为已有的 TOML 配置生成一份 JSON Schema（draft-07）草稿，把“期望的结构”固化下来。
• 在前端打包产物里需要内嵌配置、但运行时不方便引入 TOML 解析器时，先转成 JSON 再嵌入。
• 与只能处理 JSON 的工具/同事共享一份配置快照（如某些 Lint 工具、在线格式化器、没有 TOML 库的脚本环境）。

轉換後最值得複核的幾個邊界

TOML 和 JSON 大部分对得上，但有几处它们并不一致，而且偏偏是“线上会出事”的几处。提前复核一下，可以省下很多排错时间。

• 註解和空白行會全部消失：如果設定依賴某條註解來解釋含義，應當在轉換前先把這條資訊搬到 README 或一個專門的 `description` 欄位裡。
• 日期和时间会变成字符串：下游需要显式 ISO 8601 解析，不要假设 `Date.parse` 在所有运行时里行为一致。
• 數字：TOML 支援大整數和明確的十六/八/二進位寫法，JSON 只有一種數字型別。轉換後要確認精度仍然足夠，尤其是 64 位元整數會不會在 JavaScript 那一側丟精度。
• 同一前缀的点号键既出现在 `[table.sub]` 里又出现在 `table = { sub = ... }` 形式里，转换器应当报错而不是默默合并。出现“两种写法混用”时优先在源头统一。
• 表数组 `[[entries]]` 和内联数组 `entries = [...]` 写法看起来相似，但语义和适用场景有差异，转换后要去对照下游期望的 JSON 形状。

TOML 與 JSON 各自的強項對比

使用注意

• 複用映射 TOML 表节和值的 JSON 文字前，先檢查表节、数组、布尔值、字元串、嵌套結構，以及原檔案中的注释或排版是否携带额外含义。
• TOML 注释和排版意圖在轉換后不会保留，因此應把審查重点放在資料結構而不是檔案外观上。
• 当结果会影响生产工作或客户可见内容时，應保留原始需要转成 JSON 供接口、解析器或審查工具使用的 TOML 配置檔案以便回退和核对。

TOML 轉 JSON 參考說明

TOML 轉 JSON 的参考說明應始终围绕需要转成 JSON 供接口、解析器或審查工具使用的 TOML 配置檔案、產生的映射 TOML 表节和值的 JSON 文字，以及用于配置迁移、解析器輸入、接口 payload 准备和工具審查前必须確認的檢查点。

• 輸入重点：需要转成 JSON 供接口、解析器或審查工具使用的 TOML 配置檔案。
• 輸出重点：映射 TOML 表节和值的 JSON 文字。
• 複核重点：表节、数组、布尔值、字元串、嵌套結構，以及原檔案中的注释或排版是否携带额外含义。

參考資料

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• ECMA-404: The JSON Data Interchange Syntax
• TOML v1.0.0