ZonoTools

JSON 转 YAML 的常见错误和修正方法

作者 ZonoTools11 分钟阅读

缩进错误

YAML 用空格表达结构，而不是 {}。转换 JSON to YAML 后，如果某一行多缩进或少缩进一级，子节点可能变成兄弟节点。

这个 JSON 中，host 和 port 属于 server：

如果 YAML 中 port 和 server 对齐，parser 会把它当作顶层 key。文件可能直接报错，也可能解析成错误树。

修正： 统一两个空格缩进，禁止 tab，并在 merge 前用 YAML Validator 检查。

json
{ "server": { "host": "0.0.0.0", "port": 8080 }}

数据类型问题

JSON 的 true、false、null、number 和 string 很明确。YAML 更灵活，有些 parser 会把 yes、no、日期或 null 解读成特殊类型。

如果 API 期望字符串，这些值就可能被悄悄改类型。

修正： 需要保持文本时加引号：

`yaml
flags:
enabled: "yes"
region: "null"
cutoff: "2024-01-15"
`

yaml
flags: enabled: yes region: null cutoff: 2024-01-15

数组格式错误

JSON 用 [] 表示数组；YAML 用 - 表示列表项。列表项必须在同一列对齐。

如果 upstream: direct 不属于第二个 - path，路由表就变了。

修正： 不要在转换后手工大幅调整长列表。结构可疑时，从 JSON 重新生成并验证所有同级 - 对齐。

yaml
routes: - path: /api upstream: svc - path: /health upstream: direct

特殊字符

YAML 会赋予 :、#、{}、[] 和行首 - 特殊含义。URL、错误消息和 connection string 最容易出问题。

# 可能开启注释。安全写法是：

`yaml
message: "Error: disk full (see log #42)"
`

yaml
message: Error: disk full (see log #42)

如何避免错误

把 JSON -> YAML 当成编译步骤，而不是随手复制粘贴：

  • 用 JSON Validator 验证源 JSON。
  • 用 JSON to YAML 转换。
  • 用 YAML Validator 检查输出。
  • 在 CI 中禁止 tab 和模糊 scalar。
  • 保留包含 null、空数组、日期、URL 和 # 的 golden samples。

结论

大多数 JSON to YAML 错误都落在四类：缩进、隐式类型、列表归属和引号。把这些点显式化，配置就不会因为隐形细节在部署时失败。

推荐工具

footer=