跳到主要内容
约 7 分钟2 张卡

Spring Boot 外部化配置

外部化配置是把端口、数据库地址、超时等运行参数放在代码之外,让同一份应用在不同环境中使用不同的值。Spring Boot 会统一读取配置文件、环境变量和启动参数,再按优先级决定最终取值。理解这些规则,才能解释为什么改了文件却没生效,以及属性已经改变时,客户端是否还在使用旧配置。本文以 Boot 3.5 为准。

1. 面试核心​

先记住这几条,再读正文
  • Spring Boot 将配置来源放入 Environment,同名属性取优先级较高的 PropertySource 中的值。卡 · Environment 与 PropertySource
  • 在命令行、Java 系统属性、环境变量和配置数据这四类来源中,前者的优先级依次高于后者。
  • 同一位置中,profile 专属文件优先于默认文件;对应配置同时有 properties 和 YAML 两种格式时,properties 优先。
  • 属性名转为环境变量名时,点改成下划线、删除连字符、字母转为大写,例如 max-attempts 对应 MAXATTEMPTS。
  • 多个来源共同绑定配置时,List 整体替换,Map 按键合并,Map 的同名键取高优先级值。卡 · 集合覆盖与配置刷新

2. Environment 与 PropertySource​

Environment 是应用读取配置的统一入口,PropertySource 表示一份配置来源,例如环境变量或某个配置文件。容器将这些来源按优先级排列,读取属性时查找优先级最高的有效值。业务代码因此可以只关心属性名,不必自己决定先读文件还是先读环境变量。

读取配置主要有三种方式:注入单个属性、通过 Environment 查询,以及把一组属性绑定成对象。下面三个片段分别对应这三种用法:

@Value("${payment.timeout}")
Duration timeout;

environment.getProperty("payment.timeout", Duration.class);

@ConfigurationProperties("payment")
public record PaymentProperties(URI endpoint, Duration timeout) {}
  • @Value 把单个配置值注入字段,适合少量属性。它支持 ${...} 占位符,也支持 Spring 表达式语言 SpEL。
  • Environment.getProperty 按属性名直接查询,并将结果转换为指定类型。示例将超时值转换为 Duration。
  • @ConfigurationProperties 将一组相关属性绑定成对象。示例把 payment 下的地址与超时放进 PaymentProperties。

@ConfigurationProperties 支持宽松命名、类型转换和 Bean Validation 校验。宽松命名允许不同来源用不同形式表达同一个属性,例如环境变量 SERVER_PORT 对应 server.port。配合配置处理器,还能生成供编辑器提示属性名和类型的元数据。把相关配置放在一个类中,也更容易看清这个组件需要哪些参数。

上面的 record 属性类需通过 @ConfigurationPropertiesScan 扫描,或通过 @EnableConfigurationProperties 注册。完成注册后,Boot 才会创建对象并绑定配置。

3. 配置来源的优先级​

同名属性以高优先级来源的值为准。下面列出排查时会用到的配置来源,按优先级从低到高排列,后面的值覆盖前面的同名值:

  1. SpringApplication.setDefaultProperties 设置默认值。
  2. application.* 等配置数据提供文件值。
  3. 操作系统环境变量覆盖文件值。
  4. Java 系统属性覆盖环境变量。
  5. SPRING_APPLICATION_JSON 提供内联 JSON 属性。
  6. 命令行参数提供更高优先级值。
  7. 测试属性可继续覆盖应用配置。

这里列出的是日常排查常用的层级,省略了 JNDI、Servlet 初始化参数等特定来源。比如,启动时可以通过命令行指定端口:

java -jar order.jar --server.port=9000

默认启用命令行属性时,这条命令将端口设为 9000,覆盖文件中的 server.port。如果实际值与预期不同,要查看 Environment 中该属性的最终来源。

4. 配置文件的加载顺序​

配置文件之间也会覆盖同名属性,文件位置和激活的 profile 都会影响结果。profile 是按名称启用的一组配置,例如激活 prod 会加载 application-prod.yaml。默认加载的四类文件按以下顺序提高优先级:

  1. JAR 内默认配置提供基础值。
  2. JAR 内 profile 配置覆盖内部默认值。
  3. JAR 外默认配置覆盖 JAR 内配置。
  4. JAR 外 profile 配置覆盖外部默认值。

多个 profile 同时激活时,后声明的 profile 覆盖前面的同名值。同一位置的对应配置同时存在 properties 和 YAML 两种格式时,properties 优先。项目统一使用一种格式,可以减少同目录内不易察觉的覆盖。

spring.config.import 导入的配置会在声明它的文档之后处理,因此可覆盖该文档中的值。列出多个导入位置时,后面位置的同名值优先。

