JSON、YAML、CSV 和 TOML：什么时候该用哪种数据格式

说实话，写代码这么多年，我越来越觉得我们程序员大部分时间其实不是在写业务逻辑，而是在跟各种数据格式打交道——API 返回的是 JSON，配置文件是 YAML 或 TOML，报表导出是 CSV，Excel 里是表格行。这些格式看着都挺像的，但你要是用错了地方，真的会给自己挖坑。

我最早踩过的一个坑就是：把 YAML 当 JSON 用，结果被缩进搞到崩溃。后来慢慢摸清楚了每种格式的脾气，才明白它们压根就不是为了互相替代而设计的。这篇笔记我就把这些经验掰开揉碎讲清楚，希望对你有帮助。

JSON：API 界的通用语言

JSON（JavaScript Object Notation）现在是系统间数据交换的事实标准，尤其是 Web API。它用 {} 和 [] 来表示嵌套对象和数组，结构清晰，几乎所有编程语言都有现成的解析库。

为什么 JSON 在机器之间通信这么强？

它的规则非常严格，严格到有点“死板”：

• 字符串必须用双引号，不能用单引号
• 不能有注释（对，注释是不允许的）
• 最后一个键值对后面不能有逗号，多一个逗号整个文件就废了

这种严格性其实对机器来说是好事——没有歧义。比如：

{
  "name": "Alice",
  "age": 30,
  "address": {
    "city": "Beijing",
    "zip": "100000"
  },
  "hobbies": ["reading", "coding"]
}

这段 JSON 无论用 Python 的 json.loads() 还是 JavaScript 的 JSON.parse() 解析，结果完全一致。你不用担心“这个 true 是不是字符串”之类的问题。

但 JSON 对人不友好

我试过手写一个几百行的 JSON 配置文件，结果因为少了个逗号或者多逗号，来回检查了十分钟。更痛苦的是没法写注释——你永远不知道某个字段是干嘛的，除非有外部文档。

所以我的经验是：JSON 最适合机器对机器，比如 API 请求/响应、数据库导出、缓存序列化。但如果是人类要手动编辑的文件，别用 JSON，除非你想折磨自己和同事。

YAML：人类友好但暗藏杀机的配置格式

YAML 的设计初衷就是“人类可读写”。它用缩进代替花括号，支持注释，去掉了大部分 JSON 里那些烦人的标点符号。看起来清爽多了：

# 这是用户配置
name: Alice
age: 30
address:
  city: Beijing
  zip: "100000"  # 注意这里用引号，防止类型转换
hobbies:
  - reading
  - coding

为什么 CI/CD 和容器编排都爱 YAML？

因为 DevOps 工程师经常要手动改配置，YAML 的简洁性让它在这些场景里特别受欢迎。比如 GitHub Actions、GitLab CI、Docker Compose、Kubernetes 的 YAML 文件，全是 YAML 的天下。

YAML 的三大坑

但 YAML 的“简洁”也是它的致命弱点。我踩过至少三次这种坑：

1. 缩进问题
YAML 用缩进来表示层级，一个空格不对，整个文件的意思就变了。比如：

# 正确：address 是 name 的同级
name: Alice
address:
  city: Beijing

# 错误：address 变成了 name 的子级（多了一个空格）
name: Alice
 address:
   city: Beijing

这种错误在编辑器里可能看不出来，但解析时直接报错或者静默地改变了数据结构。

2. 类型强制转换的坑
YAML 有个非常著名的坑：no 会被解析成布尔值 false。比如：

# 你可能想表达“不允许”
allow_no: no

解析后 allow_no 的值是 False，而不是字符串 "no"。同样的问题还有 yes → true，on → true，off → false。要避免这个，必须显式加引号：

allow_no: "no"

3. 大文件的可读性
YAML 在文件小的时候很清爽，但一旦超过几百行，缩进嵌套多了，你根本分不清哪一层是哪一层。我曾经维护过一个 500 行的 Kubernetes 部署 YAML，每次改都心惊胆战。

我的建议

YAML 适合人类编辑的配置文件，但一定要加校验。比如用 yamllint 检查语法，或者在 CI 里跑一次解析测试。别相信自己的眼睛，也别相信同事的缩进习惯。

TOML：既友好又明确的配置格式

TOML（Tom's Obvious Minimal Language）是 YAML 的“改良版”。它用 INI 风格的分节和键值对，支持注释，类型系统明确，而且不太容易因为缩进出问题。

TOML 长什么样？

# 服务器配置
[server]
host = "0.0.0.0"
port = 8080

[database]
name = "myapp"
user = "admin"
password = "secret"

你看，它用 [section] 来表示层级，用 = 来赋值，非常直观。而且缩进只影响可读性，不影响结构——这是和 YAML 最大的区别。

TOML 的优势

