YAML 介绍及使用

[TOC]

## 1. YAML 介绍

YAML（YAML Ain't Markup Language）是一种用于数据序列化的格式，它被设计成易于人类阅读和编写。YAML 的语法简洁明了，适合用来编写配置文件和其他需要人类可读性的数据文档。

YAML 的意思其实是："Yet Another Markup Language"（仍是一种标记语言），发音是[/ˈjæməl/]

### 1.1. 的一些关键特性

+ **可读性**：YAML 的设计使得数据直观易懂，即使是非程序员也能轻松阅读和编辑。

+ **数据结构**：YAML 支持基本的数据类型，如数字、字符串、布尔值、数组（列表）和映射（字典）。

+ **缩进**：YAML 使用空白字符（通常是空格）来表示数据的层次结构，这使得文件既整洁又易于理解。

+ **注释**：使用 `#` 符号可以添加单行注释。

+ **文档**：一个 YAML 文件可以包含多个文档，每个文档由 `---` 开始，由 `...` 结束，如果一个YAML文件可以省略
 `---`

+ **锚点与别名**：允许定义数据片段并在文档中重复引用它们。

### 1.2. YAML 与 JSON 和 XML 的区别

- **JSON**（JavaScript Object Notation）是一种轻量级的数据交换格式，易于机器生成和解析。YAML 在某些方面比 JSON 更加灵活和强大，例如支持注释和更复杂的结构，其中YAML的锚点引用能定义比JSON更加复杂和简洁的结构。

- **XML**（Extensible Markup Language）是一种标记语言，用于结构化数据。YAML 的语法比 XML 更简洁，更易于编写和阅读。

## 2. YAML 使用

说明YAML的使用语法与规范，通过示例的方式

### 2.1. 使用规范

+ 大小写敏感

+ 使用缩进表示层级关系

+ 缩进不允许使用tab，只允许空格

+ 缩进的空格数不重要，只要相同层级的元素左对齐即可

+ 文档使用 Unicode 编码作为字符标准编码，例如 UTF-8

+ 使用两个空格作为缩进单位

+ YAML 文件中包括多个文档内容时，不要省略`---`和`...`

+ 同一些其它的配置文件（.gitignore）格式一样，`#` 表示注释

### 2.2. 支持的数据结构

+ 纯量（scalars）：标量，单个的、不可再分的值

+ 序列：相当于数组和列表

+ 对象：键值表（相当于 Mapping / Hashes /Dictonary）

### 2.3. 基本语法

#### 2.3.1. 序列

序列的书写方式是 `- + 单个空格 `

<table><tr><th width="33%">基础</th><th width="33%">如果是连续的一类序列，也可以使用[]表示为一组数据的方式书写</th><th width="33%">序列里面可以套序列或对象</th></tr><tr><td style="vertical-align: top;"><pre class="prettyprint linenums prettyprinted" style=""><ol class="linenums"><li class="L0"><code class="lang-yaml">- Red</code></li><li class="L1"><code class="lang-yaml">- Yellow</code></li><li class="L2"><code class="lang-yaml">- Blue</code></li></ol></pre></td><td style="vertical-align: top;"><pre class="prettyprint linenums prettyprinted" style=""><ol class="linenums"><li class="L0"><code class="lang-yaml">- [Red,Yellow,Blue]</code></li><li class="L1"><code class="lang-yaml">- [Chicken,Duck]</code></li></ol></pre></td><td style="vertical-align: top;"><pre class="prettyprint linenums prettyprinted" style=""><ol class="linenums"><li class="L0"><code class="lang-yaml"># 序列里面套序列</code></li><li class="L1"><code class="lang-yaml">---</code></li><li class="L2"><code class="lang-yaml">-</code></li><li class="L3"><code class="lang-yaml"> - Red</code></li><li class="L4"><code class="lang-yaml"> - Yellow</code></li><li class="L5"><code class="lang-yaml"> - Blue</code></li><li class="L6"><code class="lang-yaml">-</code></li><li class="L7"><code class="lang-yaml"> - Chicken</code></li><li class="L8"><code class="lang-yaml"> - Duck</code></li><li class="L9"><code class="lang-yaml">...</code></li><li class="L0"><code class="lang-yaml"># 序列里面套对象（键值）</code></li><li class="L1"><code class="lang-yaml">---</code></li><li class="L2"><code class="lang-yaml">-</code></li><li class="L3"><code class="lang-yaml"> Name:'曹操'</code></li><li class="L4"><code class="lang-yaml"> Age:56</code></li><li class="L5"><code class="lang-yaml"> Sex:'男'</code></li><li class="L6"><code class="lang-yaml">-</code></li><li class="L7"><code class="lang-yaml"> Name:'刘备'</code></li><li class="L8"><code class="lang-yaml"> Age:58</code></li><li class="L9"><code class="lang-yaml"> Sex:'男'</code></li><li class="L0"><code class="lang-yaml">...</code></li></ol></pre></td></tr></table>

