Note 06. 详解 Springboot3 外部化配置：YAML、Properties 与环境隔离

本章学习路径

1. 核心思想：理解配置与代码分离的必要性及 Spring Boot 的加载顺序。
2. 格式对比：掌握 YAML 的语法优势及与 Properties 的区别。
3. 读取实战：通过 @Value 读取简单值，通过 @ConfigurationProperties 实现类型安全的结构化绑定。
4. 环境隔离：使用 Profiles 实现多环境配置管理。

6.1. 外部化配置的核心思想与加载顺序

6.1.1. “痛点”场景：为什么配置需要与代码分离？

想象一下，在我们刚刚完成的 Hello, World! 项目中，我们需要连接一个数据库。一个初级的做法可能是将数据库连接信息硬编码在代码里：

1
2
3
4
5
6
7
8
9

public class DatabaseConnector {
    public void connect() {
        // 硬编码：极度危险且难以维护
        String url = "jdbc:mysql://localhost:3306/dev_db";
        String username = "root";
        String password = "dev_password";
        // ... 连接逻辑
    }
}

这段代码存在一个致命问题：配置与代码高度耦合。当我们需要将应用从开发环境部署到测试环境，再到生产环境时，数据库的地址、用户名和密码必然会改变。难道我们每次部署都要去修改 Java 源代码，然后重新编译、打包吗？这显然是低效且极易出错的。

解决方案:
将这些易变的配置信息从代码中抽离出来，存放到代码外部的文件（如 application.yml）中。应用程序在启动时去读取这些外部文件，获取配置。这就是 外部化配置 的核心思想。

6.1.2. 关键：Spring Boot 配置的加载优先级顺序

Spring Boot 可以在很多不同的地方查找配置，并且有一套严格的 优先级顺序。高优先级 的配置会 覆盖 低优先级的配置。了解这个顺序对于排查“为什么我改了配置文件但不生效”的问题至关重要。

部署结构示例

假设我们的应用打包后，部署结构如下：

1
2
3
4
5

. 📂 /opt/app/
├── 📄 my-app-1.0.0.jar         # 应用程序 JAR 包
├── 📄 application.yml          # [3] JAR 包外部的配置文件
└── 📂 config/                   # [4] JAR 包外部的 config 目录
    └── 📄 application.yml      # [4] config 目录下的配置文件

在 my-app-1.0.0.jar 内部的 resources/ 目录下也包含一个 application.yml。

配置加载优先级 (由低到高)

1. jar 包内部 的 application.properties 或 application.yml (优先级最低，保底配置)
2. jar 包内部 config/ 目录下的配置文件
3. jar 包外部 的 application.properties 或 application.yml (与 jar 包同级目录)
4. jar 包外部 config/ 目录下的配置文件
5. 操作系统环境变量
6. Java 系统属性 (-Dkey=value)
7. 命令行参数 (--key=value) (优先级最高)

6.2. 主流配置方式：.properties vs .yml

Spring Boot 主要支持两种格式的配置文件：.properties 和 .yml。

6.2.1. application.properties 语法与用法

这是 Java 中传统的配置文件格式，以简单的键值对形式存在。

文件路径: src/main/resources/application.properties

1
2
3
4
5
6
7
8
9

# 服务器端口
server.port=8080

# 数据库连接信息
spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
# 列表写法
my.list[0]=a
my.list[1]=b

6.2.2. application.yml 的层级结构与语法优势

YAML (.yml) 是一种对人类阅读更友好的数据序列化语言。它通过 缩进 来表示层级关系，结构非常清晰。

文件路径: src/main/resources/application.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 服务器配置
server:
  port: 8080

# 数据库连接信息
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    
# 列表写法 (短横线)
my:
  list:
    - a
    - b

6.2.3. 两种格式的优先级与选择建议

6.3. 读取配置：@Value vs @ConfigurationProperties

“痛点”场景:

好了，我们已经在 application.yml 中定义了配置，但我们的 Java 代码如何才能获取到这些值呢？

Spring Boot 提供了两种主流的注解来解决这个问题：@Value 和 @ConfigurationProperties。

