YAML语法完全指南

一、YAML 简介

YAML（“YAML Ain't Markup Language”的递归缩写，原意是Yet Another Markup Language）。与 JSON 和 XML 相比，YAML 使用更简洁的语法，通过缩进来表示结构，避免了大量的括号和引号。

YAML 广泛应用于配置文件、DevOps（如 Kubernetes、Ansible、Docker Compose）、持续集成/交付管道等场景，被认为是适合人类书写和阅读的数据交换格式。

主要特点：

可读性高
支持复杂数据结构
跨语言支持
可扩展性强

基本规范：

大小写敏感
使用空格缩进表示层级关系（不可以使用 TAB）
基本数据类型包括 Null、布尔、字符串、整数、浮点数、日期和时间等
单个文件包括多个 YAML 数据结构时使用 --- 分割

二、基本数据类型

Null 值

表示空值，有多种表示方式：

null_value: null
empty_value: 
another_null: ~

布尔值

true_value: true
false_value: false
# 也可以使用首字母大写形式
True_value: True
False_value: False

字符串

simple_string: Hello World
quoted_string: "Hello World"
single_quoted: 'Hello World'

整数和浮点数

integer: 42
negative: -42
float: 3.14
scientific: 1.2e+34

日期和时间

YAML 支持 ISO 8601 格式的日期和时间：

date: 2023-10-05
datetime: 2023-10-05T17:23:45Z
datetime_with_timezone: 2023-10-05T17:23:45+08:00

三、复杂数据结构

列表（序列Sequence）

使用连字符和空格表示列表项：

fruits:
  - Apple
  - Banana
  - Orange

# 行内表示
numbers: [1, 2, 3, 4, 5]

字典（映射Mapping）

使用键值对表示：

person:
  name: John Doe
  age: 30
  city: New York

# 行内表示
inline_dict: {name: John, age: 30}

字典列表

组合使用映射和序列：

users:
  - name: Alice
    age: 25
    email: alice@example.com
  - name: Bob
    age: 30
    email: bob@example.com

四、其他特性

1. 多行字符串

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

字面块（Literal Block）

保留换行符和缩进：

description: |
  This is a multi-line
  string that preserves
  line breaks and indentation.

折叠块（Folded Block）

将换行符转换为空格：

summary: >
  This is a multi-line
  string that folds
  line breaks into spaces.

保留换行符

明确指定换行处理方式：

with_newlines: |+
  保留文本末尾的换行符

without_newlines: |-
  删除文本末尾的换行符

2.片段和引用

YAML 支持锚点和别名，避免重复数据：

锚点（Anchor）和别名（Alias）

这里 &p 定义 anchor，*p 为 alias。片段和引用属于表示层（serialization tree），最终在内部表示图中展开为普通节点

person: &p
  name: Alice
  age: 30

friend: *p

合并键（Merge Key）

base: &base
  name: Everyone
  age: 100

person:
  <<: *base
  name: Someone  # 覆盖基类的name

3.注释

YAML 使用井号（#）表示注释：

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

multiple:
  - item1  # 列表项注释
  - item2
  # 注释可以单独成行
  - item3

五、最佳实践

一致的缩进：使用空格而非制表符，建议使用 2 个空格
合理使用引用：只在必要时使用引号（如包含特殊字符时）
善用注释：为复杂的配置添加说明
使用锚点和别名：避免重复配置项
验证语法：使用在线工具或 IDE 插件验证 YAML 语法

# 应用配置示例
app:
  name: My Application
  version: 1.0.0
  debug: false

database:
  host: localhost
  port: 5432
  name: app_db
  # 定义片段
  credentials: &db-creds
    username: admin
    password: secret123

services:
  - name: api
    port: 8000
    # 引用片段
    database: *db-creds
  - name: worker
    port: 8001
    # 引用片段
    database: *db-creds

logging:
  level: INFO
  file: /var/log/app.log
  format: |
    {timestamp} {level} {message}

参考资源：