Spring Boot 中 YAML 配置文件详解

在 Spring Boot 项目中，配置文件是不可或缺的一部分，用于自定义应用行为、覆盖默认设置。除了传统的 properties 文件，Spring Boot 对 YAML（YAML Ain't Markup Language）格式提供了完美支持。YAML 以其简洁的语法、清晰的层级结构，成为许多开发者的首选配置方式。

一、YAML 是什么？为什么用 YAML？

YAML 是一种数据序列化格式 ，设计目标是易读易写 ，同时兼顾机器解析效率。与传统的 properties 文件相比，YAML 具有以下优势：

层级结构清晰 ：通过缩进表示配置之间的父子关系，避免了 properties 中重复的前缀（如 server.port、server.servlet.context-path）。
支持复杂数据类型：原生支持对象、列表、Map 等复杂结构，无需额外语法。
语法简洁 ：去掉了 properties 中的等号和多余标点，减少冗余代码。

Spring Boot 会自动加载 resources 目录下的 application.yml 或 application.yaml 文件，其优先级与 application.properties 一致（可通过配置位置调整优先级）。

二、YAML 基础语法规则

使用 YAML 时，需遵守以下核心规则，否则可能导致配置加载失败：

大小写敏感 ：name 和 Name 代表不同的配置项。
缩进表示层级：使用空格（不允许使用 Tab）缩进，缩进数量不限，但同级配置必须对齐。
键值对格式 ：键与值之间用冒号加空格分隔（如 key: value），冒号后必须有空格。
注释：以 # 开头的行为注释，会被忽略。
字符串无需引号：默认情况下，字符串可以不加引号；若包含特殊字符（如空格、冒号），需用单引号或双引号包裹。

示例：

yaml 复制代码

# 基本键值对
server:
  port: 8080  # 端口配置
  servlet:
    context-path: /demo  # 上下文路径

# 字符串配置（含特殊字符）
app:
  title: "Spring Boot: YAML 教程"  # 双引号保留特殊字符
  description: 'Hello: World'      # 单引号也支持

三、YAML 配置常见数据类型

YAML 支持多种数据类型，从简单值到复杂结构均可轻松表示，以下是开发中常用的类型及示例：

1. 简单数据类型

包括字符串、数字、布尔值等，直接以 key: value 形式定义：

yaml 复制代码

# 简单数据类型示例
user:
  id: 1001          # 数字
  name: 张三         # 字符串
  isVip: true        # 布尔值
  score: 98.5        # 浮点数
  joinDate: 2023-10-01  # 日期（字符串形式）

2. 对象类型

用于表示包含多个属性的实体，支持两种写法：

缩进式：通过缩进体现属性层级。
行内式 ：用 {} 包裹，属性之间用逗号分隔。

示例：

yaml 复制代码

# 对象配置（缩进式）
user1:
  name: 张三
  age: 20
  address: 北京

# 对象配置（行内式）
user2: {name: 李四, age: 22, address: 上海}

3. 集合类型

包括列表（List）和集合（Set），支持两种写法：

短横线式 ：每个元素前加 - （短横线+空格）。
行内式 ：用 [] 包裹，元素之间用逗号分隔。

示例：

yaml 复制代码

# 列表配置（短横线式）
city1:
  - 北京
  - 上海
  - 广州

# 列表配置（行内式）
city2: [北京, 上海, 广州]

# 集合中的元素是对象
students:
  - id: 1
    name: 张三
    age: 20
  - id: 2
    name: 李四
    age: 22

⚠️ 注意：短横线与元素值之间必须有空格，否则会解析错误。

四、Spring Boot 中 YAML 的核心应用

1. 覆盖默认配置

Spring Boot 有许多默认配置（如 Tomcat 端口、日志级别等），可通过 YAML 覆盖：

yaml 复制代码

# 覆盖服务器配置
server:
  port: 8888  # 端口改为 8888（默认 8080）
  tomcat:
    max-threads: 200  # Tomcat 最大线程数

# 日志配置
logging:
  level:
    root: info  # 根日志级别
    com.example: debug  # 自定义包日志级别

