DevToolkit Pro

什么是 YAML 和 JSON

在现代软件开发中，数据序列化格式无处不在。YAML 和 JSON 是两种最常用的结构化数据表示格式，它们各有特点，适用于不同的场景。

YAML 的定义和特点

YAML（YAML Ain't Markup Language）是一种人类友好的数据序列化标准，由 Clark Evans 于 2001 年首次提出。它的设计目标是让数据既易于人类阅读和编写，又便于机器解析和生成。

YAML 的核心特点：

• 可读性强：使用缩进表示层级结构，类似 Python 的语法风格
• 简洁语法：不需要引号、大括号等冗余符号
• 丰富的数据类型：支持字符串、数字、布尔值、日期、空值、列表、字典等
• 高级特性：支持锚点（&）、别名（*）、多行字符串、复杂键等
• 注释支持：可以使用 # 添加注释，方便文档化

一个简单的 YAML 示例：

name: DevToolkit Pro
description: 开发者在线工具集
version: 2.0
features:
  - 格式转换
  - 编码解码
  - 文本处理
  - 加密哈希
is_free: true
founded: 2024-01-15

JSON 的定义和特点

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，由 Douglas Crockford 在 2001 年左右推广。它源于 JavaScript 语言，但现在已经成为几乎所有编程语言都支持的通用格式。

JSON 的核心特点：

• 语法简洁：使用大括号 {} 和方括号 [] 表示结构
• 机器友好：解析速度快，几乎所有语言都有原生支持
• 数据类型有限：支持对象、数组、字符串、数字、布尔值、null
• 无注释：标准 JSON 不支持注释
• 严格格式：键名必须用双引号，字符串必须用双引号

同样内容的 JSON 示例：

{
  "name": "DevToolkit Pro",
  "description": "开发者在线工具集",
  "version": 2.0,
  "features": ["格式转换", "编码解码", "文本处理", "加密哈希"],
  "is_free": true,
  "founded": "2024-01-15"
}

两者的关系和区别

YAML 和 JSON 有着密切的关系：JSON 是 YAML 1.2 规范的子集，也就是说，几乎所有合法的 JSON 都是合法的 YAML。这就是为什么 YAML 解析器通常可以直接解析 JSON 数据。

但反过来，YAML 的许多特性在 JSON 中并不存在，比如注释、锚点、多行字符串等。

为什么需要 YAML JSON 转换

在实际开发中，YAML 和 JSON 之间的转换是非常常见的需求。以下是几个典型的应用场景。

配置文件场景

YAML 因其良好的可读性，被广泛用作配置文件格式：

• Kubernetes：所有资源定义（Deployment、Service、ConfigMap 等）都使用 YAML
• Docker Compose：容器编排配置文件 docker-compose.yml
• Ansible：自动化运维的 Playbook 使用 YAML 编写
• GitHub Actions：CI/CD 工作流配置
• OpenAPI/Swagger：API 文档规范通常用 YAML 编写

而这些配置工具的内部实现，往往是先把 YAML 解析成 JSON 结构再进行处理。

API 数据交换

在 Web API 领域，JSON 是事实上的标准数据交换格式。当你需要：

• 把 YAML 配置的内容通过 API 发送给后端
• 将 API 返回的 JSON 数据保存为 YAML 配置文件
• 在支持 YAML 的工具和支持 JSON 的系统之间传递数据

这些场景都需要进行格式转换。

前后端协作

前端开发者通常更熟悉 JSON，而后端或运维工程师可能更习惯用 YAML 编写配置。在团队协作中，经常需要：

• 后端提供 JSON 格式的 API 响应，前端需要转为 YAML 做配置
• 运维用 YAML 写配置，开发需要转为 JSON 在代码中使用
• 技术文档中同时提供两种格式的示例

YAML vs JSON 对比

让我们通过一个详细的对比表，来全面了解这两种格式的差异。

语法对比表格

| 特性 | YAML | JSON | |------|------|------| | 语法风格 | 缩进表示层级 | 大括号和方括号 | | 注释 | 支持（#） | 不支持 | | 字符串引号 | 可选，大多数情况不需要 | 必须使用双引号 | | 键名引号 | 可选 | 必须使用双引号 | | 多行字符串 | 原生支持（|、>） | 需要用 \n 转义 | | 数据类型 | 丰富（日期、时间、空值等） | 有限（6 种基本类型） | | 锚点/别名 | 支持（&、*） | 不支持 | | 文件扩展名 | .yaml / .yml | .json | | 人类可读性 | 高 | 中等 | | 解析速度 | 相对较慢 | 快 | | 语言支持 | 需要第三方库 | 大多数语言原生支持 |

各自的优势和适用场景

YAML 的优势：

• 更适合人类阅读和编写
• 支持注释，便于文档化
• 多行字符串处理更自然
• 可以用锚点和别名减少重复
• 适合作为配置文件格式

