YAML 1.1和1.2的语法细节

原创于 2025-08-30 10:15:00 发布 · 779 阅读

15 ·

CC 4.0 BY-SA版权

文章标签：

#开发语言

作者：浪浪山齐天大圣
描述：分别详细探讨YAML 1.1和1.2的语法细节，并深入分析它们之间的异同。

1. YAML 1.1语法详解

YAML 1.1作为YAML的早期主流版本，其语法奠定了YAML简洁、可读性强的基础。理解YAML 1.1的语法是掌握YAML的关键一步。本节将详细介绍YAML 1.1的核心语法元素。

1.1 基本结构与缩进

YAML使用缩进来表示数据层级，通常建议使用2个或4个空格作为缩进单位，但不能使用Tab键。冒号（:）用于表示键值对，连字符（-）用于表示列表项。

# 这是一个YAML示例
key: value

parent_key:
  child_key: child_value
  list_example:
    - item1
    - item2

1.2 数据类型

YAML 1.1支持多种数据类型，但其类型推断相对宽松。主要包括：

字符串 (Strings)：最常见的数据类型。可以不加引号，也可以使用单引号或双引号。双引号允许使用转义字符，单引号则不进行转义。
```
string1: Hello YAML
string2: 'Hello, World!'
string3: "Hello, \"YAML\"!"
```
数字 (Numbers)：整数和浮点数。
```
integer: 123
float: 3.14
negative: -10
```
布尔值 (Booleans)：true, false, on, off, yes, no 等，大小写不敏感。
```
is_active: true
is_enabled: No
```
空值 (Null)：null 或 ~。
```
empty_value: null
another_empty: ~
```
日期和时间 (Dates & Times)：通常解析为ISO 8601格式的日期或时间对象。
```
date: 2023-10-26
datetime: 2023-10-26T10:30:00Z
```

1.3 集合类型

YAML 1.1主要支持两种集合类型：映射（Maps/Dictionaries/Objects）和序列（Sequences/Lists/Arrays）。

映射 (Maps)：键值对的无序集合。键必须是唯一的。
```
person:
  name: Alice
  age: 30
  city: New York
```
序列 (Sequences)：值的有序集合。每个值前使用一个连字符和空格。
```
fruits:
  - Apple
  - Banana
  - Orange
```
块样式与流样式：
- 块样式 (Block Style)：使用缩进和换行来表示结构，可读性强，是YAML的默认风格。
- 流样式 (Flow Style)：使用JSON类似的语法，用大括号 {} 表示映射，方括号 [] 表示序列，并用逗号 , 分隔元素。适用于短小的数据结构。
```
# 块样式
block_map:
  key1: value1
  key2: value2

# 流样式
flow_map: {key1: value1, key2: value2}
flow_list: [item1, item2, item3]
```

1.4 多行字符串

YAML 1.1提供了两种处理多行字符串的方式：

折叠式 (Folded Style) >：将多行文本折叠成一行，换行符会被替换为空格，但空行会保留。

folded_string: >
  This is a long string
  that spans multiple lines.
  Newlines are replaced by spaces.

  Empty lines create new paragraphs.
# 解析结果："This is a long string that spans multiple lines. Newlines are replaced by spaces.\nEmpty lines create new paragraphs."

字面式 (Literal Style) |：保留所有换行符和缩进。

literal_string: |
  This is a literal string.
    It preserves all
  newlines and indentation.
# 解析结果："This is a literal string.\n  It preserves all\nnewlines and indentation.\n"

1.5 锚点与引用 (Anchors & Aliases)

锚点 & 和引用 * 允许你在YAML文档中定义一个可复用的数据块，并在其他地方引用它，从而避免重复。这对于定义模板或共享配置非常有用。

common_settings: &default_settings
  timeout: 30
  retries: 3

service_a:
  <<: *default_settings # 合并默认设置
  name: Service A
  port: 8080

service_b:
  <<: *default_settings
  name: Service B
  port: 9090
  retries: 5 # 可以覆盖默认设置

1.6 标签 (Tags)

标签 !! 用于显式指定数据类型，这在YAML解析器无法正确推断类型时非常有用。YAML 1.1支持多种隐式标签和显式标签。

# 隐式类型推断
number: 123
boolean: true

# 显式指定类型
explicit_string: !!str 123 # 强制解析为字符串
explicit_int: !!int "100" # 强制解析为整数

1.7 注释

