JSON 转 TOML:把接口数据写成人能读的配置

我手里常有一堆 JSON,接口返回的、后台导出的、脚本拼出来的,可真正要落地的文件却是 TOML。Rust 项目的 Cargo.toml、Python 项目的 pyproject.toml、还有 Hugo 和 Netlify 的站点配置,读的都是 TOML。两边数据其实一模一样,只是标点和排版不同,手动重敲一遍既慢又容易出错,漏个引号或多个逗号,解析器立刻翻脸。

TOML 到底是什么

TOML 是 Tom's Obvious Minimal Language 的缩写,一种为人易读、又能干净映射成哈希表而设计的配置格式。它的语法很克制:一行键值写成 name = "toolora",一个区段标题写成 [database],一个可重复区段写成 [[servers]]。没有花括号,没有满地的逗号,文件能从上往下顺着读下来。

你最常在三个地方碰到它。Rust 的包管理器 Cargo 用 Cargo.toml 描述依赖和元数据,Python 的现代打包标准把工具配置统一塞进 pyproject.toml,很多命令行工具也拿 TOML 当默认配置。它流行的原因很直白:配置是给人手动编辑的,而不是给机器流式传输的,所以读写体验比什么都重要。

表 [table] 和键值是怎么对应的

理解 TOML 的关键,是看懂嵌套对象怎么变成「表」。每个嵌套的 JSON 对象,都会变成一个由点号键路径作标题的 TOML 表。

举个具体的:JSON {"owner": {"name": "Li"}} 会变成一行 [owner] 标题,后面跟着 name = "Li"。再往深一层,{"a": {"b": {"c": 1}}} 会依次输出 [a]、[a.b],最后才是 c = 1。这里有个排版规矩:同一层级里的标量值要先写,子表后写,因为一个新的表头会结束上一个表的正文,顺序错了输出就不合法。

对象数组又是另一套写法。元素全是对象的数组,会变成「对象表数组」,用双方括号标记。输入 {"servers": [{"host": "a"}, {"host": "b"}]} 生成两个区块,一个 [[servers]] 带 host = "a",第二个 [[servers]] 带 host = "b"。而纯数字或字符串的扁平列表,则保持行内写法,比如 ports = [8001, 8002, 8003],短数据行内更紧凑。

一段完整的转换例子

光说规则不直观,贴一段真实的输入输出。下面这段 JSON:

{
  "package": { "name": "toolora", "version": "1.4.0" },
  "ports": [8001, 8002],
  "servers": [
    { "host": "alpha", "weight": 5 },
    { "host": "beta", "weight": 3 }
  ]
}

转成 TOML 后是这样:

ports = [8001, 8002]

[package]
name = "toolora"
version = "1.4.0"

[[servers]]
host = "alpha"
weight = 5

[[servers]]
host = "beta"
weight = 3

注意三件事:顶层的标量数组 ports 留在最前面当行内数组;package 对象升格成 [package] 表;servers 这个对象数组裂成两个 [[servers]] 区块。还有一点容易踩:TOML 没有 null 字面量,所以值为 null 的键会被直接省略,而不是写成解析不了的 key = null。想保住这个键,得在转换前把 null 换成空字符串或占位值。这些细节你不用记,丢进 JSON 转 TOML 在线工具直接出结果。

为什么 TOML 比 JSON 更适合人写配置

JSON 适合机器之间传数据,它支持 null,字段名加引号,严格到几乎没有歧义。可一旦让人手动维护配置,那堆花括号和逗号就显得很吵:缩进对不齐、尾逗号报错、改一个值要盯着括号配对。TOML 把这些标点去掉,换成 [section] 标题和裸键值,还内建了日期类型,ISO 日期字符串能被解析器当真正的日期读。代价是它没有 null,面对结构很不规则的深层树也不顺手,但配置文件本来就该是规整的,这个取舍很值。

和 YAML 的区别

很多人会问,既然要给人写,YAML 不也行吗?两者确实都比 JSON 清爽,但路子不同。YAML 靠缩进表达层级,空格数量决定结构,一个 Tab 混进去就可能解析错位,深层嵌套时尤其难数清自己在第几层。TOML 反过来,用显式的 [a.b.c] 表头把路径写死,层级一眼可见,不依赖缩进。所以 Cargo 和 pyproject 选 TOML,要的就是这份确定性:复制一段配置进文件,不会因为缩进被编辑器改动而崩。如果你的目标格式是 YAML,可以走 JSON 转 YAML,反向则用 YAML 转 JSON。

说到底,JSON、TOML、YAML 三者只是同一份数据的不同外衣,挑哪件取决于谁来读。机器之间传,JSON;给人手动编辑配置,TOML;这之间的转换交给工具,你省下的是核对括号的眼力。

Made by Toolora · Updated 2026-06-13