Spring Boot 中 .yml 文件的完整知识体系，涵盖基础语法、高级特性、实践技巧等维度，可作为系统学习或日常开发的参考手册。

一、YAML 基础概述

1. YAML 定义与特点

• 定义：YAML（YAML Ain’t Markup Language）是一种人类可读的数据序列化格式，以层级缩进表示数据结构，适合作为配置文件。
• 核心特点：
  • 大小写敏感
  • 以缩进表示层级关系（禁止使用 Tab，只能用空格）
  • 支持复杂数据结构（列表、嵌套对象）
  • 语法简洁，可读性强

2. Spring Boot 对 YAML 的支持

• Spring Boot 默认集成 YAML 解析（依赖 SnakeYAML 库），无需额外配置。
• 支持 application.yml 替代传统的 application.properties，且两者可共存（YAML 优先级更高）。

---

二、YAML 核心语法规则

1. 基本语法规范

• 键值对：key: value（冒号后必须加空格；大小写敏感）
• 层级缩进：用空格表示嵌套关系（必须使用空格，禁用Tab，通常 2 或 4 个空格）；缩进数量代表层级（相同缩进的键属于同一层级）。
• 注释：# 注释内容（仅支持单行注释）

2. 数据类型

类型	示例	说明
标量	name: ZhangSan	字符串、数字、布尔值等
序列	fruits: [apple, banana] 或 fruits: - apple - banana	列表/数组
映射	user: name: LiSi age: 25	嵌套对象（键值对集合）

3. 特殊语法

• 多行字符串：
  • |：保留换行符（如日志内容）
  • >：折叠换行符（如长描述）
• 引用与合并：
  • & 定义锚点，* 引用锚点，<<: 合并锚点（用于复用配置）

  default: &default
    timeout: 30
  service:
    <<: *default  # 复用 default 的配置
    port: 8080
  

---

一、YAML 基本语法规范

YAML 的核心设计是「以人类可读为优先」，通过缩进和简单符号表达数据结构，无需复杂的标签或括号。

1. 键值对（Key-Value）

YAML 最基础的结构是键值对，格式为 key: value，需注意：

• 冒号后必须加空格：name: ZhangSan（正确），name:ZhangSan（错误）。
• 大小写敏感：Name 和 name 是两个不同的键。

示例（Spring Boot 基础配置）：

server:
  port: 8080  # 键：server.port，值：8080
  servlet:
    context-path: /myapp  # 嵌套键：server.servlet.context-path

2. 层级缩进（表示嵌套关系）

YAML 用空格缩进表示数据的层级关系，需注意：

• 禁止使用 Tab：必须用空格（通常 2 或 4 个空格，保持一致即可）。
• 缩进数量代表层级：相同缩进的键属于同一层级。

错误示例（Tab 代替空格）：

server:
	port: 8080  # ❌ 用了 Tab，会导致解析失败

正确示例（嵌套对象）：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/testdb
    username: root
    password: 123456

3. 注释

YAML 仅支持单行注释，用 # 开头，注释内容会被解析器忽略。

# 这是服务器配置
server:
  port: 8080  # 端口号（行内注释）

---

二、YAML 数据类型

YAML 支持丰富的数据类型，可直接映射到 Java 的基本类型、集合或对象。

1. 标量（Scalar）：单个值

标量是最基础的数据类型，包括字符串、数字、布尔值、Null 等。

类型	示例	说明
字符串	name: ZhangSan 或 name: "Zhang San"	通常无需引号，含特殊字符（如 :、#）时需加引号
数字	age: 25、price: 3.14	支持整数、浮点数
布尔值	enabled: true、flag: false	直接写 true/false
Null	value: null 或 value: ~	表示空值

字符串特殊场景：

• 含特殊字符时用双引号：path: "C:\\Users\\Admin"（转义字符生效）。
• 单引号会保留原始内容：desc: 'Hello # World'（# 不会被当作注释）。

2. 序列（Sequence）：列表/数组

序列用于表示一组有序的值，有两种写法：

• 短横线写法（推荐，可读性强）：

  fruits:
    - apple
    - banana
    - orange
  

• 方括号写法（紧凑写法）：

  fruits: [apple, banana, orange]
  

Spring Boot 场景示例（配置拦截路径）：