spring.config.location 会替换默认搜索位置,spring.config.additional-location 则追加位置。如果只是想增加一份外部配置,却误用了前者,原本依赖的默认位置就不会再被搜索。在位置前加 optional:,表示资源缺失时仍允许启动。

5. 环境变量的宽松绑定​

环境变量名受操作系统和启动工具的命名规则限制,部署时常使用大写下划线形式。将属性名转换为环境变量名,要依次完成以下命名转换:

  1. 将点替换为下划线。
  2. 删除连字符。
  3. 将字母转为大写。

例如,下面的属性名对应第二行的环境变量名:

payment.retry.max-attempts
PAYMENT_RETRY_MAXATTEMPTS

示例中的连字符被删除,所以 MAXATTEMPTS 连写。绑定列表元素时,下标需使用下划线包围数字,例如 MY_SERVICE_0_OTHER。

占位符使用小写 kebab-case,也就是用连字符分隔单词,例如 ${payment.retry.max-attempts}。这样,Boot 才能按规范名称匹配其他命名形式。复杂 Map 与集合通过环境变量表达时较难阅读,可改用配置文件、配置树或平台提供的配置功能。

6. 配置与密钥​

数据库密码、访问令牌和私钥应通过平台 Secret 或外部密钥服务提供,避免提交到仓库。Secret 是部署平台保存并向应用提供敏感配置的机制。

平台也可以将密钥挂载成文件,再用配置树读取。配置树是把目录中的文件名作为属性名、文件内容作为属性值的一种配置来源。挂载目录可用 spring.config.import=optional:configtree:/run/secrets/ 导入。

环境变量和文件都需要访问控制。环境变量也会出现在进程诊断、部署清单或错误报告中,所以仅更换存放位置并不足以保护密钥。Actuator、日志和错误页应限制暴露范围,展示配置时只保留必要来源信息,并对敏感值脱敏。

7. 启动配置校验​

关键配置应在启动时验证,让错误直接指向具体属性。比如缺少支付地址时就拒绝启动,可以避免等到第一笔支付才因空值失败。下面用 @Validated 启用配置校验,并在构造器中检查超时范围:

@ConfigurationProperties("payment")
@Validated
public record PaymentProperties(
@NotNull URI endpoint,
@NotNull Duration timeout) {
public PaymentProperties {
if (timeout != null && (timeout.isZero() || timeout.isNegative())) {
throw new IllegalArgumentException("payment.timeout must be positive");
}
}
}

示例中的 @NotNull 拒绝缺失的地址和超时,构造器拒绝零或负数超时。项目需注册属性类,并提供 Bean Validation 实现,也就是实际执行校验注解的组件。

除了单个字段是否存在,还要检查容量与业务开关的取值范围,以及配置之间的组合关系。生产关键参数的默认值应当安全、含义稳定,并适用于所有未显式配置的环境。这样,遗漏配置时才不会悄悄启用错误行为。

Duration 表示时间长度,支持 500ms、2s 等带单位的配置值。裸数字默认按毫秒绑定,可用 @DurationUnit 改变单位。因此,配置说明应明确单位和合理范围,减少部署时的误填。

8. 配置来源诊断​

配置改了却没生效,要分别确认两个结果:Environment 最终读到了什么,组件绑定并使用的又是什么。可以按下面的顺序排查:

  1. 确认实际读取的规范属性名。
  2. 查看激活的 profile 与搜索位置。
  3. 区分 spring.config.location 与 spring.config.additional-location。
  4. 通过 Actuator 的 env 查看属性来源,通过 configprops 查看配置对象的绑定结果。
  5. 检查部署环境中的同名变量、系统属性与命令行参数。
  6. 对敏感值仅确认来源和是否存在,避免输出明文。

9. 集合覆盖与配置刷新​

List 按整个列表替换,Map 按键合并,所以高优先级配置没写出的部分,结果可能不同。下面用 prod 配置同时覆盖一个列表和一个 Map:

payment:
servers: [a, b]
limits:
read: 10
write: 5
---
spring:
config:
activate:
on-profile: prod
payment:
servers: [c]
limits:
read: 20

假设 servers 绑定 List,limits 绑定 Map。激活 prod 后,列表变成 [c],原来的 a、b 被整体替换。Map 中的 read 更新为 20,write 仍为 5。也就是说,相同键取高优先级值,其余键继续保留。

普通 Boot 配置在创建 Bean 时绑定,修改磁盘文件不会自动更新已有 Bean。动态刷新需要额外机制,还要明确哪些组件能重新绑定或重建。例如,客户端构造时复制了一份超时值,之后只更新 PaymentProperties,客户端保存的旧值仍然不会改变。

10. 面试题卡片​

先想答案,再翻面先在心里答一遍,再点开卡片对照参考回答。卡片之间可以左右切换,看完会回到这里。
逐张翻看 2 张 →
未标记的卡读完后明天进入复习;已标记的按状态安排

11. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明