JSON 的优势：

• 解析速度更快
• 几乎所有编程语言原生支持
• 语法严格，不容易产生歧义
• 适合作为 API 数据交换格式
• 工具生态更完善

一句话总结：配置文件用 YAML，数据交换用 JSON。

YAML 转 JSON 的方法

下面介绍几种常见的 YAML 转 JSON 方法，从最简单的在线工具到命令行和代码实现。

在线工具转换

最快捷的方式是使用在线转换工具，无需安装任何软件。

使用 DevToolkit Pro YAML JSON 转换工具：

1. 在左侧输入框粘贴 YAML 内容
2. 右侧自动实时显示转换后的 JSON
3. 点击复制按钮即可获取结果

这种方式适合临时转换、快速验证，以及不想安装工具的场景。

命令行工具

对于开发者来说，命令行工具效率更高，特别适合批量处理。

使用 yq

yq 是一个专门处理 YAML 的命令行工具，类似于处理 JSON 的 jq。

# 将 YAML 文件转为 JSON
yq eval -o=json input.yaml > output.json

# 或者使用简写
yq -o=json input.yaml

使用 Python

Python 标准库自带 JSON 模块，YAML 则需要安装 PyYAML：

# 安装 PyYAML
pip install pyyaml

# 单行命令转换
python -c "import yaml, json, sys; print(json.dumps(yaml.safe_load(sys.stdin), indent=2, ensure_ascii=False))" < input.yaml > output.json

编程语言实现

在项目代码中进行转换，是最灵活的方式。

JavaScript / Node.js

使用 js-yaml 库：

npm install js-yaml

const fs = require('fs');
const yaml = require('js-yaml');

const yamlContent = fs.readFileSync('input.yaml', 'utf8');
const data = yaml.load(yamlContent);
const jsonContent = JSON.stringify(data, null, 2);

console.log(jsonContent);

Python

import yaml
import json