#### 2.3.2. 键值/对象

对象键值对使用冒号结构表示 `key: value`，冒号后面要加一个空格，也可以使用 key:{key1: value1, key2: value2, ...}

<table><tr><th width="33%">基础</th><th width="33%">`? + 空格` 代替复杂的key</th><th width="33%">组合结构</th></tr><tr><td style="vertical-align: top;"><pre class="prettyprint linenums prettyprinted" style=""><ol class="linenums"><li class="L0"><code class="lang-yaml">person:</code></li><li class="L1"><code class="lang-yaml"> name: 曹操</code></li><li class="L2"><code class="lang-yaml"> age: 30</code></li><li class="L3"><code class="lang-yaml"> phone: 123-456-7890</code></li><li class="L4"><code class="lang-yaml"># 上面的写法也可以用下面的方式表达</code></li><li class="L5"><code class="lang-yaml">person: {name: 曹操,age: 30,phone: 123-456-7890}</code></li></ol></pre></td><td style="vertical-align: top;"><pre class="prettyprint linenums prettyprinted" style=""><ol class="linenums"><li class="L0"><code class="lang-yaml"># 复杂key</code></li><li class="L1"><code class="lang-yaml">? [red,yellow,blue]: [frontColor,backColor]</code></li><li class="L2"><code class="lang-yaml"># 上面写法的展开</code></li><li class="L3"><code class="lang-yaml">? -</code></li><li class="L4"><code class="lang-yaml"> - red</code></li><li class="L5"><code class="lang-yaml"> - yellow</code></li><li class="L6"><code class="lang-yaml"> - blue</code></li><li class="L7"><code class="lang-yaml">: -</code></li><li class="L8"><code class="lang-yaml"> - frontColor</code></li><li class="L9"><code class="lang-yaml"> - backColor</code></li></ol></pre></td><td style="vertical-align: top;"><pre class="prettyprint linenums prettyprinted" style=""><ol class="linenums"><li class="L0"><code class="lang-yaml"># 这是一个简单的 YAML 配置文件</code></li><li class="L1"><code class="lang-yaml">person:</code></li><li class="L2"><code class="lang-yaml"> name: 曹操</code></li><li class="L3"><code class="lang-yaml"> age: 30</code></li><li class="L4"><code class="lang-yaml"> hobbies:</code></li><li class="L5"><code class="lang-yaml"> - reading</code></li><li class="L6"><code class="lang-yaml"> - cycling</code></li><li class="L7"><code class="lang-yaml"> - hiking</code></li><li class="L8"><code class="lang-yaml"> contact:</code></li><li class="L9"><code class="lang-yaml"> email: johndoe@example.com</code></li><li class="L0"><code class="lang-yaml"> phone: 123-456-7890</code></li></ol></pre>在这个例子中，`person` 是一个包含多个键值对的对象，其中 `hobbies` 是一个列表，`contact` 是另一个对象。</td></tr></table>

