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