FlowingDev

YAML 详解：缩进如何成为一种超能力

YAML 是一种人类可读的数据格式，它使用简单的缩进方式来组织数据结构，因此在配置文件和数据交换领域备受欢迎。

试用工具: YAML 查看器

一句话概括

YAML 是一种人类可读的数据序列化语言，它使用缩进和极简的标点符号来表示数据结构，这让它成了那些需要由人来读写的配置文件的宠儿。

它解决了什么问题

起初，世界一片混沌。或者更准确地说，是 XML 这样的格式。如果你想存储结构化数据——比如说，一个用户的设置——你就得把它包裹在一片尖括号的森林里。它功能强大，机器可读，但对人类来说，编辑它而不犯错简直就是一场噩梦。

<user>
  <name>Alex</name>
  <roles>
    <role>editor</role>
    <role>admin</role>
  </roles>
  <active>true</active>
</user>

然后，JSON (JavaScript Object Notation) 来了。它就像一股清流！受 JavaScript 对象语法的启发，它抛弃了尖括号，改用花括号、方括号和冒号。它更轻量、更清晰，并迅速成为各地 API 的事实标准。

{
  "name": "Alex",
  "roles": [
    "editor",
    "admin"
  ],
  "active": true
}

但即便是 JSON，当人类亲自操刀时，也有它的怪癖。那一堆逗号、引号和括号都是语法上的绊脚石。忘了一个逗号？整个文件就都无效了。想加个注释来解释为什么某个设置是这样的？想都别想，JSON 不支持注释。

这正是 YAML 在 21 世纪初应运而生的生态位。它的名字，一个递归缩写，说明了一切：YAML Ain't Markup Language（YAML 不是一种标记语言）。它专注于成为一种数据格式，而不是文档标记系统。创造者的主要目标是优化人类的可读性和可写性。他们看着 Python 那干净、缩进的结构，心想：“我们能不能把这个用到数据上？” 结果就是，这种格式看起来不像代码，更像一份组织良好的大纲。

底层工作原理

YAML 的魔法在于其简洁性以及它与 JSON 的关系。其核心是，一个 YAML 解析器读取一个文本文件，然后在内存中构建一个抽象的数据结构——这个过程与 JSON 解析器的工作方式并无二致。这就是为什么在 YAML 和 JSON 之间转换如此无缝；它们代表的是相同的基本概念，只是穿的衣服不同。

缩进游戏

这是 YAML 的标志性特征。JSON 用 {} 和 [] 来表示嵌套，而 YAML 用空格。规则很简单：如果一行的缩进比上一行多，那么它就是上一行的子级。

  • 规则 #1： 用空格，别用制表符（Tab）。全世界的开发者已经就这一点达成了共识，以避免对齐混乱。
  • 规则 #2： 保持一致。如果你第一级缩进用了 2 个空格，那么所有第一级缩进都用 2 个空格。

看看这区别。结构是相同的，但 YAML 版本感觉就像一套干净的笔记。

JSON:

{
  "server": {
    "port": 8080,
    "security": {
      "enable_https": true
    }
  }
}

YAML:

server:
  port: 8080
  security:
    enable_https: true

基本构件：标量、序列和映射

YAML 数据由三种基本元素构成：

  • 映射 (Mappings / Objects / Dictionaries): 即键值对。在 YAML 中，写作 key: value。冒号后面的空格是必须的！
    # 一个简单的映射
name: "Alex"
email: alex@example.com
  • 序列 (Sequences / Lists / Arrays): 即有序的项目列表。每个项目都以一个连字符和一个空格 (- ) 开头。
    # 一个简单的角色序列
- editor
- admin
- contributor
  • 标量 (Scalars / Values): 这就是实际的数据：字符串、数字、布尔值。YAML 最友好的特性之一是，你通常不需要给字符串加引号。name: Alex 就完全没问题。只有当你的字符串包含特殊字符，或者可能被误解为其他类型（比如 true 或 5.0）时，才需要加引号。

将这些组合起来，你就能表示几乎任何数据结构。

# 一个用户对象列表
- name: Alex
  email: alex@example.com
  roles:
    - editor
    - admin
- name: Bailey
  email: bailey@example.com
  roles:
    - contributor

高级魔法：锚点、别名和标签

