Learn X in Y minutes 之 YAML 完整实战指南:标量、集合、锚点与标签全解析

原创2026-10-05 15:01:031,721 阅读
文章标签:文档教程

Learn X in Y minutes 之 YAML 完整实战指南:标量、集合、锚点与标签全解析

本篇指南以 learnxinyminutes-docs 仓库中的 de/yaml.md(德语版)及其英文原版 yaml.md 为蓝本,系统讲解 YAML 这门"面向人类书写与阅读"的数据序列化语言。你将通过一组可直接运行的 YAML 示例,掌握标量类型、多行文本块、集合嵌套、锚点/别名、显式标签与日期二进制等高级类型;同时结合本仓库的 lint/frontmatter.py 与 CI 工作流,看到 YAML 在本项目中被真实用于"文档元数据(front matter)"的工程实践。读完本文,你能独立读懂并编写任何 YAML 配置文件,并理解其解析原理与常见陷阱。

文档在仓库中的定位与阅读前提

learnxinyminutes-docs 是一个"以代码形式书写文档"的速成教程仓库,每个教程文件都以"可运行的注释代码 + 逐行讲解"的形式存在,并配有 contributors(贡献者)与 translators(译者)元数据。de/yaml.md 是该系列 YAML 教程的德语版本,其开头的 YAML front matter 本身就是一段真实的 YAML 文档:

---
contributors:
  - ["Leigh Brenecki", "https://github.com/adambrenecki"]
translators:
  - ["Ruben M.", "https://github.com/switchhax"]
---

这正是"学 YAML 最好的教材就是仓库自身"的绝佳例证:仓库的每个 .md 文件头部都有一段 YAML 元数据,并由 lint/frontmatter.py 统一校验(下文第五节详述)。因此,阅读本指南前你无需任何前置知识,但读完后不妨回到仓库,亲手用 yaml.safe_load 解析几个文件的 front matter 做验证。

YAML 是什么:面向人类的序列化语言