使用 # 符号进行注释，注释从 # 开始，到行尾结束。

# 这是一个单行注释
key: value # 这是一个行尾注释

YAML 1.1的语法相对灵活，但在某些边缘情况下可能导致解析歧义。这促使了YAML 1.2的诞生，旨在提供更严格和一致的解析行为。在下一节中，我们将深入探讨YAML 1.2的语法特性。

2. YAML 1.2语法详解

YAML 1.2版本在YAML 1.1的基础上进行了多项改进，旨在提高数据解析的严格性、一致性，并实现与JSON的完全兼容。本节将详细介绍YAML 1.2的核心语法，并重点突出与YAML 1.1的主要差异。

2.1 JSON兼容性

YAML 1.2最重要的特性之一是其作为JSON超集的地位。这意味着任何有效的JSON文档都是一个有效的YAML 1.2文档。这使得YAML 1.2能够无缝地与JSON生态系统集成，方便数据在两者之间转换。

# JSON示例，同时也是有效的YAML 1.2
{
  "name": "Alice",
  "age": 30,
  "isStudent": false,
  "courses": ["Math", "Science"]
}

2.2 更严格的数据类型处理

YAML 1.2对数据类型的解析规则进行了严格化，减少了歧义，提高了不同解析器之间的一致性。

布尔值 (Booleans)：仅支持 true 和 false（大小写不敏感）。YAML 1.1中支持的 on/off、yes/no 等在YAML 1.2中不再被视为布尔值，而是字符串。
```
is_active: true
is_enabled: false
# 以下在YAML 1.2中会被解析为字符串，而不是布尔值
# old_style_true: Yes
# old_style_false: No
```
空值 (Null)：仅支持 null 和 ~。YAML 1.1中可能被解析为空值的其他形式（如空字符串 ''）在YAML 1.2中不再被视为null。
```
empty_value: null
another_empty: ~
```
数字 (Numbers)：对八进制和十六进制的表示更加明确。例如，八进制数必须以 0o 开头，十六进制数以 0x 开头。
```
decimal: 100
octal: 0o144 # 对应十进制的 100
hexadecimal: 0x64 # 对应十进制的 100
```
日期和时间 (Dates & Times)：严格遵循ISO 8601标准，解析更加一致。
```
date: 2023-10-26
datetime: 2023-10-26T10:30:00Z
```

2.3 字符串解析的明确性

YAML 1.2在字符串解析方面更加明确，避免了某些看起来像数字或布尔值的字符串被错误解析。如果一个字符串可能被误解为其他类型，建议使用引号明确指定其为字符串。

# 在YAML 1.2中，这些都会被正确解析为字符串
string_number: "123"
string_boolean: "true"
string_null: "null"

# 如果不加引号，"123"会被解析为整数，"true"会被解析为布尔值
# 这与YAML 1.1的行为一致，但YAML 1.2更强调明确性

2.4 锚点与引用 (Anchors & Aliases)

锚点和引用的基本功能在YAML 1.2中保持不变，但其行为在某些复杂场景下可能更加稳定和可预测。合并键 <<: 仍然是常用的特性。

common_config: &base_config
  log_level: INFO
  max_connections: 100

service_alpha:
  <<: *base_config
  name: Alpha Service
  port: 8080

service_beta:
  <<: *base_config
  name: Beta Service
  port: 9090
  log_level: DEBUG # 覆盖基配置

2.5 标签 (Tags)

标签的使用方式与YAML 1.1类似，但YAML 1.2对标准标签集进行了更新和规范，以更好地支持JSON兼容性和类型一致性。例如，!!str、!!int、!!bool、!!null 等标准标签的使用。

explicit_string: !!str 123
explicit_boolean: !!bool "true"

2.6 块序列的缩进

在YAML 1.2中，块序列（列表）的子元素缩进规则更加严格。列表项的子元素必须比列表项本身有更多的缩进。

# 正确的YAML 1.2块序列缩进
items:
  - name: Item A
    value: 10
  - name: Item B
    value: 20

# 错误的YAML 1.2块序列缩进（子元素与列表项对齐）
# items:
#   - name: Item C
#   value: 30 # 错误：value没有比- name: Item C更多的缩进