#### 2.3.3. 标量/纯量

标量是最基本的，不可再分的值，包括：字符串、布尔值、整数、浮点数、Null、时间、日期，标量在 YAML 文件中可以直接写出，不需要任何特殊符号来包裹

```yaml
50
hello
2024-07-31
```

上面的三行可以被视为由三个独立标量组成的 YAML 片段。每个标量占据一行，分别是一个整数 (50)、一个字符串 (hello) 和一个日期 (2024-07-31)。在 YAML 中，当标量值各自位于不同的行时，它们被视为独立的实体，除非它们被包含在一个序列或映射中

常见标量的基本使用：

```yaml
boolean:
    - TRUE  #true,True都可以
    - FALSE  #false，False都可以
float:
    - 3.14
    - 6.8523015e+5  #可以使用科学计数法
int:
    - 123
    - 0b1010_0111_0100_1010_1110    #二进制表示
null:
    nodeName: 'node'
    parent: ~  #使用~表示null
string:
    - 哈哈
    - 'Hello world'  #可以使用双引号或者单引号包裹特殊字符
    - newline
      newline2    #字符串可以拆成多行，每一行会被转化成一个空格
date:
    - 2018-02-17    #日期必须使用ISO 8601格式，即yyyy-MM-dd
datetime:
    -  2018-02-17T15:02:31+08:00    #时间使用ISO 8601格式，时间和日期之间使用T连接，最后使用+代表时区
```

#### 2.3.4. 块的使用

块通常用于表示序列（列表）和映射（字典），并且使用缩进来表示层级关系，块常用的两种是块序列和块映射（键值）,一段同一缩进的内容可以看作一段块，序列块以`- + 空格`开头，映射块以一个`: + 空格`开头

##### 2.3.4.1. 块样式和流样式

块样式使用缩进来表示层级，而流样式则在一个紧凑的形式中表示数据

```yaml
user:
  name: Alice
  age: 30
  address: { street: Main Street, city: Anytown, state: California, postal_code: 12345 }
# address 是使用流样式表示的映射。
```

+ 块样式使用缩进来表示层级关系，适合表示多行文本和嵌套的数据结构。
+ 流样式使用紧凑的形式表示数据，适合简单的列表或映射。

##### 2.3.4.2. 块折叠

折叠较长的文本或嵌套结构，让yaml文档看着更加的紧凑，可以通过使用 > 或 | 符号来实现

+  | (pipe) 表示保持文本的原始格式，包括换行和缩进。
 + \> (greater than) 表示折叠文本，删除前导空白，并合并连续的行，这个需要在支持yaml的编辑器下看。

```yaml
description: |
  This is a multi-line text that can span over multiple lines.
  It will be displayed as-is in the output.

folded_text: >
  This is a folded text that spans multiple lines,
  but it will be compacted into one line with no leading spaces.
```

#### 2.3.5. 锚点与引用

在 YAML 中，锚点（anchors）和引用（aliases）是用来避免重复数据和提高文件可读性的特性。它们允许你在文档中定义一个数据片段，并在文档的其他地方引用它，而不需要重新输入相同的数据。这对于长文档和有重复数据结构的情况非常有用。

##### 2.3.5.1. 锚点（Anchors）

锚点用 `&<name>` 定义，其中 `<name>` 是你选择的标识符，用来唯一标识一个数据片段。当你在文档中首次定义一个数据片段时，可以附加一个锚点。

**锚点示例：**

```yaml
person: &default_person
  name: John Doe
  age: 30
  hobbies:
    - reading
    - hiking
```

在这个例子中，`&default_person` 是一个锚点，它指向了 `person` 这个映射。

##### 2.3.5.2. 引用（Aliases）