• 类型明确：数字就是数字，字符串就是字符串，没有 YAML 那种 no 变 false 的诡异行为。
• 注释支持：用 # 写注释，想写多少写多少。
• 结构简单：适合扁平到中等嵌套的配置。比如 Python 的 pyproject.toml、Rust 的 Cargo.toml 都用了它。

TOML 的不足

如果数据嵌套太深，TOML 会变得很啰嗦。比如：

[user.address]
city = "Beijing"
zip = "100000"

[user.contact.email]
primary = "alice@example.com"
secondary = "alice.backup@example.com"

相比之下，JSON 或 YAML 可以用一行嵌套搞定。所以 TOML 最适合配置文件中层级不超过两三层的场景。

我什么时候用 TOML？

当我想让配置文件“既人类可读，又没有歧义”的时候。比如自己写的 CLI 工具的配置，或者团队里需要多人维护的配置文件，TOML 比 YAML 安全得多。

CSV：最原始但最通用的表格格式

CSV（逗号分隔值）是这四个里最简单的，也是最“笨”的。它只做一件事：把表格数据存成文本。

CSV 的典型用法

name,age,city
Alice,30,Beijing
Bob,25,Shanghai

这种格式几乎所有软件都支持：Excel 可以直接打开，数据库可以导入，数据分析工具（Pandas、R）都有现成的解析器。

CSV 的硬伤

没有嵌套概念。你不能在 CSV 里表示一个“用户对象里有地址对象”这种结构。如果你非要把嵌套数据塞进 CSV，就得“拍平”它——把嵌套的键用点号连起来变成列名：

user.name,user.address.city,user.address.zip
Alice,Beijing,100000

这样做虽然可行，但数据表会变得很宽，而且失去了原本的结构信息。

现实世界的 CSV 很脏：

• 值里包含逗号怎么办？比如 "Beijing, China" 必须用引号包起来。
• 值里包含换行符怎么办？有些 CSV 解析器会直接崩溃。
• 不同工具的换行符不一致（Windows 用 \r\n，Unix 用 \n），跨平台时容易出问题。

我的建议

CSV 只适合两件事：

1. 给 Excel 或 Google Sheets 用的表格数据
2. 简单的数据导入/导出

别试图把层级数据塞进 CSV，也别用 CSV 做配置。如果你需要表格格式但又要处理复杂数据，考虑用 Parquet 或 Avro。

格式之间的转换

实际工作中经常需要在不同格式之间来回倒腾。大多数情况下转换是直接的，但有一个关键点要注意：结构不匹配。

JSON ↔ YAML ↔ TOML

这三种格式都支持嵌套，所以互相转换通常很干净。比如 JSON 转 YAML：

{
  "user": {
    "name": "Alice",
    "address": {
      "city": "Beijing"
    }
  }
}

转成 YAML 就是：

user:
  name: Alice
  address:
    city: Beijing

基本上是一一对应的，不用担心丢数据。

JSON ↔ CSV 的坑

这是最容易踩坑的地方。因为 CSV 是扁平的，所以转换嵌套 JSON 时必须“拍平”：

{
  "user": {
    "name": "Alice",
    "address": {
      "city": "Beijing"
    }
  }
}

拍平后变成 CSV：

user.name,user.address.city
Alice,Beijing

反过来，从 CSV 转成 JSON 会得到一个扁平的对象数组：

[
  {
    "user.name": "Alice",
    "user.address.city": "Beijing"
  }
]

注意这里的键名变成了点号分隔的字符串，不是嵌套对象。如果你想要嵌套结构，还得自己写逻辑把键名拆开。

转换工具的选择

市面上有很多转换工具，但我推荐用客户端工具，尤其是处理敏感数据时。我写了一个小工具叫 boxtool.io/data-converter，支持 JSON、YAML、CSV、TOML 之间的双向转换，所有操作都在浏览器本地完成，数据不会上传到服务器。

为什么要强调“本地”？因为有时候你要转换的是客户数据、内部报表或者任何你不想上传到第三方服务器的内容。用客户端工具，你的数据永远只在你自己的机器上。

快速决策指南

根据我多年的踩坑经验，总结了一个简单的规则：

场景	推荐格式	原因
API 响应/数据交换	JSON	机器友好，解析一致
CI/CD 配置（如 GitHub Actions）	YAML	人类可读，生态成熟
需要明确类型的配置	TOML	无歧义，安全
表格数据/Excel 导出	CSV	通用性最强
手写配置文件（团队维护）	TOML > YAML > JSON	TOML 最安全，YAML 次之
深度嵌套的数据存储	JSON 或 YAML	两者都支持嵌套

最后再啰嗦一句：别把格式当信仰。JSON 再好，也别用它写配置文件；YAML 再方便，也要记得校验；CSV 再简单，也别往里塞树状数据。选对工具，省下的时间够你喝好几杯咖啡的。