TOML 转 JSON

关于 TOML 转 JSON

把 TOML 转成 JSON 通常是为了让只认 JSON 的消费方读到同一份配置，例如把本地工具链的配置文件喂给前端构建、或把配置注入到以 JSON 为契约的服务。相比手工誊写，转换能保证结构完整，也避免了在嵌套表上的低级错误。 转换原理是把 TOML 解析成对象树，再按 JSON 规则序列化。TOML 的段头语法让层级表达更显式，因此转换后的 JSON 层级往往一目了然；但两种格式在类型上的差异需要留意：TOML 的日期时间是独立类型，JSON 里只可能是字符串，序列化实现决定它带不带偏移量与毫秒，下游按字符串解析时必须先确认形态。 使用要点：转换后先核对键的总数与每个分支的键数，确认没有结构丢失；再检查数组——TOML 中数组可以混合类型，而多数语言的 JSON 消费方假定数组元素同类型，混合数组会带来反序列化问题。规范上 TOML 允许数组元素类型不一致，这种数据在跨语言传递时最容易出错，遇到时应先决定要不要拆成多个字段。 边界与限制：注释必然丢失，需要说明的配置应另存文档。TOML 支持用点号表达层级，转换后仍然是嵌套对象，但若源文件里既有字面含点号的键又有段头表达的层级，解析结果可能不是你直觉预期的那一种，这种歧义应在源文件层面消除而不是在转换后补救。此外数字方面，TOML 支持十六进制与下划线分隔等写法，转换后统一变成十进制数字，若下游依赖原表示形式会受影响。 数据与隐私：这类配置文件通常含凭据与内部地址。本工具在浏览器内完成转换，不上传内容；把配置转成 JSON 再注入服务时，注意不要连同调试开关与内部端点一起发布出去。

工程上建议把转换做成一条可重复执行的流水线步骤，而不是人工偶发操作：源文件改动后自动重生成，并在流水线里比对产物与提交内容是否一致。这样既保证了产物的可追溯性，也能立刻发现「有人直接改了生成结果」这种情况。若配置本身较大，还可以在转换后追加一次结构校验，例如用模式文件验证必需字段与类型，把错误挡在构建阶段而不是等到服务启动时才暴露。

上手建议先用一份小配置验证输出结构，确认数组与日期字段的形态符合下游预期，再处理完整文件。维护上，把「源文件改动后必须重新生成」写进提交流程并加一条自动化校验：若提交的产物与重新生成的结果不一致就拒绝合并。这条规则成本很低，却能杜绝「有人只改了产物没改源文件」这种最难排查的漂移，尤其是在多位成员共同维护同一份配置的项目里。 在合并请求里附上重新生成的产物，评审者可以直接看到配置变更的真实影响，而不必自行还原。 把这条规则写进提交检查脚本，漂移就无从发生。