引用用 `*<name>` 表示，它会引用之前定义过的锚点。当一个数据片段在文档中多次出现时，引用可以避免重复定义。

**引用示例：**

```yaml
person1: *default_person
person2: *default_person
```

在这个例子中，`*default_person` 是一个引用，它引用了前面定义的 `default_person` 锚点。这意味着 `person1` 和 `person2` 都将具有与 `default_person` 相同的值。

##### 2.3.5.3. 锚点和引用的高级用法

锚点和引用还可以用于更复杂的数据结构，如映射和序列的嵌套。例如，你可以在一个序列中引用一个映射，或者在一个映射中引用一个序列。

**高级示例：**

```yaml
friends:
  - &friend1
    name: Alice
    age: 28
  - &friend2
    name: Bob
    age: 32

# 引用朋友映射
group:
  - *friend1
  - *friend2
```

在这个例子中，`&friend1` 和 `&friend2` 是两个不同的锚点，分别指向了两个不同的映射。`group` 序列使用了 `*friend1` 和 `*friend2` 引用来引用这两个映射。

##### 2.3.5.4. 注意事项

- 当你使用引用时，实际上是在共享数据，所以修改一个引用的数据会影响所有引用该数据的其他位置。
- 锚点和引用只在同一份 YAML 文档中有效。它们不能跨文档引用。
- 锚点和引用可以极大地减少冗余，提高 YAML 文件的可维护性和可读性。

> **总结：**
- 锚点（`&<name>`）用于标记一个数据片段，使其可以被后续的引用引用。
- 引用（`*<name>`）用于引用之前定义的锚点，从而避免数据重复。
- 锚点和引用可以帮助你创建更简洁、更易于维护的 YAML 文件，特别是在处理重复数据结构时。

#### 2.3.6. 数据类型

在 YAML 中，类型推断通常是自动进行的，但也可以通过显式指定标签（tag）来定义或覆盖数据类型。YAML 本身支持几种内置类型，如整数、浮点数、字符串、日期、布尔值等。然而，对于更复杂的数据类型或自定义类型，你可以使用标签来明确指定类型。

##### 2.3.6.1. YAML 标签

YAML 使用标签（tag）来表示数据的类型。标签以 `!` 开头，后面跟着类型名称。有两种类型的标签：

+ **系统类型**：YAML 内置的标签，如 `!!int`, `!!str`, `!!bool` 等，用于表示整数、字符串、布尔值等基本数据类型。
+ **自定义类型**：用户定义的标签，用于表示自定义数据结构或外部对象。

##### 2.3.6.2. 显式类型指定

如果你想强制一个特定的类型，可以在数据旁边添加一个标签。例如：

```yaml
age: !!int 42
```

这将确保 `42` 被解释为一个整数类型，即使它没有使用整数通常的表示形式（如没有引号）。

##### 2.3.6.3. 自定义类型

自定义类型通常用于与外部数据模型或应用程序状态关联。自定义类型通常通过使用 `!` 后面跟自定义的类型名称来定义。例如，假设你有一个自定义的 `Person` 类型：

```yaml
- !Person
  name: Alice
  age: 30
```

> **总结：**
- YAML 通过标签来指定数据类型。
- 系统类型由 YAML 自动识别和处理。
- 自定义类型需要你定义标签和相应的处理器，以便 YAML 解析器能够正确地将数据转换为你期望的类型。

[========]

## 本文扩展

YAML 在许多领域得到广泛应用，尤其是在 DevOps 和云原生技术中，例如 Kubernetes、Docker、Ansible 和 Travis CI 等工具都使用 YAML 作为配置文件的首选格式。

## 参考

> **菜鸟教程：**
[YAML 入门教程](https://www.runoob.com/w3cnote/yaml-intro.html)

> **博客园：**
[SpringCloud入门之YAML格式文件规范学习](https://www.cnblogs.com/BlogNetSpace/p/8444861.html)