【Spring Boot—— .yml（YAML）】Spring Boot中.yml文件的基础语法、高级特性、实践技巧

文章目录

• • 一、YAML 基础概述
  • • 1. YAML 定义与特点
    • 2. Spring Boot 对 YAML 的支持
  • 二、YAML 核心语法规则
  • • 1. 基本语法规范
    • 2. 数据类型
    • 3. 特殊语法
    • 一、YAML 基本语法规范
    • • 1. 键值对（Key-Value）
      • 2. 层级缩进（表示嵌套关系）
      • 3. 注释
    • 二、YAML 数据类型
    • • 1. 标量（Scalar）：单个值
      • 2. 序列（Sequence）：列表/数组
      • 3. 映射（Mapping）：嵌套对象
    • 三、YAML 特殊语法
    • • 1. 多行字符串
      • 2. 引用与合并（复用配置）
    • 四、Spring Boot 特有的 YAML 语法
    • • 1. 占位符与默认值
      • 2. 随机值配置
      • 3. 多环境 Profile 配置
    • 注意事项
  • 三、Spring Boot 中 YAML 配置优先级
  • • 1. 配置文件位置优先级（从高到低）
    • 2. 多环境配置优先级
    • 3. 全量配置源优先级（从高到低）
  • 四、YAML vs Properties：对比与选择
  • 五、Spring Boot 中 YAML 常用配置示例
  • • 1. 服务器与 Web 配置
    • 2. 数据源与持久层配置
    • 3. 日志配置
    • 4. 自定义配置
  • 六、YAML 高级特性与进阶用法
  • • 1. 多环境 Profile 配置
    • 2. 占位符与变量引用
    • 3. 类型安全的配置属性（`@ConfigurationProperties`）
    • 4. YAML 扩展与集成
  • 七、常见问题与注意事项
  • • 1. 语法陷阱
    • 2. 配置优先级混淆
    • 3. 编码与乱码
  • 八、YAML 配置最佳实践

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. 数据类型

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 等。

字符串特殊场景：

• 含特殊字符时用双引号：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 # 激活开发环境

注意事项

三、Spring Boot 中 YAML 配置优先级

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

2. 多环境配置优先级

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

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

四、YAML vs Properties：对比与选择

五、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 配置最佳实践