YAML(YAML Ain't Markup Language)是一种数据序列化语言,其设计目标是人可以直接手写、直接阅读。它有两个核心设计决策:

  1. 是 JSON 的严格超集:任何合法的 JSON 文档都是合法的 YAML,因此 JSON 风格的 {} 与 [] 写法在 YAML 中同样有效;
  2. 缩进具有语法意义:换行与缩进参与语法解析,这一点类似 Python——但与 Python 不同,YAML 禁止使用制表符(Tab)进行缩进,必须使用空格。

这两点贯穿全文所有示例。下面的代码块将按"标量类型 → 集合类型 → 扩展特性 → 扩展类型"的顺序,把整个文档展开讲解。

标量类型:从键值对到引号规则

YAML 文档的根对象通常是一个映射(Map),等价于其他语言中的字典(Dictionary)、哈希(Hash)或对象(Object)。最基本的标量写法如下:

# YAML 中的注释以 # 开头。
# 根对象将是一个 Map,等价于其他语言中的哈希或对象。
Schlüssel: Wert            # 键: 值
nochn_Schlüssel: Hier kommt noch ein Wert hin.
eine_Zahl: 100             # 整数
wissenschaftliche_Notation: 1e+12   # 科学计数法
boolean: true              # 布尔值
null_Wert: null            # 空值
Schlüssel mit Leerzeichen: value    # 键名可以包含空格

要点归纳:

  • 键值对用 键: 值 形式,冒号后必须跟一个空格;
  • 数值支持整数、小数、科学计数法(1e+12)等多种写法;
  • 布尔与空值分别写作 true / false 和 null;
  • 键名可以包含空格,无需引号。

字符串在大多数情况下不需要引号,但也可以加上:

jedoch: "Ein String in Anführungszeichen"        # 双引号字符串
"Ein Schlüssel in Anführungszeichen": "Nützlich, wenn du einen Doppelpunkt im Schlüssel haben willst."

第二个例子展示了引号键名的实际用途:当键名本身包含冒号时,必须用引号包裹,否则解析器会把冒号误认为键值分隔符。英文原版 yaml.md 还补充了几个易混淆点,一并列出:

  • 数字 1 会被解析为数值而非布尔值;若想表达布尔,请显式写 true;
  • yes / no / on / off(不区分大小写)在多数解析器里会被解析为布尔值,想保留字面字符串必须加引号;
  • 单引号字符串中可以用 '' 转义单个引号,双引号字符串支持 \"、\t、\u263A、\x0d\x0a 等转义;
  • 含 [、]、&、{、}、-、<、> 等特殊字符的字符串应加引号。

多行字符串:literal block 与 folded block

多行文本在 YAML 中有两种规范写法,均以指示符开头:

  • literal block(字面块):| 后跟文本,保留每一处换行;
  • folded block(折叠块):> 后跟文本,块内换行被替换为单个空格。
literal_block: |
    Dieser ganze Block an Text ist der Wert vom Schlüssel literal_block,
    mit Erhaltung der Zeilenumbrüche.

    Das Literal fährt solange fort bis dieses unverbeult ist und die vorherrschende Einrückung wird
    gekürzt.

        Zeilen, die weiter eingerückt sind, behalten den Rest ihrer Einrückung -
        diese Zeilen sind mit 4 Leerzeichen eingerückt.
folded_style: >
    Dieser ganze Block an Text ist der Wert vom Schlüssel folded_style, aber diesmal
    werden alle Zeilenumbrüche durch ein Leerzeichen ersetzt.

    Freie Zeilen, wie obendrüber, werden in einen Zeilenumbruch verwandelt.

        Weiter eingerückte Zeilen behalten ihre Zeilenumbrüche -
        diese Textpassage wird auf zwei Zeilen sichtbar sein.

两个块的关键语义:

  1. 块持续到缩进回退(de-dent)为止,即块内文本必须比键名多缩进,而公共前导缩进会被剥离;
  2. 比公共缩进更深的行保留其多余缩进——示例中"4 个空格缩进"的行会原样保留这 4 个空格;
  3. 折叠块中,空行不会被折叠成空格,而是转换为换行符;更深缩进的行则保留其换行。

英文原版还补充了块指示符的三种后缀,用于控制末尾空行:

  • |- / >-:剥离(strip) 末尾空行;
  • |+ / >+:保留(keep) 末尾空行;
  • 无后缀(| / >):默认 clip 行为,即保留单个末尾换行。

集合类型:嵌套、复杂键与序列

通过缩进实现嵌套

YAML 的嵌套完全由缩进表达,推荐使用 2 空格缩进(但并非强制,需保持一致):

eine_verschachtelte_map:
    schlüssel: wert
    nochn_Schlüssel: Noch ein Wert.
    noch_eine_verschachtelte_map:
        hallo: hallo

键不一定非是字符串

0.25: ein Float-Wert als Schlüssel   # 浮点数作为键

复杂键:? 与 :

键也可以是复杂的多行对象。? (问号加空格)标记复杂键的开始,: 后跟该键对应的值:

? |
    Dies ist ein Schlüssel,
    der mehrzeilig ist.
: und dies ist sein Wert

更进一步,YAML 允许用序列(Sequence)作为键——例如英文原版中的示例,把球队序列映射到日期序列:

? - Manchester United
  - Real Madrid
: [ 2001-01-01, 2002-02-02 ]

这种"集合作为键"的写法许多语言解析器会报错,属于进阶技巧,使用时需谨慎。

序列(Sequence):等价于列表或数组

序列用 - 标记每个元素(注意 - 本身计入缩进层级):

eine_Folge:
    - Artikel 1
    - Artikel 2
    - 0.5                 # 序列可以包含不同类型的元素
    - Artikel 4
    - schlüssel: wert     # 元素也可以是内联 Map
      nochn_schlüssel: nochn_wert
    -
        - Dies ist eine Folge   # 嵌套序列:序列中的序列
        - innerhalb einer Folge

要点:

  • 序列元素可以是标量、Map 或嵌套序列,类型可以混用;
  • - key: value 这种写法表示"序列元素本身是一个单键 Map",其后续行需要与 key 对齐缩进;
  • 多层嵌套的 - - - 写法可以展开书写,也可折叠为多级缩进。

JSON 兼容写法

由于 YAML 是 JSON 的超集,可以直接内联 JSON 风格的映射与序列:

json_map: {"schlüssel": "wert"}
json_seq: [3, 2, 1, "Start"]

甚至键不引号、值不引号也可以混合使用:{ key: [ 3, 2, 1, takeoff ] }。这为"在 YAML 中混用 JSON 风格"提供了便利,也意味着你可以把现有 JSON 配置直接粘贴进 YAML 文件。

锚点、别名与合并:文档内复用内容

YAML 提供了**锚点(Anchor)与别名(Alias)**机制,用于在文档内复用内容:

  • 锚点以 & 开头,定义被复用的值;
  • 别名以 * 开头,相当于"引用上面定义过的锚点"。
verankerter_inhalt: &anker_name Dieser String wird als Wert beider Schlüssel erscheinen.
anderer_anker: *anker_name

上述两个键最终解析为完全相同的值。锚点最常见的实战用途是"继承/复制一组属性",配合合并键 <<(Merge Key)使用:

base: &base
  name: Everyone has same name

foo:
  <<: *base        # 注意:如果当前 Map 已存在同名键,则不会被锚点覆盖
  age: 10
  name: John       # foo.name 保持 "John"

bar:
  <<: *base        # bar 没有自己的 name,合并后 name = "Everyone has same name"
  age: 20

<<: *base 表示"把 base 锚点中的所有键插入当前 Map"。同名键以当前 Map 中显式定义的值为准——foo 中已有 name: John,因此合并不会覆盖它;而 bar 没有定义 name,合并后得到锚点中的值。这一机制在 CI 配置、应用默认配置中广泛用于"默认值 + 局部覆盖"。

标签(Tags):显式声明类型

YAML 支持用 !!类型名 语法显式声明标量的类型,格式为 !![typeName] [value]:

explicit_string: !!str 0.5          # 强制把 "0.5" 当作字符串而非浮点数
explicit_boolean: !!bool true       # 显式布尔
explicit_integer: !!int 42          # 显式整数
explicit_float: !!float -42.24      # 显式浮点
explicit_datetime: !!timestamp 2022-11-17 12:34:56.78 +9
explicit_null: !!null null

核心价值在于消除歧义:例如 0.5 默认会被解析为浮点数,但加上 !!str 后即强制为字符串。

此外,部分解析器实现了语言特定标签。仓库文档中给出的例子是 Python 复数类型:

python_komplexe_Zahlen: !!python/complex 1+2j

以及用语言特定标签构造复杂键:

? !!python/tuple [ 5, 7 ]
: Fifty Seven
# 在 Python 中解析为 {(5, 7): 'Fifty Seven'}

注意:语言特定标签依赖具体解析器实现,跨语言迁移配置时应避免使用。

扩展类型:日期时间、二进制与集合

ISO 格式日期与时间

字符串和数字并非 YAML 唯一认识的标量。符合 ISO 格式的日期与时间字面量会被自动解析为日期/时间对象:

DatumZeit: 2001-12-15T02:59:43.1Z                      # ISO 8601 规范格式
DatumZeit_mit_Leerzeichen: 2001-12-14 21:59:43.10 -5   # 空格分隔 + 时区偏移
Datum: 2002-12-14                                       # 纯日期

二进制数据:!!binary

!!binary 标签表示"该字符串实际是 base64 编码的二进制数据块",常与 literal block 配合存放图片等二进制内容。文档中的例子是一个 base64 编码的 GIF 文件:

gif_datei: !!binary |
    R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
    OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+
    +f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC
    AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs=

解析器会将其解码为原始二进制字节,适合在配置中内嵌小型证书、图标等资源。

集合(Set)类型

YAML 还提供**集合(Set)**类型,语法与"复杂键"一致——每个元素以 ? 开头:

menge:
    ? artikel1
    ? artikel2
    ? artikel3

其等价写法 { item1, item2, item3 } 同样合法。理解原理很重要:Set 本质就是"值为 null 的 Map",因此上面的例子完全等价于:

menge:
    artikel1: null
    artikel2: null
    artikel3: null

这一等价关系可以帮你理解为何许多 YAML 解析器把 Set 实现为"键集合"。

仓库中的 YAML 实战:front matter 校验与 CI

YAML 语法在本仓库并非纸上谈兵——每个 .md 教程文件头部的 front matter 都是一段真实 YAML,并经过三层工程化校验,这为你的学习提供了可验证的参照物:

  1. 语法与键校验:lint/frontmatter.py 先以正则 ^(---\s*\n.*?\n)---\n 提取每个 .md 文件的 front matter,再用 yaml.safe_load 解析、以 yamllint 做风格检查(该脚本对缩进、行长、尾随空格等规则做了放宽,见文件内 yaml_config),最后校验只允许 name、where_x_eq_name、category、filename、contributors、translators 这六个键,并对 contributors/translators 的"贡献者列表"结构做了逐项类型检查。这正是 de/yaml.md 头部那段 front matter 能通过 CI 的原因。
  2. 编码与空白校验:.github/workflows/lint.yml 中的 CI 任务会运行 lint/encoding.sh 确保所有 .md 文件为 UTF-8/US-ASCII 且无 BOM,同时禁止非断行空格、零宽空格与回车符——这些约束同样适用于 YAML 教程文件内的文本。
  3. 站点触发:.github/workflows/build.yml 在 main/master 分支推送时触发 repository-dispatch,通知文档站点重建。也就是说,仓库中的每一份 YAML 教程最终都会被渲染为 Learn X in Y minutes 网站上的一个页面。

如果你想把 YAML 官方文档中的 ---(文档开始)与 ...(文档结束)标记也纳入理解,英文原版 yaml.md 给出了完整示例——这两个标记用于在单个文件中分隔/结束多个 YAML 文档,是 YAML 多文档流(multi-document stream)的基础语法。

小结:一份可复制的 YAML 心智模型

回顾全篇,YAML 的核心心智模型可概括为三条:

  • 缩进即结构:Map 靠缩进嵌套,序列靠 - 标记,Tab 永远禁用;
  • 字面量有默认类型推断:数字、布尔、null、ISO 日期会被自动识别,需要字面字符串时加引号,需要强制类型时用 !!tag;
  • 文档内复用靠锚点/别名:& 定义、* 引用、<< 合并,适合做默认值与覆盖。

本文所有示例均可在本仓库 de/yaml.md 与 yaml.md 中直接查阅;如需动手验证解析结果,可用 Python 的 PyYAML(本仓库 lint/frontmatter.py 即依赖它)对文中的示例代码块执行 yaml.safe_load,逐条对照你预期的数据结构。

登录后查看全文
learnxinyminutes-docs