数据格式与结构化数据

JSON 转 TOML 时 null 和日期会怎样？

使用工具

改配置格式不只是改扩展名。字符串 true 与布尔 true、null 与空值、日期字符串与日期类型都不同。先用小配置往返 JSON/TOML，再核对应用期望类型。

初始 JSON 输入

{"name":"demo","enabled":true,"retries":3,"ports":[8000,8001]}

转换后确认 name 为字符串、enabled 为布尔、retries 为数字、ports 为数组，再把结果转回 JSON。空白和键展示顺序可不同，但值与类型应相同。先独立写下 demo、3、8000/8001 等预期。

方向由首字符推断：{ 或 [ 被当作 JSON。因此以表头开头的 TOML 会与判定冲突。本文 TOML 例子先写键值行，遇到判定失败应视为工具限制。

会被拒绝的 null 例子

{"name":"demo","timeout":null}

TOML 无 null 值，因此转换拒绝。不要仅为消除错误改成 0 或空字符串：0 可能表示不等待、无限等待或非法，省略键可能启用默认值。转换器不能决定应用语义。

应明确记录语义修改，例如省略 timeout:null 以使用接收方默认值。删掉数组中的 null 会移动后续位置，与删除对象属性不同，审查时必须区分。

比较日期有无引号的 TOML

name = "demo"
created = 2026-01-02T03:04:05Z
label = "2026-01-02T03:04:05Z"

默认拒绝日期类型，请先选择将TOML日期转换为字符串。created 是 TOML 日期时间，label 是字符串。JSON 中两者可能都像日期字符串，转回时 created 不一定恢复原类型。外形相似不证明类型保留，应检查应用实际收到的类型。

规范化可能改变小数秒或偏移写法。时刻相同也不代表日志或签名所需原文相同。应区分本地日期、带偏移时刻和标签，并决定哪些字段必须保持字符串，不要推测时区。

带理由注释的 TOML

retries = 3 # temporary limit for the test environment
name = "demo"

注释不会作为 JSON 值保留。retries 仍为 3，但选择 3 的运维理由可能丢失。这不是数值变化，却影响维护，应决定把理由放入文档还是保留原配置。

空行和键顺序也可能变化。应分开看外观差异和值差异，必要时转 JSON 做结构比较。但这仍不保证注释或 TOML 特有类型等价，应组合多个明确范围的检查。

JSON 转 TOML 被拒绝的整数

{"id":9007199254740993}

JSON 整形能保留的数字不代表 TOML 转换也支持。此输入超出精确转换范围而被拒绝。格式的整数范围与实现的转换范围不同，不要舍入 ID 来通过，应确认协议是否允许字符串。

按数字、布尔、数组、null、日期、注释列检查表。单例通过不等于迁移完成，应逐类测试实际数据。转换器限制不授权改变配置契约；若必要信息无法保留，应重新选择方法或格式。