YAML 详解

YAML 详解

什么是 YAML？

YAML（YAML Ain’t Markup Language）是一种人类友好的数据序列化语言，专门用于配置文件和数据交换。它比 JSON 更易读，比 XML 更简洁，广泛用于各种编程语言和工具的配置。

核心特点

1. 可读性强

• 使用缩进表示层次结构
• 无需大量标点符号
• 支持自然语言风格的配置

2. 语言无关

• 几乎所有现代编程语言都支持 YAML
• 可以轻松转换为 JSON、XML 等其他格式

3. 表达能力强

• 支持复杂的数据结构
• 包含引用、多行文本等高级特性

基本语法

数据结构

标量（Scalars）

# 字符串name:"John Doe"simple_string:Hello Worldnumber_as_string:'123'# 数字age:30price:19.99scientific:1.2e+5# 布尔值is_active:trueenabled:false# 空值middle_name:nullnickname:~

序列（列表/数组）

# 短横线表示法fruits:-Apple-Banana-Orange# 行内表示法colors:[Red,Green,Blue]# 嵌套列表matrix:-[1,2,3]-[4,5,6]

映射（字典/对象）

# 基本映射person:name:Johnage:30city:New York# 行内表示法car:{make:Toyota,model:Camry,year:2020}

多行文本

# 保留换行符（|）description:|This is a long description that spans multiple lines. Each newline is preserved.# 折叠为单行（>）summary:>This is a summary that will be folded into a single line with spaces.# 保留尾随换行符（|+）# 删除尾随换行符（|-）

特殊特性

锚点和别名（引用）

# 定义锚点defaults:&defaultsadapter:postgreshost:localhost# 引用锚点development:<<:*defaults# 合并映射database:dev_dbtest:<<:*defaultsdatabase:test_db

多文档支持

# 用 --- 分隔多个文档---server:port:8080host:localhost---database:name:app_dbuser:admin

数据类型详细说明

字符串类型

# 不需要引号（除非有特殊字符）simple:This is a string# 需要引号的情况special:"Text with: colon, and other special chars"single_quotes:'Avoid escaping single quotes'' here'

数字类型

# 整数decimal:42octal:0o52# 八进制hexadecimal:0x2A# 十六进制# 浮点数float:3.14infinity:.inf# 无穷大not_a_number:.NaN

时间类型

date:2023-12-25datetime:2023-12-25T14:30:00Ziso_datetime:2023-12-25T14:30:00+08:00

注释

# 这是单行注释key:value# 行内注释# 多行注释需要每行都用 ## 这是第二行注释

YAML vs JSON vs XML

示例对比

YAML:

person:name:Johnage:30hobbies:-reading-swimmingaddress:city:New Yorkzip:"10001"

JSON:

{"person":{"name":"John","age":30,"hobbies":["reading","swimming"],"address":{"city":"New York","zip":"10001"}}}

XML:

<person><name>John</name><age>30</age><hobbies><hobby>reading</hobby><hobby>swimming</hobby></hobbies><address><city>New York</city><zip>10001</zip></address></person>

使用场景

1. 配置文件

# Docker Compose 示例version:'3.8'services:web:image:nginx:latestports:-"80:80"volumes:-./html:/usr/share/nginx/htmldb:image:postgres:13environment:POSTGRES_PASSWORD:secret

2. CI/CD 配置

# GitHub Actions 示例name:CI Pipelineon:[push,pull_request]jobs:test:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v2-name:Run testsrun:npm test

3. Kubernetes 配置

# Kubernetes DeploymentapiVersion:apps/v1kind:Deploymentmetadata:name:nginx-deploymentspec:replicas:3selector:matchLabels:app:nginxtemplate:metadata:labels:app:nginxspec:containers:-name:nginximage:nginx:1.14.2ports:-containerPort:80

最佳实践

1. 一致的缩进

• 使用 2 个空格（推荐）或 4 个空格
• 不要混用制表符和空格

2. 键命名规范

# 使用小写和下划线api_key:"value"database_name:"prod_db"

3. 避免复杂嵌套

# 不好level1:level2:level3:level4:value:too_deep# 更好（如果可能）flat_structure:level1_level2_level3_level4_value:data

4. 使用引用减少重复

# 定义通用配置common_settings:&commontimeout:30retries:3# 复用service_a:<<:*commonendpoint:"/api/a"service_b:<<:*commonendpoint:"/api/b"

常用工具

1. 验证工具

• yamllint: YAML 语法检查器
• yq: YAML 的 jq（命令行处理工具）

2. 转换工具

# YAML 转 JSONpython -c'import yaml, json, sys; print(json.dumps(yaml.safe_load(sys.stdin)))'<file.yaml# JSON 转 YAMLpython -c'import yaml, json, sys; print(yaml.dump(json.load(sys.stdin)))'<file.json

3. 编辑器支持

• VS Code（YAML 扩展）
• IntelliJ IDEA / PyCharm
• Sublime Text
• Vim / Emacs

常见陷阱

1. 缩进错误

# 错误：混用空格和制表符data:key:value# 4个空格tab:value# 制表符（危险！）

2. 布尔值歧义

# 这些会被解析为字符串，而不是布尔值yes_as_bool:yes# 实际是字符串 "yes"no_as_bool:"no"# 明确字符串true_as_bool:true# 布尔值 true

3. 数字作为字符串

# 如果需要将数字保持为字符串，使用引号zip_code:"10001"# 字符串postal_code:10001# 数字

安全注意事项

1. 避免执行任意代码

# 危险！某些解析器支持执行代码danger:!!python/object/apply:os.system["rm -rf /"]

2. 使用安全加载

# Python 示例：使用 safe_load 而不是 loadimportyaml# 安全data=yaml.safe_load(yaml_content)# 危险data=yaml.load(yaml_content,Loader=yaml.Loader)

YAML 的简洁性和可读性使其成为现代开发中不可或缺的工具，特别是在 DevOps、云原生应用和配置管理领域。掌握 YAML 可以显著提高工作效率和配置文件的维护性。