JSON 转 YAML

关于 JSON 转 YAML

JSON 与 YAML 表达的是同一类数据（映射、序列、标量），但服务的人群不同：JSON 面向程序解析，标点严格、不允许注释；YAML 面向人编写，用缩进代替括号、允许注释、支持多行字符串。Kubernetes 清单、CI 流水线、Ansible 剧本、Docker Compose 都是 YAML，而接口返回与前端配置几乎都是 JSON。于是「把接口返回的 JSON 变成可以直接写进配置文件的 YAML」成了排障与搭建环境时的日常动作。 转换原理是把 JSON 解析成内存中的对象树，再按 YAML 的规则重新序列化：对象变成键值对，数组变成以短横线开头的列表，字符串按需加引号，多行字符串改用竖线或大于号表示。全程在浏览器内完成，不需要任何服务端参与，因此可以断网使用，也不会把配置内容发到外部。 使用要点有几个。缩进宽度建议固定为 2 空格——YAML 不允许用制表符缩进，混入制表符会直接解析失败，而很多编辑器在粘贴时会把空格自动转成制表符，务必检查。字符串里若出现冒号、井号、前导空格或以数字开头，必须加引号，否则会被解释成键或注释，这类错误在中文内容里尤其常见。键的顺序：JSON 对象无序，转换后通常保留插入顺序，但不要把它当作契约，需要稳定顺序时应显式排序。 边界与限制值得单独说明。JSON 允许一个文件里只有一个顶层值，因此转换结果也只有一个顶层节点；如果手上有多个 JSON 文件想合并成一份 YAML，需要先自行合并成数组或映射。精度方面，超过 2 的 53 次方减一的整数会在 JSON 解析阶段就丢失精度，源数据里的雪花 ID 转成 YAML 后末位已经变零，这不是转换器的问题，而要在数据源头改。日期时间在 JSON 里只是字符串，YAML 有专门的时间类型，某些解析器会自动把形如 2026-01-01 的字符串转成日期对象，若下游按字符串处理就会报类型错误，稳妥做法是加引号强制为字符串。 数据与隐私：要转换的内容往往是包含数据库地址、密钥、内网域名的部署配置，属于最不该外泄的一类材料。本工具全部在浏览器内完成解析与序列化，不发送任何请求；转换前可以先断开网络，或在开发者工具的网络面板里确认整个过程中没有任何带载荷的请求发出。

放进 Helm、Kustomize 这类模板工具时还要意识到一层区别：模板会在渲染阶段再做一次替换，因此在模板里写的字符串可能被再次解释。若某段文本包含模板语法符号（双大括号），必须先转义或改用变量注入，否则转换看起来成功、渲染时却报找不到变量。交接时把「转换后仍需人工确认的三处」写进变更说明，能让评审与回滚都快得多。 一个容易被忽略的细节是键名大小写：YAML 本身对键名大小写敏感，但某些框架在读取后会把键名转成小写，于是 camelCase 的键在运行时变成全小写导致取值失败，交接时把键名规范写进文档可以省掉一轮联调。