YAML 有一些 JSON 所没有的绝招，主要是为了让你的文件保持 DRY (Don't Repeat Yourself，不要重复自己)。

  • 锚点 (&) 和别名 (*): 锚点让你能给一块数据命名。别名则让你能在别处引用这块数据。对于那些有重复块的复杂配置来说，这简直是天赐之物。

    # 用锚点定义一组默认配置
default_db_config: &db_defaults
  adapter: postgres
  pool: 5
  timeout: 5000

# 在不同环境中使用别名来复用默认配置
development:
  <<: *db_defaults # << 会将别名合并进来
  database: myapp_dev

production:
  <<: *db_defaults
  database: myapp_prod

    在这里，&db_defaults 创建了一个可复用的模板。*db_defaults 则把它复制了进来。如果你需要为所有环境更改 timeout，你只需在一个地方修改即可。

  • 标签 (!): 标签是一种明确告诉解析器某数据是什么类型的方式。你很少会自己写它们，但它们是规范的一部分。!!str "123" 会强制解析器将 "123" 视为字符串，而不是数字。

真实世界的故事

不堪重负的 DevOps 工程师

一个团队正在用 Kubernetes 管理他们的应用基础设施。每个服务、部署和配置映射都是一个独立的 .json 文件。随着系统的增长，“括号失明症”也越来越严重。Pull Request 里的 diff 简直就是一场括号不匹配和尾逗号修改的噩梦。终于，一位工程师忍无可忍，主导了一次向 YAML 的迁移。突然之间，deployment.yaml 文件变得一目了然。可以添加注释来解释为什么某个服务有特定的内存限制。查找环境变量里的一个拼写错误，从语法解谜变成了视觉扫描。

经验： 对于需要人类频繁阅读和修改的复杂、分层的配置，YAML 的可读性极大地提升了生活质量。

静态网站生成器的布道者

一个内容团队正在使用静态网站生成器（如 Hugo 或 Jekyll）来管理公司博客。每篇文章都以 "frontmatter" 开头，这是一块包含标题、作者、日期和标签的元数据。最初的设置使用 JSON frontmatter。那些非技术背景的作者们经常被漏掉的逗号或不正确的转义引号搞得晕头转向。一位开发者将 frontmatter 格式切换到了 YAML。语法是如此直观 (title: My Post, author: Dale)，以至于作者们的求助工单降到了零。他们现在可以专注于写作，而不是语法。

经验： YAML 的低语法噪音使其成为非开发者与结构化数据交互的绝佳“接口”。

国家代码的“坑”

一位开发者正在构建一个处理国际订单的系统，并将两位字母的国家代码存储在一个 YAML 配置文件中。对于 US、DE 和 JP，一切正常。但当一笔来自挪威的订单进来时，系统崩溃了。经过数小时的调试，他们找到了罪魁祸首。YAML 文件里写的是 country: NO。YAML 解析器自作聪明地将 NO 解释为布尔值 false，而不是字符串 "NO"。修复很简单，但过程很 frustrating：country: "NO"。

经验： YAML 的自动类型推断很方便，但也可能导致意想不到的 bug。当你不确定时，或者当处理的数据看起来像布尔值或数字时，给你的字符串加上引号。

常见错误和陷阱

  • 制表符 vs. 空格。 这是 YAML 的原罪。你必须使用空格进行缩进。大多数编辑器都可以配置为自动将制表符转换为空格，这将把你从这种特殊的头痛中解救出来。
  • 挪威问题。 如上所述，未加引号的字符串如 NO、YES、ON、OFF，甚至一些数字，都可能被自动转换为布尔值或数字类型。经验法则是：如果一个字符串可能被解释为其他任何东西，就给它加上引号。
  • 忘记冒号后面的空格。 写成 key:value 会导致解析错误。冒号后面必须有一个空格：key: value。这个小细节至少会让每个人都栽一次跟头。
  • 缩进不一致。 在一个嵌套层级用两个空格，在另一个层级用四个，会让解析器感到困惑。选择一个缩进宽度（2 个空格是最常见的约定）并坚持使用。
  • 多行字符串的困惑。 YAML 有特殊字符（| 和 >）来处理多行字符串。| 保留换行符（非常适合代码片段），而 > 会将它们折叠成单行（非常适合长段落）。用错了可能会弄乱你的文本。

为什么你应该关注它

如果你在现代软件开发领域工作，尤其是在 DevOps 和基础设施领域，你根本无法避开 YAML。

  • 配置为王： 像 Docker Compose、Kubernetes、Ansible 以及几乎所有的 CI/CD 平台（GitHub Actions、GitLab CI）都使用 YAML 作为其主要的配置语言。了解它不是可选项，而是一项核心能力。
  • 以人为本的数据： 每当你创建一个需要人类直接编写或编辑结构化数据的系统时——从应用程序设置到博客文章元数据——YAML 都应该是首选。
  • JSON 的超集： 因为 YAML（大部分情况下）是 JSON 的一个超集，所以你有一条清晰的迁移路径和极好的互操作性。你可以拿一个棘手的 JSON 文件，把它转换成 YAML 使其更具可读性，添加注释，然后如果另一个系统需要纯 JSON，再把它转换回去。

你可以把 YAML 想象成一位友善、有条理的图书管理员，而 JSON 则像是一股原始、高效的数据流。你的工具箱里需要同时拥有这两者。

深入了解

理论搞定，动手试试吧——100% 在你的浏览器中运行。

试用工具: YAML 查看器