with open('input.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

with open('output.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

提示：使用 yaml.safe_load() 而不是 yaml.load()，可以避免 YAML 反序列化安全问题。

JSON 转 YAML 的方法

JSON 转 YAML 同样有多种实现方式。

在线工具

使用在线工具是最快的方式之一。

DevToolkit Pro YAML JSON 转换工具 支持双向转换：

1. 点击中间的"切换方向"按钮，切换到 JSON → YAML 模式
2. 在左侧输入 JSON 内容
3. 右侧实时显示转换后的 YAML

命令行

使用 yq

# 将 JSON 文件转为 YAML
yq eval -P input.json > output.yaml

使用 Python

python -c "import yaml, json, sys; print(yaml.dump(json.load(sys.stdin), allow_unicode=True, default_flow_style=False))" < input.json > output.yaml

代码实现

JavaScript / Node.js

const fs = require('fs');
const yaml = require('js-yaml');

const jsonContent = fs.readFileSync('input.json', 'utf8');
const data = JSON.parse(jsonContent);
const yamlContent = yaml.dump(data, { indent: 2, lineWidth: -1 });

console.log(yamlContent);

Python

import json
import yaml

with open('input.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

with open('output.yaml', 'w', encoding='utf-8') as f:
    yaml.dump(data, f, allow_unicode=True, default_flow_style=False, sort_keys=False)

常见问题和陷阱

YAML 和 JSON 之间的转换看起来简单，但实际操作中经常会遇到各种问题。下面是一些最常见的陷阱。

缩进问题

YAML 对缩进非常敏感，这是新手最容易踩的坑：

• 必须使用空格缩进，不能用 Tab
• 同一层级的缩进必须对齐
• 通常使用 2 个或 4 个空格，但一个文件内要一致

# 正确
person:
  name: Alice
  age: 30

# 错误：缩进不一致
person:
  name: Alice
   age: 30  # 多了一个空格

解决方法：使用支持 YAML 的编辑器，开启显示空白字符功能；或者使用 DevToolkit Pro 的 YAML 格式化工具 自动修复格式。

数据类型丢失

YAML 的自动类型推断有时会带来意外：

# 看起来像数字的字符串
port: 08080  # YAML 会把 08080 解析为八进制数字，结果是 520！

# 看起来像布尔值的字符串
enabled: yes  # 会被解析为 true
flag: off     # 会被解析为 false

# 日期自动转换
date: 2024-01-15  # 会被解析为 Date 对象，转 JSON 变成字符串

解决方法：

• 对于需要保留为字符串的值，加上引号：port: "08080"
• 使用严格模式解析，或在转换后手动验证数据类型

循环引用

JSON 不支持循环引用，但 JavaScript 等语言中的对象可能存在循环引用：

const obj = { name: 'test' };
obj.self = obj;  // 循环引用
JSON.stringify(obj);  // 报错：TypeError: Converting circular structure to JSON

解决方法：

• 避免在需要序列化的数据中使用循环引用
• 使用专门的库处理循环引用（如 circular-json，但已废弃）

多行字符串处理

YAML 的多行字符串有多种语法，转换时需要注意：

# | 保留换行符
description: |
  第一行
  第二行

# > 折叠换行（变成空格）
summary: >
  这是一段
  很长的文字

转为 JSON 后分别是：

{
  "description": "第一行\n第二行\n",
  "summary": "这是一段 很长的文字\n"
}

注意：| 和 > 语法末尾的换行符处理方式不同，需要根据实际需求选择。

YAML 锚点和别名无法转 JSON

YAML 的锚点（&）和别名（*）是非常有用的特性，可以减少重复：

defaults: &defaults
  adapter: postgres
  host: localhost

development:
  <<: *defaults
  database: dev_db

production:
  <<: *defaults
  database: prod_db

但 JSON 没有对应的概念，转换后会变成展开的完整结构。虽然数据是正确的，但会失去"引用"的语义。

解决方法：如果需要保留引用关系，需要在业务代码中自己处理，或者选择其他支持引用的格式。

使用 DevToolkit Pro 在线 YAML JSON 转换工具

如果你需要快速、方便地进行 YAML 和 JSON 之间的转换，DevToolkit Pro 的在线 YAML JSON 转换工具 是一个绝佳选择。

双向转换

工具支持 YAML → JSON 和 JSON → YAML 双向转换，一键切换方向，满足各种转换需求。无论是把配置文件转为 API 可用的 JSON，还是把接口返回的数据保存为 YAML 配置，都能轻松搞定。

实时预览

输入内容的同时，右侧结果实时更新，无需点击转换按钮。你可以边写边看转换结果，快速验证格式是否正确。

格式校验

工具会自动检测语法错误，并给出清晰的错误提示，帮你快速定位问题。无论是 YAML 的缩进问题，还是 JSON 的语法错误，都能一目了然。

此外，工具还支持：

• 格式化美化：自动调整缩进和换行，让代码更易读
• 压缩/最小化：JSON 可以转为压缩格式，减少体积
• 一键复制：转换结果一键复制到剪贴板
• 纯前端运行：所有处理在浏览器本地完成，数据不上传服务器，保护隐私

最佳实践

1. 选择合适的格式

• 配置文件：优先用 YAML，可读性好，支持注释
• API 数据交换：用 JSON，兼容性好，解析速度快
• 存储大量数据：考虑更紧凑的格式（如 MessagePack、Protocol Buffers）

2. 保持风格一致

在同一个项目中，保持格式风格的一致性：

• YAML 缩进统一使用 2 空格或 4 空格
• JSON 的缩进空格数保持一致
• 命名风格统一（驼峰、下划线、连字符选一种）

3. 注意数据类型

• 字符串如果可能被误解为数字、布尔值或日期，务必加引号
• 浮点数精度问题要注意，尤其是金额相关的数据
• 空值统一使用 null（JSON）或 null / ~（YAML）

4. 转换后验证

转换完成后，不要直接使用，先做验证：

• 检查关键字段的值是否正确
• 验证数据类型有没有发生意外变化
• 确认没有丢失字段或数据

5. 安全地解析 YAML

• 永远使用 safe_load 而不是 load，避免反序列化攻击
• 不要解析来自不可信来源的 YAML 文件
• 对解析后的数据做合法性校验

FAQ

YAML 和 JSON 哪个更好？

没有绝对的"更好"，取决于使用场景。配置文件推荐用 YAML（可读性好、支持注释），API 数据交换推荐用 JSON（兼容性好、解析快）。

为什么 YAML 文件有时候会解析出错？

最常见的原因是缩进问题。YAML 对缩进非常敏感，必须使用空格（不能用 Tab），同一层级的缩进必须严格对齐。另外，特殊字符、未加引号的字符串也可能导致解析错误。

JSON 支持注释吗？

标准 JSON 不支持注释。但有些工具和库（如 JSON5、JSONC）扩展了 JSON 语法，支持注释。如果你需要带注释的配置文件，建议直接使用 YAML。

YAML 转 JSON 后数据类型变了怎么办？

这通常是因为 YAML 的自动类型推断导致的。解决方法是给字符串加上引号，明确告诉解析器这是字符串类型。例如 port: "8080" 而不是 port: 8080。

有没有批量转换的方法？

有。可以使用命令行工具（如 yq）配合 shell 脚本批量处理文件，或者用 Python/Node.js 写脚本遍历目录进行转换。对于简单的临时转换，也可以使用在线工具逐个处理。

本文由 DevToolkit Pro 提供。立即体验 在线 YAML JSON 转换工具，让数据格式转换变得简单高效。更多开发者工具请访问 首页。