JSON ↔ YAML 转换完全指南：有损无损、类型坑与配置迁移

1. 两种格式各自擅长什么

JSON 与 YAML 都能表达对象、数组、字符串、数字、布尔和空值，但工程角色不同。

何时优先 JSON： API 响应、前端状态、多数语言的标准库开箱即用、需要严格可互操作的契约。

何时优先 YAML： K8s、Compose、CI、Ansible、Helm values——人要改、还要写注释和多段文档。

两者不是「同一种东西的两种皮肤」。互转是投影：能保留的是共享数据模型；格式专属能力会在边界被削掉。

2. 有损与无损：一张对照表

下面按「往返一次是否还能得到等价结构」判断。等价指解析后的数据模型一致，不要求空白、键序、引号风格完全相同。

实践原则：

1. 配置源以 YAML 为权威时，JSON 只是导出物；不要把导出 JSON 再写回覆盖带注释的 YAML。
2. 接口契约以 JSON 为权威时，YAML 只是给人看的草稿；提交前应用 JSON Schema 或示例响应校验。
3. 任何「看起来像数字/布尔」的业务码，在 YAML 里加引号，再转 JSON，避免静默变类型。

前后对照示例

合法 JSON：

{
  "replicas": 3,
  "image": "nginx:1.25",
  "debug": false,
  "note": "生产勿开"
}

转成常见 YAML 形态（风格因实现略有差异）：

replicas: 3
image: nginx:1.25
debug: false
note: 生产勿开

若 YAML 写成未加引号的版本号与开关，再转回 JSON 可能变成：

{
  "port": 80,
  "enabled": true,
  "version": 1.10
}

而你本意可能是字符串 "1.10"（保留尾零）或字符串 "80"。类型一旦在中间态被猜错，业务校验会在很远的地方才爆。

故意有损的 YAML（含注释与多文档）无法完整变成单个 JSON 值：

# 仅文档 A
---
name: api
---
name: worker

在线转换器通常只能给你其中一个映射，或直接报错。正确做法是按文档切开，分别转换。

3. 类型坑：YAML「帮你猜」时最伤

JSON 类型集合小而硬：string / number / boolean / null / object / array。YAML 1.1 风格的解析器常把未加引号的标量猜成布尔、整数、浮点、时间戳。WebUtils 转换页基于浏览器内的 js-yaml 一类实现，行为接近常见前端工具链，但不等于你服务器上的 PyYAML 或 Go yaml.v3 逐字节一致。

国家代码、工号、订单号、权限码、镜像 tag 中的数字——一律当字符串处理，直到你证明业务层要的是数值运算。

JSON 侧也有坑：标准 JSON 没有 undefined，没有 NaN/Infinity，键必须双引号。从 JS 对象 JSON.stringify 时 undefined 字段会被丢弃；若你先在控制台抄「长得像 JSON」的对象字面量（单引号、尾逗号），转换器会先在 JSON 解析阶段失败——这时应先走 JSON 格式化 修到合法，再转换。

4. 在 WebUtils 上怎么转

主工具页：JSON 转 YAML / YAML 转 JSON（站点另有开发分类下的 dev 版，能力同属互转；本指南步骤以 converter 双栏为准）。

JSON → YAML

1. 打开转换页，左侧（或 JSON 区域）粘贴文本。
2. 若来源是压缩一行或可疑片段，先在 JSON 格式化 校验并美化，确认无语法错误。
3. 点击 「JSON ➔ YAML」。
4. 在 YAML 区域检查：层级是否与原对象一致、布尔与数字是否仍是你期望的类型、字符串是否被无意义地拆行。
5. 需要复制时用区域旁的 复制；贴进仓库前在本地再用项目同款解析器（如 kubectl、yamllint、CI 里的 schema）扫一遍。

YAML → JSON

1. 将 YAML 粘贴到 YAML 区域。多文档时先手工只保留当前要转的一段。
2. 缩进混乱或 Tab 混用时，先用 YAML 格式化 统一空格并校验。
3. 点击 「YAML ➔ JSON」。
4. 打开结果，重点盯：曾未加引号的字段类型、原注释是否已消失（预期行为）、根是否仍是对象/数组。
5. 若下游是 API，用格式化工具再缩进一次，便于 Code Review；入库或传输再考虑压缩。

失败时看什么

• JSON 解析失败： 缺逗号、单引号、尾逗号、多余 undefined——回格式化工具定位行列。
• YAML 解析失败： 缩进不对齐、: 后空格缺失、Tab——回 YAML 格式化或对照错误表。
• 能转但「值不对」： 几乎总是类型猜测或注释/多文档被丢掉——回到上一节对照表，而不是反复点转换按钮。

处理含账号、Token、内网地址的配置时，先脱敏再粘贴。WebUtils 工具在浏览器本地处理，不替代你的保密规范；公共电脑上用完应清空文本框。

5. 常见错误与处理

6. 真实工作场景

场景 A：接口 JSON 改成 Helm values 草稿

后端给了应用配置的 JSON 样例，要写进 values.yaml。步骤：JSON 格式化确认结构 → 转到 YAML → 人工加注释（环境差异、密钥来源）→ 把密钥改成 valueFrom 或占位符，不要把生产密钥留在 values 里再提交。往返时以 Git 中的 YAML 为准，JSON 样例只作初始骨架。

场景 B：同事只发 YAML 片段，前端 Mock 要 JSON

从 Compose 或 Action 里抠出一段 environment 映射，需要变成前端 mock 或 Postman body。先确认片段是单一映射而非多文档；YAML→JSON 后检查所有环境变量值是否仍为字符串（PORT: 8080 常被收成数字，而 process.env 体系里往往是字符串）。

场景 C：K8s 与运维脚本双轨

GitOps 仓库用 YAML，某审计脚本只吃 JSON。流水线里应用同款库做转换并跑 schema，而不是每次人工点在线工具。在线工具适合改一两个字段时的即时预览；批量与门禁仍应自动化。转换后用 JSON Diff 对比「上一版导出」与「本版导出」，避免缩进美化造成的假差异干扰——对比前两边都格式化。

场景 D：OpenAPI 同时提供 JSON 与 YAML

规范允许两种表达。编辑时选一种为源（许多团队用 YAML 方便 diff 注释），发布时生成另一种。生成物中的 $ref、discriminator 等结构应保持引用语义；若在线工具把复杂文档扁成丢失引用的树，说明该文件超出「简单配置互转」范围，应改用官方/专用转换链。

8. 相关工具怎么选

决策一句： 语法不合法 → 格式化工具；合法但要换皮给另一生态 → 转换工具；换完要证明没改业务字段 → Diff。

9. 常见问题

10. 下一步

1. 打开 JSON ↔ YAML 转换，用本文「replicas / image / debug」示例走通 JSON→YAML。
2. 故意写一段带 yes 与 1.10 的 YAML，转 JSON 观察类型，再改成加引号的版本对比。
3. 把真实工作中的一份非敏感配置走「格式化 → 转换 →（可选）Diff」闭环，把检查清单固化进团队习惯。
4. 若日常主要是改 YAML 缩进，收藏 YAML 格式化；主要是追 API 字段，收藏 JSON 格式化。