YAML 1.2通过这些改进，提供了更健壮、更可预测的解析行为，并增强了与JSON的互操作性。虽然这些变化可能导致与YAML 1.1文档的某些不兼容，但它们对于构建更可靠的数据处理系统至关重要。在下一节中，我们将通过表格形式，更直观地对比YAML 1.1和1.2之间的关键语法差异，并探讨这些差异可能带来的兼容性问题。

3. YAML 1.1与1.2语法差异与兼容性对比

YAML 1.1和1.2版本在设计理念和具体实现上存在一些关键差异，这些差异可能导致在不同解析器或不同版本之间的数据兼容性问题。下表将详细对比这些差异，并分析其对实际使用的影响。

特性/版本	YAML 1.1 (2005)	YAML 1.2 (2009)	兼容性影响与建议
JSON兼容性	非JSON超集	JSON超集	YAML 1.1文档可能不是有效的JSON。YAML 1.2文档天然兼容JSON，便于数据互转。建议使用YAML 1.2以获得更好的JSON互操作性。
布尔值	宽松：`true`, `false`, `on`, `off`, `yes`, `no` (大小写不敏感)	严格：仅 `true`, `false` (大小写不敏感)	YAML 1.1中被解析为布尔值的 `on`/`off`/`yes`/`no` 在YAML 1.2中会被解析为字符串。影响：旧文档在新解析器中可能行为异常。建议：统一使用 `true`/`false`。
空值 (Null)	宽松：`null`, `~`, `Null`, `NULL` 等	严格：仅 `null`, `~` (大小写不敏感)	类似布尔值，YAML 1.1中某些形式的空值在YAML 1.2中可能被解析为字符串。影响：同上。建议：统一使用 `null` 或 `~`。
数字解析	宽松：`0` 开头的数字可能被解析为八进制（如 `010` 解析为 `8`）	严格：八进制必须 `0o` 开头（如 `0o10` 解析为 `8`），十六进制 `0x` 开头。	YAML 1.1中 `0` 开头的数字可能导致意外的八进制解析。影响：数据值可能不符预期。建议：避免 `0` 开头的数字，或显式指定类型。
字符串解析	某些看起来像数字、布尔值或空值的字符串可能被隐式解析为对应类型。	更加明确：除非显式指定，否则倾向于解析为字符串。	YAML 1.1的隐式解析可能导致数据类型错误。影响：数据类型不一致。建议：对可能引起歧义的字符串加引号。
日期和时间	宽松：支持多种日期时间格式	严格：主要遵循ISO 8601标准	YAML 1.1可能接受非标准格式。影响：跨系统解析不一致。建议：统一使用ISO 8601标准格式。
文档结束标记	`...` (可选)	`...` (可选)	行为一致。
流样式映射键	键可以不加引号	键必须加引号（如果包含特殊字符）	YAML 1.1中 `key: value` 在流样式中可能不加引号。影响：YAML 1.2解析器可能报错。建议：流样式映射键始终加引号。
合并键 `<<:`	广泛支持	广泛支持	行为一致，但YAML 1.2的解析更稳定。

兼容性问题总结：

YAML 1.1的“宽松”特性在某些情况下可能导致解析器之间的不一致行为，尤其是在处理布尔值、空值和数字时。YAML 1.2通过引入更严格的规则和对JSON的兼容性，解决了这些问题，提供了更可靠和可预测的解析。因此，当从YAML 1.1迁移到1.2时，或在混合使用不同版本解析器的环境中，需要特别注意上述差异，以避免潜在的数据解析错误。

在下一节中，我们将探讨不同编程语言和工具对YAML版本支持的差异，并提供解决兼容性问题的实践建议。

4. 不同工具对YAML版本支持差异

在实际开发中，我们经常会使用各种编程语言和工具来解析和处理YAML文件。然而，不同的解析库和工具对YAML版本的支持程度可能存在差异，这可能导致在跨环境或跨工具协作时出现问题。了解这些差异对于确保YAML配置的正确解析和应用至关重要。

以下是一些主流编程语言的YAML解析库及其对YAML版本支持的概况：

Python

PyYAML: 这是Python中最常用的YAML库。默认情况下，PyYAML 会尝试解析符合YAML 1.1规范的文档，但它也支持YAML 1.2的某些特性。在加载时，可以通过 yaml.safe_load() 或 yaml.load() 函数的 Loader 参数来指定更严格的解析模式，例如 yaml.SafeLoader 或 yaml.FullLoader。对于YAML 1.2的严格模式，通常需要确保输入符合1.2规范，并且某些1.1的宽松语法（如 on/off 作为布尔值）在新版本中会被解析为字符串。