6.3.1. [实践] 使用 @Value 读取单个配置

@Value 注解非常适合用于注入 单个、简单 的配置值。

配置文件: src/main/resources/application.yml

1
2
3
4

app:
  name: "My Awesome App"
  owner: "Prorise"
  # 我们故意不设置 port，用于演示默认值

Java 代码: src/main/java/com/example/demo/config/AppInfo.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

package com.example.demo.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class AppInfo {

    // 使用 ${...} 占位符来引用配置文件中的 key
    @Value("${app.name}")
    private String name;

    @Value("${app.owner}")
    private String owner;

    // 使用冒号 ":" 来提供一个默认值
    // 如果配置文件中找不到 app.port，则会使用 8080
    @Value("${app.port:8080}")
    private Integer port;

    @Override
    public String toString() {
        return "AppInfo{name='" + name + "', owner='" + owner + "', port=" + port + "}";
    }
}

测试验证:
编写一个单元测试，注入 AppInfo 并打印，控制台将输出：
AppInfo{name='My Awesome App', owner='Prorise', port=8080}

6.3.2. [推荐] 使用 @ConfigurationProperties 进行类型安全绑定

“痛点”场景:

@Value 注解虽然简单，但如果要注入的配置项非常多（比如一个数据源有十几个配置），在类中写十几个 @Value 注解会显得非常 繁琐和重复。而且，它对复杂的嵌套结构（如 Map）或集合配置（如 List）支持不佳。

解决方案:
@ConfigurationProperties 注解为此而生。它允许我们将配置文件中 一个前缀下的所有属性，整体地、类型安全地 绑定 到一个 Java 对象（POJO）上。

配置文件: src/main/resources/application.yml

1
2
3
4
5
6
7
8
9
10
11
12
13

datasource:
  mysql:
    url: jdbc:mysql://localhost:3306/prod
    username: prod_user
    password: prod_password
    # 集合配置
    connection-properties:
      - characterEncoding=utf8
      - useSSL=false
    # 嵌套对象配置
    pool-options:
      max-active: 20
      min-idle: 5

Java 代码: src/main/java/com/example/demo/config/MySQLProperties.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

package com.example.demo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.List;

@Data // 必须提供 Getter/Setter，否则无法绑定
@Component // 方式一：直接声明为 Component
// 关键：将此类与配置文件中 "datasource.mysql" 为前缀的属性进行绑定
@ConfigurationProperties(prefix = "datasource.mysql")
public class MySQLProperties {
    
    private String url;
    private String username;
    private String password;
    
    // 对应 YAML 中的列表
    // 属性名 connection-properties 自动映射为 connectionProperties (松散绑定)
    private List<String> connectionProperties; 
    
    // 对应 YAML 中的嵌套对象
    private PoolOptions poolOptions;           

    @Data
    public static class PoolOptions { // 内部静态类用于映射嵌套对象
        private int maxActive;
        private int minIdle;
    }
}

6.3.3. 启用属性类的两种方式：@Component vs @EnableConfigurationProperties

这是一个容易混淆的知识点。我们定义了 Properties 类，但这还不够，我们需要让 Spring 容器“知道”并“接管”它。

方案一：使用 @Component (简单、直接)

如上节代码所示，直接在属性类上添加 @Component 注解。

• 优点: 简单，自包含。
• 缺点: 属性类与 Spring 框架的 @Component 注解耦合。

方案二：使用 @EnableConfigurationProperties (集中、解耦)

如果这个属性类是 第三方库提供的（我们无法修改源码添加 @Component），或者我们希望 集中管理 所有的配置类，可以使用这种方式。

第一步：移除 MySQLProperties 上的 @Component。

1
2
3

@Data
@ConfigurationProperties(prefix = "datasource.mysql")
public class MySQLProperties { ... }

第二步：在配置类（如启动类或专门的 Config 类）上激活它。

1
2
3
4
5

@Configuration
// 明确告诉 Spring Boot 去激活并注册 MySQLProperties.class
@EnableConfigurationProperties(MySQLProperties.class)
public class AppConfig {
}

6.4. 多环境配置管理 (Profiles)

