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. 配置来源的优先级
同名属性以高优先级来源的值为准。下面列出排查时会用到的配置来源,按优先级从低到高排列,后面的值覆盖前面的同名值:
SpringApplication.setDefaultProperties设置默认值。application.*等配置数据提供文件值。- 操作系统环境变量覆盖文件值。
- Java 系统属性覆盖环境变量。
SPRING_APPLICATION_JSON提供内联 JSON 属性。- 命令行参数提供更高优先级值。
- 测试属性可继续覆盖应用配置。
这里列出的是日常排查常用的层级,省略了 JNDI、Servlet 初始化参数等特定来源。比如,启动时可以通过命令行指定端口:
java -jar order.jar --server.port=9000
默认启用命令行属性时,这条命令将端口设为 9000,覆盖文件中的 server.port。如果实际值与预期不同,要查看 Environment 中该属性的最终来源。
4. 配置文件的加载顺序
配置文件之间也会覆盖同名属性,文件位置和激活的 profile 都会影响结果。profile 是按名称启用的一组配置,例如激活 prod 会加载 application-prod.yaml。默认加载的四类文件按以下顺序提高优先级:
- JAR 内默认配置提供基础值。
- JAR 内 profile 配置覆盖内部默认值。
- JAR 外默认配置覆盖 JAR 内配置。
- JAR 外 profile 配置覆盖外部默认值。
多个 profile 同时激活时,后声明的 profile 覆盖前面的同名值。同一位置的对应配置同时存在 properties 和 YAML 两种格式时,properties 优先。项目统一使用一种格式,可以减少同目录内不易察觉的覆盖。
spring.config.import 导入的配置会在声明它的文档之后处理,因此可覆盖该文档中的值。列出多个导入位置时,后面位置的同名值优先。
spring.config.location 会替换默认搜索位置,spring.config.additional-location 则追加位置。如果只是想增加一份外部配置,却误用了前者,原本依赖的默认位置就不会再被搜索。在位置前加 optional:,表示资源缺失时仍允许启动。
5. 环境变量的宽松绑定
环境变量名受操作系统和启动工具的命名规则限制,部署时常使用大写下划线形式。将属性名转换为环境变量名,要依次完成以下命名转换:
- 将点替换为下划线。
- 删除连字符。
- 将字母转为大写。
例如,下面的属性名对应第二行的环境变量名:
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 最终读到了什么,组件绑定并使用的又是什么。可以按下面的顺序排查:
- 确认实际读取的规范属性名。
- 查看激活的 profile 与搜索位置。
- 区分
spring.config.location与spring.config.additional-location。 - 通过 Actuator 的
env查看属性来源,通过configprops查看配置对象的绑定结果。 - 检查部署环境中的同名变量、系统属性与命令行参数。
- 对敏感值仅确认来源和是否存在,避免输出明文。
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. 面试题卡片
11. 参考资料
- Spring Boot:Externalized Configuration
- Spring Boot:Type-safe Configuration Properties
- Spring Boot:Environment Endpoint
- Spring Boot 3.5:Externalized Configuration
来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明