1. 从一次线上事故说起为什么配置这件事值得单独开一篇前阵子帮一个朋友排查他那个小项目的线上问题现象很典型本地跑得好好的一打包扔到服务器上数据库连接池直接爆了日志里全是连接超时的报错。他第一反应是代码写错了查了半天业务逻辑最后发现是配置文件里一个max-active的值在本地和线上走了两套不同的来源线上那份配置压根没生效。这种事儿在 Spring Boot 项目里太常见了配置这东西平时不起眼一旦出问题就是连锁反应。Spring Boot 最核心的卖点之一就是约定优于配置但这句话经常被误解成不需要配置。实际上它只是把大量重复的、模板化的配置项收敛到了默认值里真正涉及业务差异的部分还是得你自己动手。而且 Spring Boot 的配置体系相当庞大application.properties、application.yml、多环境 profile、命令行参数、环境变量、外部配置文件、配置中心……这些来源之间还有优先级关系搞不清楚就很容易踩坑。这篇内容我打算把 Spring Boot 的配置体系从头到尾捋一遍重点讲清楚三件事配置文件到底该怎么组织、不同来源的配置谁覆盖谁、以及实际项目里那些容易翻车的地方。适合已经能跑起来一个 Spring Boot 项目、但对配置管理还是一知半解的同学也适合想把自己项目配置结构重新梳理一遍的老手。看完你至少能做到知道配置从哪来、知道为什么没生效、知道怎么改才不出事。2. 配置文件格式选型properties 还是 yml别纠结太久2.1 两种格式的本质差异Spring Boot 支持两种主流配置文件格式.properties和.yml或者.yaml。很多人一上来就纠结选哪个其实这俩在功能上几乎等价Spring Boot 内部都会解析成同一套Environment抽象。真正的差异在于表达能力和可读性。.properties是键值对平铺结构每一行一个配置键用点号分隔层级server.port8080 spring.datasource.urljdbc:mysql://localhost:3306/demo spring.datasource.usernameroot spring.datasource.password123456.yml是缩进式的树形结构层级关系靠缩进表达server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: 123456从信息密度上看yml 明显更紧凑尤其是配置项多的时候不用反复写前缀。但 yml 有个致命问题缩进敏感。用 Tab 还是空格、缩进几格稍有不慎就解析失败而且报错信息往往不直观。我见过不少新手在这上面浪费半小时。2.2 我的实际选择建议我的建议是新项目一律用 yml老项目维护保持原格式。理由有三点。第一yml 的树形结构天然适合表达嵌套配置像数据源、缓存、消息队列这种多层配置读起来一目了然。第二yml 支持列表和复杂对象比如你要配多个数据源或者一组拦截器规则properties 写起来会非常别扭。第三现在主流 IDE 对 yml 的支持已经很完善缩进错误基本能实时提示。但有几个坑必须提前说。yml 里冒号后面必须跟一个空格port:8080是错的得写port: 8080。字符串值如果包含特殊字符最好用引号包起来比如密码里有或者#不加引号可能被当成注释或者解析异常。还有yml 不支持开头的占位符直接写在值里得配合引号。提示如果你团队里有人对缩进特别不敏感或者项目需要频繁用脚本批量修改配置properties 反而更稳妥因为它是纯文本行结构正则替换不容易出错。2.3 一个容易被忽略的细节编码问题.properties文件在 Spring Boot 2.x 之前默认用 ISO-8859-1 编码读取中文会乱码。虽然 2.x 之后改成了 UTF-8但如果你用的是老版本或者某些特殊环境还是可能遇到。yml 默认就是 UTF-8这方面省心一些。所以如果你的配置里有中文注释或者中文值优先选 yml。3. 配置加载顺序与优先级谁覆盖谁一张表说清楚3.1 配置来源的全景图Spring Boot 的配置来源非常多官方文档列了十几种但实际项目里常用的就那么几个。我按优先级从高到低排一下高优先级的会覆盖低优先级的优先级配置来源典型场景1命令行参数临时调试、容器启动传参2环境变量容器化部署、CI/CD 注入3外部 config 目录下的配置文件运维统一管理配置4外部当前目录下的配置文件本地覆盖测试5jar 包内 config 目录下的配置文件打包时内置6jar 包内根目录下的配置文件默认配置7PropertySource注解自定义配置类8默认属性Spring Boot 内置默认值这个顺序不是让你背的而是让你在排查为什么我的配置没生效时有个方向。比如你在application.yml里改了端口但启动还是 8080那大概率是命令行或者环境变量里有更高优先级的配置把它覆盖了。3.2 profile 机制多环境配置的正确打开方式实际项目不可能只有一套配置开发、测试、生产环境的数据库地址、日志级别、第三方服务地址都不一样。Spring Boot 的 profile 机制就是干这个的。基本用法是准备多个文件application.yml放通用配置application-dev.yml放开发环境application-prod.yml放生产环境。然后在主配置里指定激活哪个spring: profiles: active: dev或者启动时用命令行指定java -jar demo.jar --spring.profiles.activeprod这里有个关键点profile 专属配置会覆盖主配置里的同名项但不会整体替换。也就是说application.yml里配了 10 个项application-prod.yml里只配了 2 个最终生效的是这 2 个覆盖后的值加上另外 8 个主配置的值。这个特性很有用通用配置不用重复写。3.3 多 profile 同时激活与优先级Spring Boot 支持同时激活多个 profile用逗号分隔spring: profiles: active: dev,debug这种情况下后激活的 profile 优先级更高。比如dev和debug都配了logging.level.root最终生效的是debug里的值。这个机制可以用来做配置分层比如common放基础配置dev放开发覆盖local放个人本地覆盖。注意profile 文件命名必须严格遵循application-{profile}.yml格式{profile}部分要和spring.profiles.active里的值完全一致大小写敏感。我见过有人写成application-Dev.yml然后激活dev死活不生效。3.4 配置覆盖的排查思路当你发现某个配置没按预期生效时按这个顺序查先看启动日志里有没有打印激活的 profile再看有没有命令行参数或环境变量覆盖然后检查外部 config 目录有没有同名文件最后确认配置项拼写和层级是否正确。Spring Boot 启动时会打印一部分配置信息但默认不打印全部可以通过开启debugtrue或者访问 actuator 的/env端点来看完整的配置来源。4. 配置项绑定从配置文件到 Java 对象的几种姿势4.1 Value简单直接但局限明显最基础的绑定方式是Value注解Component public class AppConfig { Value(${app.name}) private String name; Value(${app.timeout:3000}) private int timeout; }Value的优点是简单适合零散的一两个配置项。冒号后面是默认值当配置项不存在时使用。但它有几个硬伤不支持复杂对象绑定、不支持松散绑定比如app-name和appName不能自动对应、每个字段都要写一遍注解配置项多了很啰嗦。4.2 ConfigurationProperties复杂配置的首选当配置项成组出现时ConfigurationProperties是更好的选择Component ConfigurationProperties(prefix app) public class AppProperties { private String name; private int timeout 3000; private Datasource datasource new Datasource(); public static class Datasource { private String url; private String username; // getter/setter 省略 } // getter/setter 省略 }对应的 ymlapp: name: demo timeout: 5000 datasource: url: jdbc:mysql://localhost:3306/demo username: root这种方式的好处很明显类型安全、支持嵌套对象、支持松散绑定、IDE 能自动补全。而且配合spring-boot-configuration-processor依赖编译时还能生成配置元数据IDE 里写 yml 会有提示。4.3 松散绑定规则详解Spring Boot 的松散绑定是个很实用的特性它允许配置文件的命名风格和 Java 字段命名风格不一致。比如下面这些写法都能绑定到appName字段app: appName: demo app-name: demo app_name: demo APP_NAME: demo这个特性在环境变量场景下特别有用因为环境变量通常是大写下划线风格。但要注意Value不支持松散绑定只有ConfigurationProperties支持。这也是我推荐复杂配置用后者的原因之一。4.4 配置校验别等到运行时才发现配错了ConfigurationProperties可以配合 JSR-303 校验注解使用Component ConfigurationProperties(prefix app) Validated public class AppProperties { NotBlank private String name; Min(1000) Max(60000) private int timeout; }这样在启动时就会校验配置配错了直接启动失败而不是等到运行时才报错。对于生产环境来说早失败比晚失败好得多。我一般会在关键配置上加校验尤其是那些配错了会导致严重问题的项比如连接池大小、超时时间。5. 外部化配置与动态刷新让配置脱离代码5.1 外部配置文件的加载位置Spring Boot 默认会从四个位置加载外部配置优先级从高到低./config/当前目录下的 config 子目录./当前目录classpath:/config/类路径下的 config 目录classpath:/类路径根目录这个机制的意义在于你打包时可以把默认配置放在 jar 内部署时在 jar 同级目录放一个config/application.yml覆盖它不用重新打包。运维改配置只需要改外部文件重启即可。5.2 自定义配置文件位置如果默认位置不满足需求可以通过命令行指定java -jar demo.jar --spring.config.locationfile:/etc/myapp/或者用spring.config.additional-location追加位置而不替换默认位置。这两个参数的区别要搞清楚location是替换additional-location是追加。用错了会导致默认配置丢失。5.3 配置加密与敏感信息处理配置文件里最头疼的是密码、密钥这类敏感信息。直接明文写在 yml 里肯定不行尤其是代码要进版本库的时候。常见的处理方式有几种第一种是用环境变量注入配置文件里只写占位符spring: datasource: password: ${DB_PASSWORD}第二种是用配置中心把敏感配置放在独立的配置服务里应用启动时拉取。第三种是用加密工具对配置值加密运行时解密。第一种最简单适合中小项目第二种适合微服务架构第三种实现成本较高但安全性最好。提示不管用哪种方式都别把生产环境的密码提交到代码仓库。我见过太多项目在.gitignore里漏掉了application-prod.yml结果密码直接泄露。5.4 动态刷新配置标准 Spring Boot 应用启动后配置就固定了改配置需要重启。如果不想重启可以引入配置中心组件配合RefreshScope注解实现动态刷新。原理是配置中心推送变更事件应用接收到后重新绑定RefreshScope标注的 Bean。但动态刷新不是没有代价的。首先它增加了架构复杂度其次不是所有配置都适合动态刷新比如数据源连接池的核心参数刷新了反而可能出问题。我的经验是日志级别、开关类配置、限流阈值这类适合动态刷新数据库连接、端口、线程池核心参数这类还是重启稳妥。6. 常见配置问题排查实录6.1 配置不生效的排查清单配置不生效是最高频的问题我整理了一个排查顺序排查项检查方法常见原因profile 是否正确看启动日志激活的 profile 和预期不符配置项拼写对照配置类字段大小写、连字符错误配置来源优先级查环境变量、命令行被更高优先级覆盖文件位置确认加载路径外部文件没放对目录格式错误看启动日志yml 缩进、properties 编码缓存问题清理 target 重新编译旧配置残留6.2 yml 解析失败的典型场景yml 解析失败最常见的原因是缩进。比如下面这段spring: datasource: url: jdbc:mysql://localhost:3306/demo username: rooturl的缩进和datasource同级了导致url被解析成spring的直接子项而不是datasource的子项。这种错误不会报语法错误但绑定会失败排查起来很费劲。我的建议是写完 yml 后用在线校验工具过一遍或者依赖 IDE 的实时检查。另一个坑是特殊字符。比如密码里有#不加引号会被当成注释password: abc#123实际生效的密码是abc#123被忽略了。正确写法是password: abc#123。6.3 环境变量覆盖导致的诡异问题容器化部署时环境变量经常是配置覆盖的隐形杀手。比如你在 yml 里配了server.port8080但容器编排文件里注入了SERVER_PORT9090最终生效的是 9090。因为环境变量的优先级高于 jar 内配置文件。排查这类问题的关键是启动时打印完整的配置来源。可以开启 actuator 的/env端点或者启动参数加--debug能看到哪些配置被覆盖了。我一般会在测试环境保留这个能力生产环境关掉。6.4 配置类不生效的几种情况ConfigurationProperties类不生效常见原因有类没有被 Spring 扫描到不在启动类包路径下、缺少Component或EnableConfigurationProperties、setter 方法缺失Spring Boot 2.x 之后支持构造器绑定但字段绑定还是需要 setter。还有一种情况是配置项前缀写错了比如类上写prefix app但 yml 里写的是apps那自然绑不上。7. 一些实战中的配置组织经验7.1 配置文件拆分策略项目大了之后把所有配置堆在一个application.yml里会很难维护。我的做法是按功能模块拆分比如application-datasource.yml、application-redis.yml、application-mq.yml然后在主配置里用spring.profiles.include引入spring: profiles: include: datasource,redis,mq这样每个模块的配置独立管理改数据源不用翻整个文件。但要注意include的 profile 优先级低于active的 profile如果两者有同名配置active的会赢。7.2 配置项命名规范配置项的命名最好遵循一定规范我的习惯是前缀用项目名或模块名中间用功能分类最后是具体项。比如myapp.order.timeout、myapp.user.cache-ttl。避免用config1、param2这种无意义命名。另外布尔类型的配置项用enabled、disabled这种明确的后缀别用isOpen这种模棱两可的。7.3 默认值的设计原则配置项该不该给默认值我的判断标准是这个配置在绝大多数场景下是否有一个合理值。如果有就给默认值让使用者不配也能跑如果没有就不给强制使用者显式配置避免用错。比如日志级别默认INFO是合理的但数据库地址没有合理默认值必须让使用者配。7.4 配置文档化配置项多了之后最好生成一份配置说明文档。spring-boot-configuration-processor可以自动生成元数据配合一些工具能导出成文档。或者至少在配置类上写清楚每个字段的含义和默认值。我见过太多项目配置项只有写的人知道什么意思换个人接手就得一个个猜。8. 关于配置这件事我踩过的几个坑第一个坑是 profile 文件命名。早期我写过application-dev.yml和application-dev.properties两个文件以为会合并结果 properties 的优先级更高把 yml 里的配置覆盖了。后来才知道同名的不同格式文件properties 优先。所以别混用格式一个项目统一一种。第二个坑是Value的默认值语法。Value(${app.timeout:3000})里冒号后面不能有空格写成${app.timeout: 3000}会把空格也当成默认值的一部分然后类型转换失败。这个细节文档里没强调但实际很容易写错。第三个坑是配置刷新。有次在项目里用了动态刷新结果某个配置项刷新后没生效查了半天发现那个 Bean 没有加RefreshScope。动态刷新只对标注了该注解的 Bean 生效不是全局的。这个认知偏差让我多花了一个下午。第四个坑是环境变量的大小写。Linux 环境变量是大写敏感的但 Spring Boot 的松散绑定会把APP_NAME映射到app.name。不过如果环境变量名里有下划线映射规则是下划线转点号还是转连字符不同版本行为略有差异。稳妥的做法是环境变量名和配置项名保持一致的语义别依赖自动转换。配置管理这件事说到底是约定和显式之间的平衡。Spring Boot 给了很多默认约定让项目能快速跑起来但真正要上线稳定运行还是得把关键配置显式管理好。我的原则是能默认的默认该显式的显式敏感信息绝不进代码库配置变更要有记录可追溯。这套东西理顺了后面排查问题能省一半时间。
