先说结论
Spring Boot 自动装配的完整链路是:@SpringBootApplication 里的 @EnableAutoConfiguration → AutoConfigurationImportSelector 读取 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件里的自动配置类全名 → 用 @Conditional 系列注解逐个筛选 → 把符合条件的配置类中的 @Bean 注册进容器。它是"约定 + 条件化装配",不是魔法。理解链路的价值在于排查:starter 引了没生效、自定义 Bean 没覆盖默认实现、升级后配置静默失效,这三类问题都能沿这条链路找到断点在哪一环。
链路拆解
第一步:入口注解
@SpringBootApplication 是三个注解的组合:@SpringBootConfiguration(本质是 @Configuration)、@ComponentScan(扫描主类所在包及子包)、@EnableAutoConfiguration。自动装配的钥匙是第三个。这里顺便解释一个日常约束:主类为什么必须放在根包——因为默认的 @ComponentScan 只扫主类所在包及子包,主类放歪了,扫描范围就歪了,“组件没被扫到"类的问题根源多半在这里,而不是在自动装配。另外两个注解也值得认识:@Import 直接把指定类注册进容器(自动装配与 @EnableXxx 的共同底座),@ImportResource 兼容遗留 XML 配置——新老配置方式在 BeanDefinition 这一层汇合,容器并不区分它们的来源。
第二步:加载候选名单
@EnableAutoConfiguration 通过 @Import(AutoConfigurationImportSelector.class) 生效。Spring Boot 2.7 起,候选配置类清单从 spring.factories 迁移到独立的 imports 文件,一行一个全限定类名。启动时 selector 会把这个清单全部读出来,但读出来 ≠ 注册,还要过条件筛选——清单通常上百行,真正装配的可能只有十几行,其余都被条件注解挡在了门外。
实现细节上,AutoConfigurationImportSelector 是一个 DeferredImportSelector:它带来的配置类会被推迟到所有用户配置类处理完之后再处理。这个"延迟"不是实现细节而是语义保证——自动装配必须先看到用户注册了什么,才能让 @ConditionalOnMissingBean 做出正确的退让判断。理解了处理顺序,“为什么我的 Bean 能覆盖默认实现"就不再是记忆题,而是可以自己推理出来的结论。
第三步:条件过滤
每个自动配置类都被条件注解把守,常见组合如下(简化自 Spring Boot 源码的 Redis 自动配置):
@AutoConfiguration
@ConditionalOnClass(RedisOperations.class) // 类路径有 Redis 客户端才装配
public class RedisAutoConfiguration {
@Bean
@ConditionalOnMissingBean(name = "redisTemplate") // 用户没自定义才给默认
public RedisTemplate<Object, Object> redisTemplate(
RedisConnectionFactory connectionFactory) {
/* ... */
}
}
@ConditionalOnClass 管"类路径上有没有”,@ConditionalOnMissingBean 管"用户有没有自己定义”,@ConditionalOnProperty 管"配置开关是否打开"。这解释了两个日常现象:
- 引入 starter 就能用:starter 只带依赖,装配逻辑在自动配置类里,类路径出现关键类就触发了
@ConditionalOnClass; - 自己定义 Bean 会覆盖默认的:
@ConditionalOnMissingBean让自动配置在用户已有同名 Bean 时主动退让。
| 条件注解 | 判断依据 | 典型场景 |
|---|---|---|
| @ConditionalOnClass | 类路径是否存在指定类 | starter 依赖了客户端 SDK 才装配 |
| @ConditionalOnMissingBean | 容器是否已有同类型/同名 Bean | 提供默认实现并允许用户覆盖 |
| @ConditionalOnProperty | 配置开关是否匹配 | biz.sms.enabled=true 才生效 |
| @ConditionalOnBean | 容器是否已有某 Bean | 依赖数据源装配 JdbcTemplate |
| @ConditionalOnWebApplication | 当前是否 Web 应用 | Web 专属组件按环境装配 |
条件注解的评估时机本身也有讲究:@ConditionalOnClass 这类类路径条件在解析期就能判断,@ConditionalOnMissingBean 这类容器条件要等前面的注册动作完成。这也是 starter 作者要注意的坑:把 @ConditionalOnMissingBean 用在自己 starter 内部的两个 Bean 之间,等于引入了对处理顺序的隐式依赖,能不用就不用。
实战:写一个最小自动配置
自定义 starter 的套路固定为三件套。第一步写配置类,用条件注解把守:
@AutoConfiguration
@ConditionalOnProperty(prefix = "biz.sms", name = "enabled", havingValue = "true")
@EnableConfigurationProperties(SmsProperties.class)
public class SmsAutoConfiguration {
@Bean
@ConditionalOnMissingBean
public SmsClient smsClient(SmsProperties properties) {
return new SmsClient(properties.getAppKey(), properties.getSecret());
}
}
biz:
sms:
enabled: true
app-key: xxx
secret: yyy
第二步把配置类全名写进 src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件(一行一个全限定类名),第三步打成 starter 发布,消费方引依赖 + 加配置即生效。
最容易踩的坑在这里——自动配置类的位置:
// 错误写法:把 SmsAutoConfiguration 放在 com.company.common 这类
// 消费方一定会扫描的公共包里。后果:
// 1. 配置类被 @ComponentScan 扫描注册一次,又被 imports 文件注册一次;
// 2. 被扫描注册时它变成了"用户配置",处理时机早于自动装配阶段,
// @ConditionalOnMissingBean 的评估顺序被打乱,
// 用户的自定义覆盖关系变得不确定,各服务行为不一致
// 正确写法:自动配置类放在独立的、不会被消费方扫描到的包里
// (如 com.company.sms.autoconfigure),只通过 imports 文件注册,
// 让它始终走自动装配通道,覆盖关系符合"用户优先"的预期
补全三件套的最后一块——配置属性类:
@ConfigurationProperties(prefix = "biz.sms")
public class SmsProperties {
/** 应用 key,从配置文件绑定 */
private String appKey;
/** 密钥 */
private String secret;
/** 发送超时(毫秒),给默认值降低接入成本 */
private int timeoutMs = 3000;
// getter / setter 必须齐全,绑定靠 setter 写入
}
属性类由自动配置类上的 @EnableConfigurationProperties(SmsProperties.class) 显式注册,不强依赖消费方的扫描路径;松散绑定让 app-key 自动映射 appKey,配套 JSR303 校验可以在启动阶段拦住缺配置的问题。
打包环节还有一个细节:配置类的包名与 imports 文件里登记的全限定名必须逐字符一致——包重构时改了包名忘了改 imports,是最常见的"starter 发出去但没生效"的原因。发布前用一个真实消费方工程做一次引入验证,比只跑 starter 自己的单测可靠。
排查与避坑
- 用
--debug启动(java -jar app.jar --debug),条件评估报告会打印哪些配置类命中、哪些没命中、差在哪个条件——“starter 引了没生效"第一件事就是看这份报告; - 排除某个自动装配用
@SpringBootApplication(exclude = XxxAutoConfiguration.class); @ConditionalOnMissingBean有顺序敏感性:自动配置类在用户配置类之后处理,所以用户 Bean 优先;但如果你的自定义配置类也是自动配置(imports 文件加载),就要用@AutoConfiguration(before = ...)控制先后;- 升级 Spring Boot 大版本时,全局搜索旧机制的残留:
spring.factories里的自动配置项、旧的spring.autoconfigure.exclude写法,静默失效比报错更难发现; - 编程式查看条件评估结果:注入
ConditionEvaluationReport可以拿到与--debug相同的命中明细,CI 流水线里加一条"关键配置类必须命中"的自检断言,把"starter 没生效"拦在上线之前。
starter 维护者还有一件值得做的工程化动作:给装配结果加可观测性。自动配置类里打一条启动日志(INFO 级别,说明哪些 Bean 已按默认装配、哪些被用户覆盖),或者暴露一个只读端点返回当前生效的实现类与关键配置项。starter 被几十个服务引用时,“每个服务里谁在生效"靠翻代码是查不过来的,可观测性直接决定接入方的排障成本。
一句话收尾:自动装配 = 读清单 + 过条件 + 注册默认 Bean,默认实现永远给"用户没自定义"兜底。
生产案例
公司内部 sms-starter 被 20 多个服务引用。某次升级把自动配置类挪到了 com.company.common.starter.sms 包下——恰好落在多数消费方 @ComponentScan(scanBasePackages = "com.company") 的扫描范围内。上线后各服务行为开始分裂:一部分服务里用户的自定义 SmsClient 被默认实现覆盖(发出去的短信签名错误),另一部分服务直接因为重复 BeanDefinition 启动失败。排查时对比 --debug 的条件评估报告才发现,同一个配置类被扫描与 imports 两条通道各注册了一次,@ConditionalOnMissingBean 的评估时机在两类服务里截然不同。修复动作是:配置类挪出一切可能被扫描的包、只保留 imports 注册,并在 starter 里加了一条启动自检日志(打印当前生效的 SmsClient 实现类名),让"谁在生效"从猜测变成事实。
检查清单
- starter 的自动配置类位于独立包,不会被消费方的 @ComponentScan 扫到
- 自动配置类全名已写入 META-INF/spring 下的 imports 文件,且逐行核对过包名
- 默认 Bean 上都有 @ConditionalOnMissingBean,允许用户覆盖
- 可选功能用 @ConditionalOnProperty 提供配置开关,默认关闭或按文档暴露
- 排查装配问题时会用 –debug 启动读条件评估报告
- 升级 Spring Boot 版本时全局搜索过 spring.factories 自动配置残留
- starter 发布说明里写清了生效条件与配置项,消费方能自查"为什么没生效”