2. 自定义配置与读取

除了框架默认配置，还可在 YAML 中定义自定义配置，再通过代码读取使用。

方式 1：@Value 注解（适合简单配置）

@Value 可直接映射 YAML 中的简单值（如字符串、数字），语法为 ${key}：

yaml 复制代码

# 自定义配置
app:
  name: 我的应用
  version: 1.0.0
  authors:
    - 张三
    - 李四

代码中读取：

java 复制代码

@Controller
public class YamlController {
    @Value("${app.name}")
    private String appName;  // 映射 "我的应用"

    @Value("${app.version}")
    private String appVersion;  // 映射 "1.0.0"

    @Value("${app.authors[0]}")  // 读取列表第一个元素
    private String firstAuthor;  // 映射 "张三"

    // 业务方法...
}

⚠️ 注意：@Value 仅支持简单类型，无法直接映射对象或复杂集合。

方式 2：@ConfigurationProperties（适合对象/复杂配置）

当配置项较多或为对象结构时，推荐使用 @ConfigurationProperties 将配置批量映射到实体类：

定义实体类并绑定配置前缀：

java 复制代码

@Component
@ConfigurationProperties(prefix = "user")  // 绑定前缀 "user"
public class UserConfig {
    private Integer id;
    private String name;
    private List<String> address;  // 映射列表

    // getter + setter（必须存在，否则无法绑定）
}

YAML 配置：

yaml 复制代码

# 用户配置（与实体类对应）
user:
  id: 1001
  name: 张三
  address:
    - 北京
    - 上海

使用时直接注入实体类：

java 复制代码

@Controller
public class UserController {
    @Autowired
    private UserConfig userConfig;  // 自动注入配置

    @GetMapping("/user")
    @ResponseBody
    public String getUser() {
        return "ID: " + userConfig.getId() + ", 姓名: " + userConfig.getName();
    }
}

3. 占位符与动态配置

YAML 支持通过 ${} 引用其他配置项或使用框架提供的工具类生成动态值：

引用其他配置

yaml 复制代码

server:
  port: 8080
app:
  url: http://localhost:${server.port}/demo  # 引用 server.port 的值

生成随机值

Spring Boot 提供 random 工具类，可生成随机数、UUID 等：

yaml 复制代码

# 随机值示例
config:
  randomInt: ${random.int}  # 随机整数
  randomIntRange: ${random.int(100, 200)}  # 100-200 之间的随机整数
  randomUUID: ${random.uuid}  # 随机 UUID
  randomLong: ${random.long}  # 随机长整数

五、YAML 配置文件的优先级

Spring Boot 会从多个位置加载 application.yml，优先级从高到低如下（高优先级配置会覆盖低优先级）：

项目根目录下的 /config 子目录（./config/application.yml）
项目根目录（./application.yml）
resources 目录下的 /config 子目录（classpath:/config/application.yml）
resources 目录（classpath:/application.yml）

可根据需求将配置文件放在不同位置，例如：

开发环境配置放在 resources/config 中，方便修改。
生产环境配置放在项目根目录的 config 中，避免打包到 Jar 包内。

六、常见问题与解决方案

配置不生效？
- 检查语法：是否漏写冒号后的空格、缩进是否正确。
- 检查路径：配置文件是否在 resources 目录或指定的优先级目录中。
- 检查注解：使用 @ConfigurationProperties 时，确保实体类有 getter/setter 方法。
中文乱码？
- 确保 YAML 文件编码为 UTF-8（IDEA 中可在 File -> Settings -> Editor -> File Encodings 中设置）。
如何区分多环境？
- 创建多环境配置文件，如 application-dev.yml（开发）、application-prod.yml（生产），通过 spring.profiles.active=dev 指定激活环境。

总结

YAML 以其简洁的语法和强大的表达能力，成为 Spring Boot 配置的优选格式。掌握 YAML 的基础语法、数据类型映射及实战技巧，能显著提升配置文件的可读性和维护性。在实际开发中，建议结合 @ConfigurationProperties 管理复杂配置，并合理利用多环境配置和优先级规则，让配置更加灵活高效。