Spring Boot 3.x升级实战：自动装配原理与配置排查指南

上个月我升级一个老项目Spring Boot从2.3直接跳到3.x启动倒是顺利页面也正常但自定义的Redis序列化器、定时任务一个都没生效。排查了半个下午才意识到问题出在“自动装配”这几个字上——它不只是跳过了配置文件连配置入口都搬了家。这篇东西不是Spring Boot手册不会把所有注解和配置罗列一遍我只把这些年真正让我花过时间的地方拉出来讲透从自动装配原理到配置细节再到事务、文件存储、接口安全和Docker部署新手照着走能少踩很多坑老手也能拿它当一次系统复盘。1. 从自动装配说起SpringBoot凭什么不用写配置1.1 一个注解背后是三个注解很多初级开发看到启动类上只有一个SpringBootApplication就以为Spring Boot的启动逻辑全在这一个注解里。实际上这个注解是个组合注解它约等于下面三个注解同时生效SpringBootConfiguration本质上是Configuration标记这是一个配置类。EnableAutoConfiguration自动装配的入口把需要的一系列配置类自动导入容器。ComponentScan默认扫描启动类所在包及其子包下的Component、Service、Repository、Controller等组件。这里最容易出问题的是ComponentScan。默认扫描范围是启动类所在包及子包如果你把某个Service放在包外面Spring无论如何都不会扫到它运行时不报错但一调用就报NoSuchBeanDefinitionException。我见过好几次这种低级问题排查方式很简单看看报错类的包名和启动类的包名是不是同一个根路径。SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }这个启动类本身也是一个配置类很多自动配置类需要读取容器里的Bean时会去拿ApplicationContext而启动类所在的包路径直接决定了扫描范围所以尽量别把启动类放在一个裸包下面最好是com.公司名.项目名这种层级。1.2 自动配置装载链路从spring.factories到AutoConfiguration.importsEnableAutoConfiguration这个注解点进去核心是Import(AutoConfigurationImportSelector.class)。AutoConfigurationImportSelector的作用是去查一批配置类的名单把这些配置类导入容器让它们按条件决定是否生效。名单存在哪里这是版本变化里最坑的地方Spring Boot 2.7之前配置类的全限定名写在META-INF/spring.factories文件中key是org.springframework.boot.autoconfigure.EnableAutoConfiguration。Spring Boot 2.7开始引入新文件META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports并建议新组件用新格式。Spring Boot 3.0直接移除了对spring.factories的支持如果你的自定义starter还是在老文件里写自动配置升级后代码不报错但功能就是没有日志里连个警告都不一定看得到。所以热词里那个“spring boot版本太高”带来的诡异问题一大半都是这个原因。排查思路很简单先确认你用的自动配置类有没有被加载。最简单的方法是在application.yml里加debug: true启动时控制台会打出Positive matches、Negative matches和Exclusions列表一目了然。Positive matches: RedisAutoConfiguration matched: - ConditionalOnClass found required classes org.springframework.data.redis.core.RedisOperations Negative matches: MyCustomAutoConfiguration: Did not match: - ConditionalOnClass found required class com.xxx.SomeClass (OnClassCondition)1.3 条件注解配置之所以“自动”是因为它先判断“需不需要”自动配置类不是一个无脑全部生效的集合每个配置类上面都有大量的Conditional系列注解决定这个配置类在什么条件下才创建对应的Bean。这也是自动装配原理里最值得展开的部分面试问到Spring Boot基本原理八成会落在这些注解上。常用条件注解有这么几个注解判断逻辑典型使用场景ConditionalOnClass类路径下是否存在某个类只有引入相关依赖才加载自动配置ConditionalOnMissingBean容器中是否不存在某个Bean你自定义了Bean就覆盖默认配置ConditionalOnProperty配置文件中某个属性是否匹配按开关控制配置是否生效ConditionalOnWebApplication当前是否为Web项目区分Web和普通应用场景举个最实际的例子RedisAutoConfiguration上标了ConditionalOnClass(RedisOperations.class)也就是说你没引入spring-boot-starter-data-redis类路径下根本没有Redis相关类这个自动配置直接跳过。再比如你自己定义了一个RedisTemplateString, ObjectConditionalOnMissingBean发现容器里已经有这个Bean了Spring Boot默认提供的那套RedisTemplate就不会注册避免覆盖你的定制化配置。这个机制也解释了为什么自动配置可以“自动”得恰到好处它不是盲目给容器塞东西而是根据类路径、已有Bean、配置项精密地计算出一份适合当前项目的最终配置清单。1.4 排查自动配置不生效的实战方法在Spring Boot 2.7之后自定义一个starter标准动作是在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里写入自动配置类全限定名然后在配置类上用条件注解控制生效范围。AutoConfiguration ConditionalOnClass(MyService.class) EnableConfigurationProperties(MyProperties.class) public class MyAutoConfiguration { Bean ConditionalOnMissingBean public MyService myService() { return new MyService(); } }如果配置不生效除了debug: true看自动配置报告还可以做两个检查第一个是依赖有没有真的引入很多人只写了代码忘了在pom.xml加依赖ConditionalOnClass直接不满足第二个是配置文件里的开关属性名是否写对ConditionalOnProperty要求完全匹配多一个字母少一个字母都会导致整个配置类不加载。还有一个我自己踩过的坑自动配置类上的包名和组件扫描的根包不能一样否则会被ComponentScan提前扫到导致配置类当成普通Bean强行加载条件注解失效。很多老手也容易栽在这里所以写自动配置类时包名一般放在com.公司名.autoconfigure这类独立位置。2. 配置细节banner、多环境、资源映射与密码加密2.1 banner一个一眼就能看出的团队细节Spring Boot启动时那个打印出来的字符画很多人觉得只是好玩其实它是个很实用的团队标识。团队内部统一风格之后某个人启动日志截图发到群里大家一眼能看出是哪个项目省去很多沟通成本。网上搜“spring boot banner生成器”把文字丢进去就能生成一个ASCII艺术字复制到resources/banner.txt里下次启动自动替换默认图案。想关掉banner也很简单spring: main: banner-mode: off注意一个小坑Windows下用记事本保存banner.txt可能会带BOM头导致启动时代码打印出乱码。保存时务必选UTF-8无BOM编码IDEA默认没问题但用其他编辑器要留个心眼。2.2 IDEA里application.yml不提示怎么办热词里专门有一条“idea中springboot项目的application.yml不提示怎么办”这个问题太常见了。IDEA打开yml文件发现一点提示没有输入配置项全靠手打极大影响效率。我通常按顺序排查三件事第一自定义配置类没有加入依赖。如果想让application.yml识别你自己的ConfigurationProperties(prefix file)前缀必须在pom.xml里加上dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-configuration-processor/artifactId optionaltrue/optional /dependency加上之后重新编译一次IDEA就会把你自定义前缀的属性也纳入提示。第二src/main/resources目录没被标记成资源目录。Maven项目中可以右键目录选择Mark Directory as - Resources Root。如果没有这一步application.yml对IDE来说只是普通文件自然没有配置提示。第三IDEA的Spring插件没启用。在Settings - Plugins里确认已经安装并启用了Spring Boot相关插件有时候IDEA更新后插件会默认关闭。2.3 多环境配置与外部化优先级一个项目通常有开发、测试、生产三套环境如果全都写在一个application.yml里每次发布前都要手动改配置迟早会出错。我的习惯是拆成三个文件application-dev.yml、application-test.yml、application-prod.yml然后在application.yml里只保留公共配置和一个激活开关spring: profiles: active: dev不过生产环境不要把这行写死建议用启动参数指定java -jar app.jar --spring.profiles.activeprod这里还涉及Spring Boot的外部化配置优先级。同一项配置在多个地方都设置了值最终生效的是优先级高的那个。从高到低大致是优先级配置来源高命令行参数高Java系统属性-D参数高操作系统环境变量中application-{profile}.yml低application.yml低jar包外面的配置文件所以你在启动脚本里用--server.port8081覆盖掉application-prod.yml里的server.port是可行的而且不用改任何文件这对运维很友好。我之前遇到一个案例开发在本地改了application.yml里的数据库地址启动后还是连到测试库查了半天就是环境变量里设了SPRING_DATASOURCE_URL环境变量优先级高于jar内配置这个底层逻辑不搞清楚很容易被“配置不生效”搞到怀疑人生。2.4 静态资源映射与微信域名校验文件Spring Boot默认会从classpath:/static/、classpath:/public/、classpath:/resources/这些位置找静态资源但项目里经常需要把磁盘上的文件目录暴露成URL尤其是热词里提到的“spring boot项目配置微信域名文件认证”。微信公众号或小程序后台需要你上传一个校验文件通常是一个MP_verify_xxxxxxxx.txt要求通过http://你的域名/MP_verify_xxxxx.txt能访问到。如果这个文件放在服务器的磁盘目录而不是打包进jar就需要做资源映射。Configuration public class WebConfig implements WebMvcConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/upload/**) .addResourceLocations(file:/data/upload/); registry.addResourceHandler(/MP_verify_*.txt) .addResourceLocations(file:/alidata/cert/); } }注意addResourceLocations的值必须以/结尾否则映射不生效。另外很多同事会默认把上传文件放在项目运行目录下的static/里平时测试没问题一旦重启服务或重新部署文件就没了——因为spring boot启动时是从jar里读取静态资源而jar包里的目录是只读的。生产环境一定要把用户上传的文件放到项目外的独立目录再用上面的方式映射出来。2.5 数据库密码加密jasypt与自定义SM4配置文件里直接写数据库账号密码是很多项目里最显眼的安全隐患。代码仓库如果泄露数据库也跟着沦陷。通常的做法是引入jasypt-spring-boot-starter把密码加密成密文放在application.yml中运行时解密。dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency加密后的配置长这样spring: datasource: username: ENC(加密后的用户名) password: ENC(加密后的密码)jasypt默认使用的加密算法在某些企业合规场景下不一定满足要求比如热词里提到的“对数据库用户密码采用SM4的加密方式并且在jasyptStringEncryptor中”。解决方式是实现并注册一个自定义的StringEncryptorComponent(sm4StringEncryptor) public class Sm4StringEncryptor implements StringEncryptor { Override public String encrypt(String message) { // 使用SM4算法加密 return Sm4Util.encrypt(message); } Override public String decrypt(String encryptedMessage) { // 使用SM4算法解密 return Sm4Util.decrypt(encryptedMessage); } }然后在配置里指定用这个Beanjasypt: encryptor: bean: sm4StringEncryptor有一个必须提醒的点解密用的密钥不能继续放在application.yml里否则等于把保险柜钥匙放在保险柜旁边。正确做法是把密钥放到部署机器的环境变量里或者使用密钥管理服务应用启动时通过System.getenv()读取。3. 事务失效、循环依赖与单元测试写业务代码绕不开的三个坑3.1 一个Transactional没生效问题往往不在注解事务失效是Spring Boot开发里出现频率极高的疑难杂症。很多人的第一反应是“注解写错了”实际上注解本身大概率没问题问题出在调用链上。最常见的失效场景是同类内部自调用Service public class OrderService { public void createOrderAndNotify() { this.createOrder(); // 自调用绕过代理对象 } Transactional(rollbackFor Exception.class) public void createOrder() { // 写订单表 // 调用第三方接口 } }这里createOrderAndNotify直接调用this.createOrder()注意this是原始对象不是Spring生成的代理对象。事务是通过AOP动态代理实现的没有经过代理事务注解自然不生效。外层方法如果抛异常内层已经执行的数据库操作一样会提交。解决方式有几种把createOrder拆到另一个Bean里让它经过代理或者注入ApplicationContext通过ApplicationContext.getBean(OrderService.class).createOrder()调用还可以用AopContext.currentProxy()但前提是启动时需要设置spring.aop.expose-proxytrue副作用是对所有AOP都生效不推荐滥用。其余常见失效场景我也列一下Transactional标在非public方法上Spring AOP默认不增强非public方法。方法内部把异常用try...catch吞掉了事务感知不到异常自然无法回滚。方法抛出的异常是检查异常比如Exception的直接子类而Transactional默认只回滚RuntimeException和Error此时需要显式指定rollbackFor Exception.class。数据库表使用MyISAM引擎不支持事务这属于表结构问题经常被忽略。多数据源下事务管理器没切换到目标数据源导致操作的库和事务管理器管理的库不是一个。我的建议是团队里统一事务写法Transactional(rollbackFor Exception.class) public void doSomething() { // 业务逻辑 }3.2 循环依赖为什么升级到高版本直接启动失败循环依赖直觉上就是A依赖B、B依赖A。Spring容器理论上能通过三级缓存解决一部分循环依赖但Spring Boot 2.6版本后默认禁止循环依赖老项目升级后启动直接报错这也是热词“spring boot版本太高”相关的高频问题。报错信息长这样The dependencies of some of the beans in the application context form a cycle: ┌─────┐ | aService ↑ ↓ | bService └─────┘Spring的三级缓存机制允许setter注入或字段注入的Bean在循环依赖时延迟暴露解决大部分循环依赖问题。但构造器注入的循环依赖无法解决因为构造器阶段就要拿到依赖对象而这时候Bean还没创建完成。所以Spring Boot 2.6以后直接默认禁止从源头杜绝这种不健康的依赖关系。遇到这个问题的处理方式我建议按优先级排序重构代码把互相调用的逻辑抽到第三个Service里打破循环。在某个字段上加Lazy延迟注入代理对象等到真正调用时才解析目标Bean。临时在配置里开启spring.main.allow-circular-referencestrue这是应急手段不适合长期保留。从设计角度看业务层之间互相调用本身就该谨慎循环依赖往往意味着职责边界没划清楚。与其到处打补丁不如花点时间把依赖方向理直。3.3 单元测试别为了测一个Service把整个项目启动起来“单元测试”在热词里的热度很高说明很多人都意识到要写测试但大多数人只会用SpringBootTest。这个注解会启动完整的Spring容器加载所有配置、连接真实数据库和中间件跑一个简单Service方法可能耗时几十秒。更要命的是