Learn X in Y minutes 之 YAML 完整实战指南:标量、集合、锚点与标签全解析
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)是一种数据序列化语言,其设计目标是人可以直接手写、直接阅读。它有两个核心设计决策:
- 是 JSON 的严格超集:任何合法的 JSON 文档都是合法的 YAML,因此 JSON 风格的
{}与[]写法在 YAML 中同样有效; - 缩进具有语法意义:换行与缩进参与语法解析,这一点类似 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.
两个块的关键语义:
- 块持续到缩进回退(de-dent)为止,即块内文本必须比键名多缩进,而公共前导缩进会被剥离;
- 比公共缩进更深的行保留其多余缩进——示例中"4 个空格缩进"的行会原样保留这 4 个空格;
- 折叠块中,空行不会被折叠成空格,而是转换为换行符;更深缩进的行则保留其换行。
英文原版还补充了块指示符的三种后缀,用于控制末尾空行:
|-/>-:剥离(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,并经过三层工程化校验,这为你的学习提供了可验证的参照物:
- 语法与键校验: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 的原因。 - 编码与空白校验:.github/workflows/lint.yml 中的 CI 任务会运行 lint/encoding.sh 确保所有
.md文件为 UTF-8/US-ASCII 且无 BOM,同时禁止非断行空格、零宽空格与回车符——这些约束同样适用于 YAML 教程文件内的文本。 - 站点触发:.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,逐条对照你预期的数据结构。