干 Spring Boot 开发的这几年要说最让人又爱又恨的机制自动配置Auto Configuration绝对排第一。Spring Boot 的口号是“自动配置、开箱即用”它会在项目启动时扫描 classpath看到哪个库就自动把相关 Bean 初始化好。听起来很美好实际里却经常“聪明反被聪明误”项目里只是加了一个依赖启动时立刻多出一堆不需要的 Bean甚至直接报错。这种时候最需要的技能就是精准地排除自动配置。这篇我把自动配置的触发逻辑、几种排除姿势以及排查踩坑的经验一次讲清楚。不管你是刚接触 Spring Boot 的新人还是已经被生产环境自动配置折磨过一轮的同学都能找到能直接落地的方案。1. 自动配置的触发机制排除前你必须搞懂的底层逻辑1.1 自动配置的“侦察兵”和“开关机制”Spring Boot 之所以能“开箱即用”核心是启动类上的SpringBootApplication。这个注解其实是三个注解的组合Configuration、ComponentScan、EnableAutoConfiguration。真正干自动配置这件事的是最后一个EnableAutoConfiguration它会从 classpath 下加载一堆“自动配置类”作为候选。在 Spring Boot 2.6 及更早版本这些候选配置类注册在META-INF/spring.factories文件里key 是org.springframework.boot.autoconfigure.EnableAutoConfiguration。从 2.7 开始官方引入了一个新文件META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports到了 Spring Boot 3.x这个 imports 文件成为唯一标准spring.factories里的自动配置项已经不被处理了。但注意被注册到文件里只是进了“候选名单”不代表一定会生效。每个自动配置类上通常挂着一大堆条件注解最常见的包括ConditionalOnClassclasspath 存在某个类才生效、ConditionalOnMissingBean容器里不存在某个 Bean 才生效、ConditionalOnProperty配置了某个开关属性才生效。你可以把整个过程想象成家政服务候选名单是一套完整的服务清单家政人员先观察你家厨房classpath里有什么食材再决定做不做这道菜。比如RedisAutoConfiguration只有在 classpath 里存在RedisOperations类时才会被列入考虑然后还要检查容器里是不是已经有RedisTemplate或StringRedisTemplate如果都不存在它才会真正动手创建 Bean。这就是排除自动配置的第一条底层认知排除的本质是从“候选名单”里把某一个或某几个配置类直接划掉。它跟 classpath 上有没有这个依赖库没关系只是告诉 Spring Boot“这个自动配置你不要帮我执行”。1.2 为什么“智能”的自动配置会好心办坏事自动配置的触发条件通常只看“局部信息”某个类在不在、某个 Bean 有没有、某个属性配没配。但项目整体业务意图它并不了解所以不可避免地会“好心办坏事”。我总结了几类最常见的高频冲突场景。典型场景自动配置常见干扰多数据源项目DataSourceAutoConfiguration自动创建一个默认数据源跟自定义数据源打架仅仅引入 Redis 相关二方包RedisAutoConfiguration即使业务根本没连 Redis也会初始化连接工厂引入 Spring Security 做接入鉴权SecurityAutoConfiguration默认把所有请求都保护起来干扰监控端点访问测试环境引了全套 Spring Boot Starter各种 xxxAutoConfiguration启动变慢、上下文里多出一堆根本用不到的 Bean我在实际项目里印象最深的是多数据源。如果你只配了一个spring.datasource.urlSpring Boot 的DataSourceAutoConfiguration会很开心地帮你创建一个DataSource。可一旦你搞主库、报表库双数据源它那个“单数据源”的假设就崩了默认创建出来的 Bean 跟手动配置的数据源互相冲突启动日志里全是莫名其妙的错误。还有一次项目里只是引入了一个封装好的 Redis 工具包业务根本没打算用 Redis结果RedisAutoConfiguration直接把 RedisConnectionFactory 初始化了连不上 Redis 服务的时候整个服务启动都失败。这里要特别分清一个概念排除自动配置不等于删掉功能。你把DataSourceAutoConfiguration排除了classpath 上依然有各种数据库驱动和连接池依赖只是 Spring Boot 不再帮你自动创建那个“默认的数据源 Bean”。你完全可以自己写一个配置类来创建数据源甚至可以用Import精准导入某个内部配置类。这种“让出控制权再自己接管”的思路正是排除自动配置在大型项目里最核心的价值。2. 三种主流排除姿势与使用场景拆解2.1 启动类注解排除最直观、最常用最直接也是最常见的做法是在启动类的SpringBootApplication注解上直接加exclude属性SpringBootApplication(exclude { DataSourceAutoConfiguration.class, RedisAutoConfiguration.class }) public class MyApplication { public static void main(String[] args) { SpringApplication.run(MyApplication.class, args); } }写的时候注意这里写的是自动配置类的Class对象不是普通配置类。我在项目里见过有人把DataSourceConfig这种自己定义的配置类塞进exclude结果一天都在怀疑 Spring Boot 是不是有 Bug——其实exclude只针对被EnableAutoConfiguration加载的自动配置普通Configuration类跟它压根不是一个通道排了自然不生效。如果你的自动配置类不在当前模块的编译依赖里不想硬编码Class导致编译报错可以用excludeName属性SpringBootApplication(excludeName { org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration }) public class MyApplication { // ... }excludeName接收的是类的全限定名字符串适合“知道类名但不想直接依赖这个类”的场景。不过日常开发我更推荐直接写Class因为 IDE 能帮你校验和跳转类名写错在编译期就暴露了而不是等启动时才报“排除失败”。还有一个很隐蔽的坑自定义组合注解时exclude属性并不一定能被正确继承。比如你封装了一个MySpringBootApplication内部用了SpringBootApplication(exclude XxxAutoConfiguration.class)这时候如果外部想通过自定义注解传一个 exclude 列表必须用AliasFor做桥接否则注解属性根本没有绑定到底层的EnableAutoConfiguration上。我自己就吃过这个亏封装公司内部启动注解时exclude 写了个寂寞启动日志里清清楚楚看到该自动配置照常加载。2.2 配置文件排除环境差异化的最佳选择很多场景下不适合动启动类代码。比如两个环境共用一个 jar测试环境要排除某个自动配置生产环境不需要或者你手里的是别人编译好的二方包没法改启动类。这时候就轮到spring.autoconfigure.exclude出场了在 application.yml 里写spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration - org.springframework.boot.autoconfigure.data.redis.RedisAutoConfigurationproperties 写法也支持多个类用逗号分隔spring.autoconfigure.excludeorg.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\ org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration配置文件方式的好处是天然和 profile 结合你可以单独准备一个application-test.yml在里面排除掉所有外部中间件自动配置让测试环境只加载最小上下文生产环境什么都不用配。而且这种方式对运维也很友好不用改代码重启时加一个启动参数就行java -jar my-app.jar \ --spring.autoconfigure.excludeorg.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration命令行参数的本质也是环境属性优先级比配置文件高适合临时定位问题。我排查自动配置相关的疑难杂症时经常会先通过命令行参数排除嫌疑确认是它的锅再把排除项固化到配置里。2.3 条件注解的“反向排除”不写 exclude 也能关掉开关除了主动 exclude还有一类“被动排除”很多老手都在用。自动配置类上大概率有ConditionalOnMissingBean它的语义是“容器里没有这个 Bean 我才动手”。所以反过来利用它如果在项目里自己定义一个同类型 Bean这个自动配置就会自动放弃。举个最典型的例子Spring Boot 对 Jackson 的处理。JacksonAutoConfiguration上有ConditionalOnMissingBean(ObjectMapper.class)也就是说只要你自定义一个ObjectMapperBeanSpring Boot 就不会用它默认生成的那一套Configuration public class JacksonConfig { Bean Primary public ObjectMapper objectMapper() { return new ObjectMapper() .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) .setSerializationInclusion(JsonInclude.Include.NON_NULL); } }这种方式的好处是代码语义更清晰我不是在“排除某个自动配置”而是在“明确给出自己的实现”。很多框架的官方文档也推荐这种做法比如你需要自定义RestTemplateBuilder、自定义WebMvcConfigurer优先通过自定义 Bean 让自动配置的条件自然失效。不过要注意它只对那些带ConditionalOnMissingBean的配置类有效。如果某个自动配置类压根没有这类条件或者条件里还掺了ConditionalOnProperty那自定义 Bean 也压不住它该走exclude还是得走。判断到底走哪条路的方法很简单打开自动配置报告看这个配置类命中的条件是什么再做决定。3. 排查自动配置的实战套路与高频踩坑实录3.1 自动配置报告是最好的“破案工具”遇到“为什么这个自动配置就是生效了”和“为什么我排除了它还是不生效”不要瞎猜先看自动配置报告。把debug打开即可debug: true或者启动时加--debug参数。Spring Boot 在启动日志里会输出一份完整的自动配置报告主要包括三块Positive matches哪些自动配置条件满足、被加载了后面还会带出命中的条件。Negative matches哪些自动配置因为条件不满足没被加载会写清楚没加载的原因。Exclusions哪些自动配置被主动排除了。我排查 exclude 不生效的时候第一步永远是在启动日志里搜Exclusions看目标类到底在不在排除列表里。如果在说明排除配置本身生效了那问题出在后续加载环节如果不在说明你的 exclude 压根没被识别优先回头检查类名、配置位置和版本差异。这份报告还有个额外的价值能帮你了解自动配置内部的“依赖顺序”。有时候你排除了 A但 A 内部又Import了 BB 照样会加载。光看 Positive matches 里 A 消失了不算完还得看 B 有没有出现在列表里。3.2 排除不生效的五个典型原因我在社区和团队里帮人排查过不少“明明 exclude 了为什么没用”的案例整理下来核心原因就是这五类。第一个类名写错或包名不全。配置文件里用的是字符串IDE 不做编译期校验多一个字母少一个包名都会被静默忽略。一定要用完整全限定名比如org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration少写autoconfigure那段就是无效配置。第二个排除了普通配置类而不是自动配置类。前面提过exclude只对自动配置通道生效。你想排除的必须是在spring.factories或AutoConfiguration.imports里注册过的类。怎么确认直接进依赖 jar 翻一下这两个文件别靠猜。第三个被ComponentScan又扫回来了。这是个特别隐蔽的坑。SpringBootApplication默认扫描启动类所在包及其子包如果你把某个自动配置类或者它内部Import的配置类放在了这个扫描范围里那即使 exclude 了ComponentScan也会把它当成普通Configuration加载。exclude 只阻断自动配置那条路阻断不了组件扫描。第四个只排除了外层没排除Import的内层。自动配置类之间可以通过Import互相引用比如DataSourceAutoConfiguration里 import 了好几个内部数据源候选配置类。排除最外层不一定能拦住所有内部加载排查时要在自动配置报告里把 Positive matches 完整看一遍。第五个多模块/多应用上下文之间的误判。如果你用的是微服务多模块工程A 服务 exclude 了自动配置但 B 服务没有那 B 里照样加载。这种情况不是排除失效是范围没对齐要确认当前排查的应用实例到底加载的是哪个模块、哪份配置。3.3 排除之后 Bean 缺失怎么办这是另一个方向的经典问题排除了自动配置结果某个功能直接不可用了报错比如“No qualifying bean of type DataSource found”。原因很简单排除自动配置意味着没人帮你创建那个 Bean 了你得自己接管。最稳妥的接管方式就是手动定义 Bean前面多数据源场景会详细演示。另一个思路是用Import只引入你需要的那个内部配置类。比如某个自动配置类里定义了三个 Bean你只需要其中一个与其全盘接受不如把它的配置类整体Import进来然后看情况补配条件。这种“精准导入”比“全量排除再全量手写”省事得多但要求你对这个自动配置类内部的结构足够熟悉不然容易漏掉依赖。我个人的习惯是能通过自定义 Bean 接管就自定义 Bean不能确定内部依赖关系就直接 exclude 然后给自己的配置类写清楚所有依赖别做“半个接管”那是启动报错的温床。4. 实操案例多数据源项目怎么干净利落地排除4.1 场景还原与问题现象我处理过一个很典型的项目Spring Boot 2.6.x MyBatis-Plus业务里有主库和报表库两个数据源。最开始没做排除只在 yml 里配了两个数据源信息结果启动直接报错或者明明配了两个运行时始终只有一个 datasource Bean。原因是DataSourceAutoConfiguration和 MyBatis 的自动配置都只认单一数据源它们会自动创建一个默认的、基于“某个约定配置”的 Bean跟手动配置项互相抢位置。这类问题的本质就是“自动配置的单数据源假设”和“业务的双数据源现实”冲突。靠调整配置项很难解决干净的做法是把数据源相关的自动配置整个排除掉然后手动接管全部数据源创建逻辑。4.2 排除与替换的具体步骤第一步确定要排除哪些自动配置类。这个场景最少要排除DataSourceAutoConfiguration如果你也用 MyBatis-Plus通常还要排除com.baomidou.mybatisplus.autoconfigure.MybatisPlusAutoConfiguration。为什么连 MyBatis 那个也要排因为它的默认行为是只认容器里那个唯一的DataSource创建SqlSessionFactory多数据源时必须自己定义两个SqlSessionFactory它自动配置反而碍手碍脚。第二步在启动类上把这两个自动配置排除掉SpringBootApplication(exclude { DataSourceAutoConfiguration.class, MybatisPlusAutoConfiguration.class }) public class MultiDataSourceApplication { public static void main(String[] args) { SpringApplication.run(MultiDataSourceApplication.class, args); } }第三步写一个手动的数据源配置类。先看 yml 里怎么配spring: datasource: primary: url: jdbc:mysql://localhost:3306/main_db username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver report: url: jdbc:mysql://localhost:3306/report_db username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver然后定义两个DataSourceBeanConfiguration public class MultipleDataSourceConfig { Bean Primary ConfigurationProperties(prefix spring.datasource.primary) public DataSource primaryDataSource() { return DataSourceBuilder.create().build(); } Bean ConfigurationProperties(prefix spring.datasource.report) public DataSource reportDataSource() { return DataSourceBuilder.create().build(); } }这样两个数据源就完全由项目自己掌控了。如果你想进一步把 MyBatis 也完整接管还需要分别为两个数据源创建SqlSessionFactory和对应的 Mapper 扫描。核心思路都一样排除自动配置后所有关键 Bean 都显式声明不再指望框架默认行为。这里要特别提醒一点DataSourceAutoConfiguration被排除后如果容器里一个DataSourceBean 都没有基于ConditionalOnSingleCandidate(DataSource.class)的很多自动配置比如事务管理器、JdbcTemplate也会跟着跳过。所以接管数据源配置时一定要确认相关 Bean 都已经手动补充了否则项目能启动但一用持久层就报“找不到数据源”。4.3 验证日志、Actuator、测试三层校验排除完不是启动不报错就完事了你得确认“该排的排了、该留的留了”。第一层验证是看自动配置报告里的Exclusions和Positive matches重点确认DataSourceAutoConfiguration不在 Positive matches 里。第二层验证可以用 Actuator 端点。引入spring-boot-starter-actuator并暴露 beans 端点management: endpoints: web: exposure: include: beans然后访问/actuator/beans在返回 JSON 里搜索DataSource确认只有primaryDataSource和reportDataSource两个 Bean没有自动配置生成的那个默认数据源。这个做法在做系统监控时也特别有用配合 Spring Boot Admin 能一眼看清应用上下文里到底注册了什么。第三层验证是写自动配置单元的验证代码把它固化到 CI 里防止后续有人改配置又把自动配置带了回来。这部分的完整代码我会在下一节讲算是自动配置测试的进阶玩法。5. 进阶实践测试与自定义 Starter 里的排除学问5.1 用 ApplicationContextRunner 做自动配置回归测试SpringBootTest启动完整上下文去验证一个自动配置排不排除成本太高了。Spring Boot 官方推荐用ApplicationContextRunner做轻量级自动配置测试它能在不启动 Web 容器的情况下快速验证“某一段自动配置在当前条件下到底加载了哪些 Bean”。结合spring.autoconfigure.exclude属性你甚至可以直接断言“排除后某个 Bean 不存在”。举个例子我要验证RedisAutoConfiguration被排除后StringRedisTemplate确实不会被创建import org.junit.jupiter.api.Test; import org.springframework.boot.autoconfigure.AutoConfigurations; import org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration; import org.springframework.boot.test.context.runner.ApplicationContextRunner; import static org.assertj.core.api.Assertions.assertThat; class RedisAutoConfigurationExcludeTest { private final ApplicationContextRunner contextRunner new ApplicationContextRunner() .withConfiguration(AutoConfigurations.of(RedisAutoConfiguration.class)); Test void excludeRedisAutoConfigurationThenNoRedisTemplate() { contextRunner .withPropertyValues(spring.autoconfigure.exclude RedisAutoConfiguration.class.getName()) .run(context - { assertThat(context).doesNotHaveBean(StringRedisTemplate.class); }); } Test void keepRedisAutoConfigurationThenRedisTemplateExists() { contextRunner .run(context - { assertThat(context).hasSingleBean(StringRedisTemplate.class); }); } }这个测试跑得飞快而且结论明确排除配置确实生效了。我们在公司内部脚手架里给每个定制的自动配置都写了类似的验证版本升级、依赖调整时跑一遍能提前拦截很多“自动配置突然生效”的回归问题。5.2 自研 Starter 时把“排除”主动权交给使用者除了在业务项目里排除第三方自动配置另一个方向是自研 Starter 时主动为使用者设计好“排除入口”。Spring Boot 2.7 之前自定义自动配置要把类名写进META-INF/spring.factories2.7 之后推荐改成META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件每行一个自动配置类的全限定名com.example.myproject.MyCustomAutoConfigurationSpring Boot 3.x 中只认 imports 文件新版 starter 建议直接把自动配置类用AutoConfiguration注解标注它会自动适配这个机制。关键是自动配置类内部要尽量把条件写全、写准给使用者保留优雅的关闭通道。常见的做法有三种第一给自动配置类加ConditionalOnClass使用者只要不引入某个依赖自动配置就不会触发第二加ConditionalOnProperty让使用者能通过一个enabled开关关闭它第三内部用到核心 Bean 时都写上ConditionalOnMissingBean允许使用者自定义同类型 Bean 覆盖默认实现。这三个条件组合起来使用者既可以直接用 exclude 硬排也可以不动代码只改配置甚至可以通过自定义 Bean 无声无息地接管可玩性高很多。反过来讲如果一个自研 Starter 的自动配置类没有这些合理条件使用方就只能“暴力 exclude”你整个配置类而且一旦你的配置类内部Import了别的配置他们排了也可能排不干净。这属于给自己挖坑。5.3 实例接入监控时如何排除 Security 自动配置最后放一个实战小例子和“Spring Boot 实现监控、Spring Boot Admin”这类需求强相关。很多项目接入 Spring Boot Admin 或 Actuator 暴露监控端点时会顺手引入spring-boot-starter-security。依赖一进来SecurityAutoConfiguration就会自动接管所有请求的认证逻辑默认还生成一个随机密码的用户结果监控端点全被拦住了访问/actuator/health都要登录。这时候如果你本来就要在安全上手动接管可以直接排除它SpringBootApplication(exclude { SecurityAutoConfiguration.class, UserDetailsServiceAutoConfiguration.class }) public class MonitorApplication { // ... }排除之后Spring Security 的自动配置不会再生成默认用户和默认拦截链工程里由自己定义SecurityFilterChain那段逻辑说了算监控端点可以手动放行业务接口的鉴权规则也完全可控。如果你的项目需要保留安全自动配置也可以通过定义SecurityFilterChain、自定义用户服务来覆盖不一定非要走 exclude。这两条路我都试过如果你刚接入监控建议先排除掉默认安全自动配置把监控探活跑通再补业务侧鉴权排查问题时会少很多干扰因素。关于自动配置排除最后还有个小技巧想分享新项目接手时我会习惯性把所有依赖对应的自动配置类名单整理一遍然后带着这份名单看第一次启动的自动配置报告。对上了项目结构就心里有数了对不上说明有些二方包注册了我没注意到的自动配置趁早决定是保留还是排除。这套“先摸底、再决策”的习惯比遇到报错再临时 exclude 高效得多也让我避开了很多启动期的隐形雷。