先说结论

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 发布说明里写清了生效条件与配置项,消费方能自查"为什么没生效”