Java

SnakeYAML: Java生态系统中最流行的YAML解析器。SnakeYAML 默认支持YAML 1.1规范。它提供了配置选项来调整解析行为，但完全遵循YAML 1.2的严格模式可能需要额外的配置或对输入进行预处理。在处理布尔值、空值和数字时，SnakeYAML 的行为可能与YAML 1.1的宽松规则更接近。

JavaScript/Node.js

js-yaml: Node.js环境中广泛使用的YAML解析器。js-yaml 默认支持YAML 1.2规范，并且对JSON兼容性有很好的支持。它通常能够正确处理YAML 1.2的严格布尔值和空值定义。对于旧的YAML 1.1文档，js-yaml 可能会在遇到不符合1.2规范的语法时报错或给出警告。

Go

gopkg.in/yaml.v2 (或 gopkg.in/yaml.v3): Go语言中常用的YAML库。yaml.v2 和 yaml.v3 都倾向于支持YAML 1.2规范，尤其是在数据类型解析方面。它们通常会更严格地处理布尔值、空值和数字，与YAML 1.2的行为一致。这使得Go语言在处理现代YAML配置时更加可靠。

Ruby

Psych (Ruby标准库): Ruby内置的YAML解析器，基于 libyaml。Psych 默认支持YAML 1.1，但随着Ruby版本的更新，对YAML 1.2的兼容性也在逐步提高。然而，在处理一些边缘情况时，其行为可能仍然更偏向于YAML 1.1的宽松解析。

C#/.NET

YamlDotNet: .NET平台下功能丰富的YAML库。YamlDotNet 提供了对YAML 1.1和1.2的支持，并且允许开发者通过配置来选择解析模式。这使得它在处理不同版本的YAML文档时具有较高的灵活性。

总结不同工具支持差异：

默认版本倾向：许多较老的库或语言的内置解析器可能默认倾向于YAML 1.1，而较新的库或框架则可能默认支持YAML 1.2。
严格性：YAML 1.2的严格性（尤其是在布尔值、空值和数字解析方面）在不同库中的实现程度不同。有些库会严格遵循，有些则会为了向后兼容而保持一定的宽松性。
配置选项：一些高级库提供了配置选项，允许开发者显式选择要遵循的YAML版本或调整解析行为。
JSON兼容性：对JSON兼容性的支持是YAML 1.2的一个重要特性，但并非所有YAML 1.1解析器都能很好地处理JSON格式的YAML文档。

了解这些差异后，在编写和使用YAML文件时，我们就能更好地选择合适的工具和库，并采取相应的策略来避免兼容性问题。在下一节中，我们将提供一些解决这些兼容性问题的实践建议。

5. 解决兼容性问题的实践建议

鉴于YAML 1.1和1.2版本之间的差异以及不同工具对它们支持程度的不同，在实际项目中处理YAML文件时，采取一些实践建议可以有效避免兼容性问题，确保配置的稳定性和可靠性。

1. 明确指定YAML版本

在YAML文件的开头，明确指定所使用的YAML版本是一个良好的实践。这有助于解析器以正确的模式解析文档，尤其是在混合环境中。

# YAML 1.2
%YAML 1.2
---
key: value

或者，如果你的工具链更倾向于YAML 1.1，也可以这样指定：

# YAML 1.1
%YAML 1.1
---
key: value

注意：并非所有解析器都严格遵守此指令，但它提供了一个重要的提示。

2. 优先使用YAML 1.2规范

如果项目条件允许，尽量使用YAML 1.2规范来编写YAML文件。YAML 1.2是当前推荐的版本，它提供了更好的JSON兼容性和更严格的解析规则，减少了歧义。

3. 避免使用歧义语法

布尔值和空值：统一使用 true / false 和 null / ~。避免使用 on/off、yes/no、Y/N 等在YAML 1.1中被解释为布尔值，但在YAML 1.2中可能被解释为字符串的表达方式。
数字：避免使用 0 开头的数字（八进制）或 . 结尾的浮点数（如 1.）。如果需要表示八进制，使用 0o 前缀（如 0o10）。
字符串：对于可能被误判为其他数据类型（如数字、布尔值）的字符串，始终使用引号（单引号或双引号）将其括起来。
```
# 避免歧义的字符串
version: "1.0"
is_active: "true"
port: "8080"
```