“痛点”场景:

我们的应用即将上线。开发环境用的是本地数据库，测试环境用的是测试库，而生产环境则需要连接生产主库。难道我们每次部署到不同环境，都要手动去修改 application.yml 里的数据库连接信息吗？

解决方案:
Spring Profiles 允许我们为不同的环境创建各自独立的配置文件，在应用启动时，只需通过一个简单的开关，就能激活指定环境的配置。

6.4.1. [实践] application-{profile}.yml 的约定

Spring Boot 约定，特定环境的配置文件命名格式为 application-{profile}.yml。

1. application.yml: 主配置文件，存放所有环境共享的配置，并指定默认激活的环境。
2. application-dev.yml: 开发环境 配置。
3. application-prod.yml: 生产环境 配置。

文件: application.yml

1
2
3
4
5

spring:
  application:
    name: my-app # 共享配置
  profiles:
    active: dev  # 默认激活 dev

文件: application-dev.yml

1
2
3
4

server:
  port: 8080
app:
  env: Development

文件: application-prod.yml

1
2
3
4

server:
  port: 80
app:
  env: Production

6.4.2. [实践] 激活特定 Profile

方式一：在主配置文件中指定 (开发默认)

如上所示，在 application.yml 中设置 spring.profiles.active=dev。

方式二：通过命令行参数 (生产部署首选)

这是 优先级更高 的方式。它可以在不修改任何打包文件的情况下，在启动时动态指定环境。

1
2

# 激活生产环境配置来启动应用
java -jar my-app.jar --spring.profiles.active=prod

当执行上述命令时，Spring Boot 会先加载 application.yml，然后加载 application-prod.yml，后者会覆盖前者的同名配置（例如端口变为 80）。

6.5. 本章总结与配置速查

摘要回顾
本章我们构建了 Spring Boot 应用的“神经系统”——配置。我们明确了配置加载的优先级（命令行 > 外部 > 内部），掌握了 YAML 语法的精髓，学会了用 @ConfigurationProperties 优雅地管理复杂配置，并利用 Profiles 实现了“一次打包，处处运行”的多环境部署能力。

遇到以下 3 种配置场景时，请直接参考下方的代码模版：

1. 场景一：读取简单的开关/字符串配置

需求：读取配置文件中的 app.feature.enabled 开关。
方案：使用 @Value。
代码：

1
2
3
4
5
6

@Component
public class FeatureFlags {
    // 冒号后是默认值，防止配置缺失报错
    @Value("${app.feature.enabled:false}")
    private boolean isFeatureEnabled;
}

2. 场景二：读取结构化的业务配置

需求：配置微信支付的 appid, secret, mchid 等一组相关参数。
方案：使用 @ConfigurationProperties。
代码：

1
2
3
4
5
6
7
8

@Data
@Component
@ConfigurationProperties(prefix = "wechat.pay")
public class WechatPayProperties {
    private String appId;
    private String secret;
    private String mchId;
}

3. 场景三：生产环境临时覆盖配置

需求：线上数据库密码变更，不能重新打包，需要立即生效。
方案：使用命令行参数启动。
代码：

1

java -jar app.jar --spring.datasource.password=NewSecurePassword!

4. 核心避坑指南

1. YAML 缩进地狱

   • 现象：启动报错 ScannerException: mapping values are not allowed here。
   • 原因：YAML 格式错误，通常是因为冒号后面 少了一个空格，或者使用了 Tab 键缩进。
   • 对策：检查冒号后是否有空格；使用 IDE 的格式化功能。

2. @Value 注入失败 (static/final)

   • 现象：字段值为 null 或 0，配置未生效。
   • 原因：将 @Value 用在了 static 或 final 字段上。Spring 依赖注入是基于对象实例的，不支持静态注入。
   • 对策：移除 static 关键字；如果必须给静态变量赋值，请将 @Value 放在 setter 方法上。

3. 配置提示失效

   • 现象：在 application.yml 中写自定义配置时，IDE 没有自动补全提示。
   • 原因：缺少处理器的依赖。
   • 对策：在 pom.xml 中添加 spring-boot-configuration-processor 依赖。