spring:
  mvc:
    interceptors:
      - path: /api/**
        exclude: /api/login
      - path: /admin/**

3. 映射（Mapping）：嵌套对象

映射用于表示键值对的集合（即 Java 中的 Map 或自定义对象），通过缩进实现嵌套。

示例（自定义配置对象）：

app:
  name: MySpringBootApp
  author:
    name: ZhangSan
    email: zhangsan@example.com
  version: 1.0.0

对应 Java 绑定（@ConfigurationProperties）：

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private Author author; // 嵌套对象
    private String version;
    // getters and setters
}

---

三、YAML 特殊语法

1. 多行字符串

YAML 提供两种方式处理多行文本，避免在一行写长字符串：

• |（保留换行符）：保留文本中的换行和缩进，适合日志、代码片段。

  log:
    content: |
      2024-01-01 10:00:00 INFO  Application started
      2024-01-01 10:00:01 DEBUG  Database connected
  

• >（折叠换行符）：将换行符替换为空格，适合长描述文本。

  desc: >
    这是一个很长的描述文本，
    会被折叠成一行显示，
    但保留空格分隔。
  

2. 引用与合并（复用配置）

YAML 支持通过**锚点（&）和引用（*）复用配置，结合合并键（<<:）**可实现配置继承。

示例（复用公共配置）：

# 定义公共配置锚点
default: &default
  timeout: 30
  retry: 3

# 开发环境：复用 default 配置，覆盖 port
dev:
  <<: *default  # 合并 default 的所有键值
  port: 8080

# 生产环境：复用 default 配置，覆盖 port 和 timeout
prod:
  <<: *default
  port: 80
  timeout: 60  # 覆盖 default 的 timeout

---

四、Spring Boot 特有的 YAML 语法

1. 占位符与默认值

YAML 中可使用 ${key:default} 引用其他配置项，冒号后为默认值（当 key 不存在时使用）。

示例：

app:
  name: MyApp
  full-name: ${app.name:DefaultApp} - v1.0  # 引用 app.name
  temp-path: ${java.io.tmpdir:/tmp}  # 引用系统属性，默认 /tmp

2. 随机值配置

Spring Boot 提供 random.* 前缀生成随机值，常用于测试或临时配置：

app:
  secret: ${random.uuid}  # 随机 UUID
  port: ${random.int(8000,9000)}  # 8000-9000 之间的随机整数
  number: ${random.long}  # 随机长整数

3. 多环境 Profile 配置

YAML 支持通过 spring.profiles 区分不同环境（开发、测试、生产），有两种方式：

• 单文件多文档块（用 --- 分隔）：

  # 默认配置
  spring:
    application:
      name: MyApp
  
  ---
  # 开发环境配置
  spring:
    profiles: dev
  server:
    port: 8080
  
  ---
  # 生产环境配置
  spring:
    profiles: prod
  server:
    port: 80
  

• 多文件方式：单独创建 application-dev.yml、application-prod.yml，在 application.yml 中激活：

  spring:
    profiles:
      active: dev  # 激活开发环境
  

注意事项

1. 缩进错误：必须用空格，禁止 Tab，否则解析失败。
2. 冒号后无空格：key:value 会被当作一个字符串，而非键值对。
3. 特殊字符未加引号：字符串含 :、#、{、} 等字符时，需用引号包裹，如 url: "http://example.com:8080"。
4. 布尔值/数字被当作字符串：enabled: "true" 会被解析为字符串，而非布尔值（去掉引号即可）。

---

三、Spring Boot 中 YAML 配置优先级

1. 配置文件位置优先级（从高到低）

1. file:./config/（项目根目录下的 config 文件夹）
2. file:./（项目根目录）
3. classpath:/config/（类路径下的 config 文件夹）
4. classpath:/（类路径根目录，如 resources 文件夹）

2. 多环境配置优先级

• 激活的 Profile 配置（application-{profile}.yml）覆盖默认配置（application.yml）。
• 激活方式：spring.profiles.active=dev（在 application.yml 或命令行指定）。

3. 全量配置源优先级（从高到低）

1. 命令行参数（--server.port=8081）
2. 外部配置文件（file:./application.yml）
3. 内部配置文件（classpath:/application.yml）
4. 默认属性（SpringApplication.setDefaultProperties()）

---

四、YAML vs Properties：对比与选择

维度	YAML	Properties
语法	层级缩进，结构清晰	点号分隔（server.port=8080）
数据结构	支持列表、嵌套对象	需特殊处理（如 list[0]=a）
可读性	适合复杂配置	适合简单配置
优先级	高于 Properties（同位置时）	低于 YAML

---

五、Spring Boot 中 YAML 常用配置示例

1. 服务器与 Web 配置

server:
  port: 8080
  servlet:
    context-path: /myapp  # 上下文路径

2. 数据源与持久层配置

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/testdb
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update  # 自动更新表结构

3. 日志配置

logging:
  level:
    root: INFO
    com.example: DEBUG  # 指定包日志级别
  file:
    name: logs/myapp.log  # 日志文件路径

4. 自定义配置

app:
  name: MySpringBootApp
  author:
    name: ZhangSan
    email: zhangsan@example.com

---

六、YAML 高级特性与进阶用法

1. 多环境 Profile 配置

• 定义环境配置文件：application-dev.yml（开发）、application-prod.yml（生产）。
• 在 application.yml 中激活：

  spring:
    profiles:
      active: dev  # 激活开发环境
  

2. 占位符与变量引用

• 引用配置项：${app.name:DefaultApp}（冒号后为默认值）。
• 随机值：${random.uuid}、${random.int(1,100)}。

3. 类型安全的配置属性（@ConfigurationProperties）

• 将 YAML 配置绑定到 Java 对象，实现类型安全：

  @Component
  @ConfigurationProperties(prefix = "app")
  public class AppProperties {
      private String name;
      private Author author;
      // getters and setters
  }
  

4. YAML 扩展与集成

• 支持 Spring Cloud Config 配置中心。
• 可通过 PropertySource 加载自定义 YAML 文件（需额外配置解析器）。

---

七、常见问题与注意事项

1. 语法陷阱

• 缩进错误：必须用空格，禁止 Tab。
• 冒号后无空格：key:value 错误，应为 key: value。
• 特殊字符：字符串含 :、# 等字符时需用引号包裹（"key: value"）。

2. 配置优先级混淆

• 同位置时，application.yml 覆盖 application.properties。
• 激活的 Profile 配置覆盖默认配置。

3. 编码与乱码

• YAML 文件需使用 UTF-8 编码，避免中文乱码。

---

八、YAML 配置最佳实践

1. 结构分层：按模块分组配置（如 server、spring、logging）。
2. 多环境管理：用 Profile 隔离开发、测试、生产配置。
3. 类型安全：优先使用 @ConfigurationProperties 绑定配置。
4. 注释与文档：关键配置添加注释，说明用途和默认值。
5. 配置复用：用 YAML 锚点（&、*）复用公共配置。

---