Skip to content

3.2-2 自动装配:条件装配、加载顺序、imports ​

所属:03 主流框架 / 3.2 Spring Boot 分级:A 状态:◐ 初稿 关联:3.1-1、3.1-2、3.1-3、3.1-5、3.2-1、3.2-3、3.2-4、3.2-8

  • 题型:原理 / 流程 / 排障

  • 一句话结论:Spring Boot 自动装配 = **@EnableAutoConfiguration → @Import(AutoConfigurationImportSelector) → 从 AutoConfiguration.imports(Boot 3)/ spring.factories(Boot 2)读取候选配置类 → 按 @ConditionalOnXxx 过滤 → 按 @AutoConfigureOrder/Before/After 排序 → 注册 BeanDefinition**。它能“按需生效”的关键有三点:**DeferredImportSelector让自动配置晚于用户配置解析**(所以@ConditionalOnMissingBean能尊重用户自定义)、**条件注解决定装不装**、**imports 文件决定找不找得到**。Boot 3 已不再从spring.factories` 读取自动配置。

  • 分层要点:

    1. 入口是一条注解链:@SpringBootApplication = @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan;@EnableAutoConfiguration = @AutoConfigurationPackage + @Import(AutoConfigurationImportSelector.class)。@AutoConfigurationPackage 把启动类所在包注册进 AutoConfigurationPackages,供 JPA/MyBatis 等做实体、Mapper 扫描。
    2. 候选清单来自 imports 文件:Boot 3 读 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports(每行一个全限定类名);Boot 2.7 也支持,但主路径仍是 META-INF/spring.factories 的 EnableAutoConfiguration= 键;Boot 3.0 起 spring.factories 这条路径被移除。自定义 starter 最常见的坑就是文件路径/文件名写错,启动不报错但就是不生效。
    3. DeferredImportSelector 是“用户优先”的机制:普通 ImportSelector 在解析配置类时立即执行;DeferredImportSelector 推迟到所有用户 @Configuration 解析完之后再执行。所以用户自己定义的 DataSource、RestTemplate 先进入 BeanDefinition 表,自动配置里的 @ConditionalOnMissingBean 才能看到并让位。这是自动装配“可覆盖”的根本原因。
    4. 条件装配分两个阶段:ConfigurationCondition.ConfigurationPhase.PARSE_CONFIGURATION(解析配置类时判断,如 @ConditionalOnClass)和 REGISTER_BEAN(注册 Bean 时判断,如 @ConditionalOnMissingBean、@ConditionalOnBean)。Boot 的 OnClassCondition 用 ASM 读元数据判断类是否存在,尽量不触发类加载;@ConditionalOnBean 只能看到“当前已注册”的 Bean,所以对顺序敏感。
    5. 加载顺序有两层:类之间用 @AutoConfigureOrder(数值)、@AutoConfigureBefore/After(类名)表达,由 AutoConfigurationSorter 做拓扑排序,无声明时按字母序;Bean 之间用 @Order/Ordered/@Priority(那是 AOP/集合注入的顺序,和自动配置顺序不是一回事)。@AutoConfigureBefore(X.class) 引用了不存在的类不会报错,只是不生效。
    6. 条件注解家族:@ConditionalOnClass/MissingClass(类路径)、@ConditionalOnBean/MissingBean/SingleCandidate(容器 Bean)、@ConditionalOnProperty(配置项)、@ConditionalOnResource(资源文件)、@ConditionalOnWebApplication(应用类型)、@ConditionalOnExpression(SpEL)、@ConditionalOnJava、@ConditionalOnJndi。底层都是 Spring 的 @Conditional + Condition 接口,Boot 只是提供了实现。
    7. 配置属性是自动装配的“参数面”:@ConfigurationProperties(prefix="xxx") 负责批量绑定,@EnableConfigurationProperties/@ConfigurationPropertiesScan 负责注册;Boot 2.2+ 支持构造器绑定(2.x 需 @ConstructorBinding,3.0 单构造器可省略),支持松散绑定(kebab-case/camelCase/下划线)。自动配置类通常“条件 + 属性 + @ConditionalOnMissingBean”三件套。
    8. 排障靠证据,不靠猜:--debug 或 logging.level.org.springframework.boot.autoconfigure=DEBUG 输出 ConditionEvaluationReport;Actuator /actuator/conditions 直接看每个自动配置类的 matched/mismatched 及原因;/actuator/beans 看最终注册了哪些 Bean。先确认“类有没有被加载”,再确认“条件为什么没过”,最后确认“Bean 有没有被覆盖”。
  • 图/流程:

text
启动时的解析顺序:
  SpringApplication.run
    → refresh()
      → invokeBeanFactoryPostProcessors
        → ConfigurationClassPostProcessor
          → 解析启动类 @SpringBootApplication
            → @ComponentScan:注册业务 BeanDefinition
            → @Import(AutoConfigurationImportSelector)
              → 是 DeferredImportSelector → 先挂起
          → 所有用户 @Configuration 解析完
            → AutoConfigurationImportSelector.selectImports()
              → 读 AutoConfiguration.imports
              → 去重 / 排除 exclude
              → AutoConfigurationImportFilter 预过滤(OnClass/OnWebApplication/OnBean)
              → AutoConfigurationSorter 排序
              → 逐个解析自动配置类
                → 条件不满足 → 跳过
                → 满足 → 注册 @Bean / @ConfigurationProperties
text
条件评估两个阶段:
  PARSE_CONFIGURATION  → 决定“这个配置类要不要解析”
    典型:@ConditionalOnClass、@ConditionalOnWebApplication
  REGISTER_BEAN        → 决定“这个 @Bean 要不要注册”
    典型:@ConditionalOnMissingBean、@ConditionalOnBean、@ConditionalOnProperty
text
排序:
  AutoConfigurationSorter
    → @AutoConfigureOrder(数值,越小越前)
    → @AutoConfigureBefore / @AutoConfigureAfter(类名依赖)
    → 拓扑排序;无声明按字母序
    → 存在环 → 报错/按字母序兜底
text
自定义 starter 结构:
  xxx-spring-boot-autoconfigure
    src/main/resources/META-INF/spring/
      org.springframework.boot.autoconfigure.AutoConfiguration.imports
        → com.example.xxx.XxxAutoConfiguration
    XxxAutoConfiguration
      @AutoConfiguration
      @ConditionalOnClass(XxxClient.class)
      @EnableConfigurationProperties(XxxProperties.class)
      @Bean @ConditionalOnMissingBean → XxxClient
  xxx-spring-boot-starter
    pom 只依赖 autoconfigure + 第三方 SDK
  • 版本/源码锚点:

    • Boot 2.7:新增 @AutoConfiguration 与 AutoConfiguration.imports;spring.factories 的 EnableAutoConfiguration 标记弃用。
    • Boot 3.0:不再从 spring.factories 读取自动配置;AutoConfigurationMetadata/spring-autoconfigure-metadata.properties 移除;Java 17+、Jakarta EE 9+;@AutoConfiguration 成为标准写法(自带 @Configuration(proxyBeanMethods = false))。
    • Boot 3.x:@ConditionalOnBooleanProperty(3.4+)简化布尔开关;@ConditionalOnThreading 用于虚拟线程判断。
    • 关键类:AutoConfigurationImportSelector(getAutoConfigurationEntry/getCandidateConfigurations/AutoConfigurationGroup)、ImportCandidates、AutoConfigurationSorter、AutoConfigurationImportFilter、OnClassCondition、OnBeanCondition、OnWebApplicationCondition、ConditionEvaluationReport、AutoConfigurationPackages。
    • Spring Framework:DeferredImportSelector、ImportSelector、ImportBeanDefinitionRegistrar、ConfigurationClassPostProcessor、ConfigurationCondition(3.1-1 第 5 步)。
    • 配置绑定:ConfigurationPropertiesBindingPostProcessor、EnableConfigurationPropertiesRegistrar、ConfigurationPropertiesScan;属性元数据 spring-configuration-metadata.json。
    • 开关:spring.autoconfigure.exclude、@SpringBootApplication(exclude=...)、spring.main.allow-bean-definition-overriding(Boot 2.1+ 默认 false)。
  • @Import 的三种形态:

形态写法执行时机典型用途
普通配置类@Import(FooConfig.class)直接解析模块内组合
ImportSelector@Import(MySelector.class)解析时立即执行按条件返回类名数组
DeferredImportSelector@Import(AutoConfigurationImportSelector.class)用户配置解析完后自动装配(用户优先)
ImportBeanDefinitionRegistrar@Import(MyRegistrar.class)解析时注册定义MyBatis Mapper、Feign Client
  • 条件注解:
注解判断对象注意
@ConditionalOnClass类路径用 ASM 判断;类不在时不要直接引用其类型,用 name=
@ConditionalOnMissingClass类路径与上面相反
@ConditionalOnBean已注册 Bean顺序敏感,推荐只用在自动配置类上
@ConditionalOnMissingBean已注册 Bean用户自定义覆盖的基石
@ConditionalOnSingleCandidate唯一/首选 BeanDataSource、CacheManager 常用
@ConditionalOnPropertyEnvironmenthavingValue、matchIfMissing
@ConditionalOnResource资源文件classpath:/file:
@ConditionalOnWebApplication应用类型type = SERVLET/REACTIVE
@ConditionalOnExpressionSpEL解析晚、难排查,慎用
@ConditionalOnJavaJDK 版本兼容多版本
@ConditionalOnJndiJNDI传统容器
  • @ConditionalOnBean vs @ConditionalOnMissingBean:
维度@ConditionalOnBean@ConditionalOnMissingBean
语义已有某 Bean 才生效没有某 Bean 才生效
顺序敏感高:只能看到之前注册的相对低:自动配置在用户配置之后
推荐位置自动配置类内部自动配置类 + @Bean 方法
search 属性ALL/ANCESTORS/CURRENT同
匹配依据类型(可用 name/value/annotation)同
常见坑写在用户配置类里结果不稳定返回类型写成实现类,接口注入时判断不到
  • 加载顺序的控制手段:
手段作用范围说明
@AutoConfigureOrder(n)自动配置类之间数值越小越先;只对自动配置生效
@AutoConfigureBefore(X.class)自动配置类之间声明式依赖;X 不存在时静默忽略
@AutoConfigureAfter(X.class)自动配置类之间常用:DataSource 之后才配 JdbcTemplate
imports 文件行序无不保证,最终以排序器为准
@Order/OrderedBean/集合注入不控制 BeanDefinition 注册顺序
@DependsOnBean 创建顺序运行时依赖,不改变解析顺序
  • 失效场景与定位:
现象根因处理
自定义 starter 的 Bean 不存在imports 路径/文件名写错;用了 Boot 3 但放 spring.factories校验 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
条件永远不满足@ConditionalOnClass 引用的类不在依赖里补依赖或用 name=
用户 Bean 被自动配置覆盖用了 @ConditionalOnBean 或同名 Bean改 @ConditionalOnMissingBean;检查 overriding 开关
自动配置 A 看不到 B 的 Bean顺序错,A 先于 B@AutoConfigureAfter
@ConditionalOnProperty 不生效前缀/属性名拼错;matchIfMissing 理解反用 Actuator /conditions 看实际判断
配置绑定为 null没 @EnableConfigurationProperties/@ConfigurationPropertiesScan;类没注册成 Bean补注解或加 @Component
启动报 NoClassDefFoundError@ConditionalOnClass 通过但方法签名直接引用了缺失类用 name= 或拆配置类
两个自动配置互相覆盖都缺 @ConditionalOnMissingBean明确主从,加条件
排除没起作用exclude 写的是内部类/名字拼错用全限定名;spring.autoconfigure.exclude
排序环A after B、B after A拆解依赖
自定义配置类被 @ComponentScan 又扫到类在启动包下且是 @Configuration放到独立包;AutoConfigurationExcludeFilter 只排除 imports 中的类
  • 排查三件套:
手段命令/配置看什么
条件报告--debug、ConditionEvaluationReport 日志Positive/Negative matches、Exclusions、Unconditional
Actuator/actuator/conditions每个自动配置类 matched/mismatched 原因
Bean 列表/actuator/beans、/actuator/configprops最终注册的 Bean、绑定后的属性值
  • 深挖点(面试官常追的 6 个):

    1. 自动配置的完整链路:@EnableAutoConfiguration 上的 @Import(AutoConfigurationImportSelector.class) 被 ConfigurationClassParser 识别为 DeferredImportSelector,先放进 deferredImportSelectors;等所有普通配置类解析完,再调用 selectImports。getAutoConfigurationEntry 依次做:读候选类(Boot 3 用 ImportCandidates.load)、removeDuplicates、应用 exclude、AutoConfigurationImportFilter 预过滤(OnClass/OnWebApplication/OnBean)、AutoConfigurationSorter 排序,最后返回类名数组交给解析器继续解析。
    2. 为什么用户配置能覆盖自动配置:因为 DeferredImportSelector 晚执行,用户 @Configuration 里的 @Bean 已经注册成 BeanDefinition;自动配置类里的 @ConditionalOnMissingBean 在 REGISTER_BEAN 阶段评估,看到同类型 Bean 就跳过。反过来,如果自动配置先执行,或者用户 Bean 来自 @ComponentScan 但类型不匹配(比如用户定义的是实现类、条件判断的是接口),覆盖就会失效。
    3. @ConditionalOnClass 为什么不触发类初始化:OnClassCondition 走 AnnotationMetadata/MetadataReader(ASM)读注解元数据,拿到类名后用类加载器做可读性判断,而不是 Class.forName 触发初始化。但条件通过后,ConfigurationClassParser 仍要解析 @Bean 方法签名,如果签名里直接写了缺失类,就会 NoClassDefFoundError——所以要么把 @ConditionalOnClass(name=...) 和引用类的方法拆到两个配置类,要么只在新配置类上做条件。
    4. 加载顺序到底谁决定:AutoConfigurationSorter 先按 @AutoConfigureOrder 分组,再按 @AutoConfigureBefore/After 建图做拓扑排序,没有依赖关系的按类名字母序。@AutoConfigureOrder 只对自动配置类有意义,不要拿它去控制普通 @Bean 的顺序;Bean 之间的顺序用 @Order/@DependsOn/ObjectProvider。
    5. 条件装配的边界:@ConditionalOnBean 依赖“当前已注册”的 Bean,写在用户配置类里可能因为解析顺序看不到后面的 Bean,官方建议只放在自动配置类;@ConditionalOnMissingBean 在自动配置里最可靠。@ConditionalOnExpression 解析时机晚、错误信息差,能用 @ConditionalOnProperty 就别用 SpEL。多个条件之间是 AND,需要 OR 时只能组合注解或自定义 Condition。
    6. 自定义 starter 怎么做得像官方:拆 xxx-spring-boot-autoconfigure(逻辑)+ xxx-spring-boot-starter(依赖聚合);自动配置类用 @AutoConfiguration + @ConditionalOnClass + @EnableConfigurationProperties + 每个 @Bean 加 @ConditionalOnMissingBean;提供 spring-configuration-metadata.json 让 IDE 有提示;imports 文件只写自动配置类,不写普通配置;版本升级时检查 Boot 2 → 3 的 javax→jakarta 和 imports 迁移。
  • 追问链:

    1. 什么是自动装配? → 按依赖和配置自动注册 Bean。
    2. 入口注解? → @EnableAutoConfiguration。
    3. @SpringBootApplication 包含什么? → @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan。
    4. 自动配置类从哪读? → Boot 3 AutoConfiguration.imports;Boot 2 spring.factories。
    5. imports 文件全路径? → META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。
    6. Boot 3 还读 spring.factories 吗? → 不读自动配置,其它扩展点仍用。
    7. 为什么用 DeferredImportSelector? → 用户配置先解析,自动配置后执行,保证可覆盖。
    8. ImportSelector 和 DeferredImportSelector 区别? → 立即 vs 延迟到用户配置之后。
    9. @Import 有几种用法? → 配置类、ImportSelector、ImportBeanDefinitionRegistrar。
    10. 条件注解底层是什么? → Spring @Conditional + Condition。
    11. 条件评估分几个阶段? → PARSE_CONFIGURATION 和 REGISTER_BEAN。
    12. @ConditionalOnClass 怎么判断? → ASM 读元数据,尽量不加载类。
    13. @ConditionalOnBean 为什么不可靠? → 只能看到已注册的 Bean,顺序敏感。
    14. @ConditionalOnMissingBean 用在哪? → 自动配置类/@Bean,让用户覆盖。
    15. @ConditionalOnSingleCandidate 用途? → 唯一或 @Primary 的 Bean。
    16. @ConditionalOnProperty 关键属性? → havingValue、matchIfMissing。
    17. 多个条件什么关系? → AND;OR 要自定义 Condition。
    18. 自动配置顺序谁定? → AutoConfigurationSorter。
    19. 排序依据? → @AutoConfigureOrder + @AutoConfigureBefore/After + 字母序。
    20. @AutoConfigureAfter 引用不存在的类? → 静默忽略。
    21. @Order 能控制自动配置顺序吗? → 不能,那是 Bean 顺序。
    22. 怎么排除自动配置? → exclude、spring.autoconfigure.exclude。
    23. 排除写错会怎样? → 不生效/启动报类找不到。
    24. 怎么排查条件不生效? → --debug、/actuator/conditions。
    25. ConditionEvaluationReport 在哪? → 启动日志/Actuator。
    26. 配置属性怎么绑定? → @ConfigurationProperties + @EnableConfigurationProperties/Scan。
    27. 构造器绑定要什么? → Boot 2.x @ConstructorBinding;3.0 单构造器可省。
    28. 松散绑定是什么? → kebab/camel/下划线互相兼容。
    29. @ConfigurationProperties 不加注解能生效吗? → 不会,得注册成 Bean。
    30. 自动配置类为什么要 proxyBeanMethods=false? → 避免 CGLIB 代理,启动更快;@AutoConfiguration 已默认。
    31. @AutoConfigurationPackage 做什么? → 记录启动类包,供实体/Mapper 扫描。
    32. 自动配置会被组件扫描重复注册吗? → AutoConfigurationExcludeFilter 排除。
    33. 同名 Bean 冲突怎么办? → Boot 2.1+ 默认禁止覆盖;改名/条件/排除。
    34. spring.main.allow-bean-definition-overriding? → 打开同名覆盖,慎用。
    35. 自动配置能读到用户 Bean 吗? → 能,但受顺序限制。
    36. 用户 Bean 能注入自动配置的 Bean 吗? → 能;定义注册有先后,但注入发生在实例化阶段,此时两类 BeanDefinition 都已就绪。
    37. 自动配置和 @ComponentScan 关系? → 相互独立,自动配置不靠扫描。
    38. 自定义 starter 怎么组织? → autoconfigure + starter 两个模块。
    39. starter 的 pom 该放什么? → 依赖聚合,不放代码。
    40. 怎么给配置项加 IDE 提示? → spring-configuration-metadata.json。
    41. Boot 3 迁移要注意什么? → imports 文件、javax→jakarta、Java 17。
    42. 自动配置能懒加载吗? → spring.main.lazy-initialization,但会影响启动期校验。
    43. 自动配置失败怎么报? → FailureAnalyzer 给出可读原因。
    44. 条件不满足会报错吗? → 不会,静默跳过(所以难查)。
    45. 怎么知道某自动配置为什么没生效? → /actuator/conditions 的 negative match 原因。
    46. 自动配置和 AOP 代理关系? → 无关,代理在 Bean 初始化后(3.1-5)。
    47. 自动配置能注册 BPP 吗? → 能,但要注意 BPP 注册时机早于普通 Bean(3.1-2)。
    48. @ConditionalOnWebApplication 类型? → SERVLET/REACTIVE/ANY。
    49. 自动配置会影响启动速度吗? → 会,候选类多、条件评估多;可排除无用配置。
    50. 面试怎么总结? → 注解入口 → imports 文件 → DeferredImportSelector → 条件过滤 → 排序 → 用户覆盖 → 排障三件套。
  • 生产案例/取舍(示例,替换成你的项目):

    • 自研 starter 升级 Boot 3 后不生效,仍放在 spring.factories;迁到 imports 文件恢复。
    • 自动配置的 RestTemplate 覆盖了业务自定义的超时配置;业务侧改用 @ConditionalOnMissingBean 或直接排除。
    • @ConditionalOnBean(DataSource.class) 写在用户配置类,时好时坏;移到自动配置类并加 @AutoConfigureAfter。
    • @ConditionalOnClass 通过但方法签名引用了缺失类,启动 NoClassDefFoundError;改 name= 并拆配置类。
    • 两个内部 starter 都提供 TokenService,启动报 Bean 冲突;加 @ConditionalOnMissingBean + @AutoConfigureOrder。
    • 配置项写成 my.app.enable,代码判断 myapp.enabled,条件永远 false;用 /actuator/conditions 定位。
    • @ConfigurationProperties 类没加 @EnableConfigurationProperties,绑定全 null;补注解或 @ConfigurationPropertiesScan。
    • 自定义 starter 把实现类放进 starter 模块,依赖倒挂;拆成 autoconfigure 模块。
    • 自动配置过多导致启动 8s;排除未使用的 20 个配置类,降到 5s。
    • @AutoConfigureBefore 引用了已改名的类,排序失效但无报错;升级时全局搜注解。
    • 用户自定义 CacheManager 仍被覆盖,因为条件判断的是实现类而用户 Bean 是接口代理;统一按接口类型判断。
    • 取舍:@ConditionalOnMissingBean 换可覆盖性,代价是条件判断成本/顺序依赖;@ConditionalOnProperty 换显式开关,代价是配置分散;拆 starter 换复用,代价是模块与版本管理;排除自动配置换启动速度,代价是功能缺失风险。
  • 易错点:

    • 认为自动装配靠 @ComponentScan 扫描。
    • 认为自动配置类必须放在启动类包下。
    • 认为 Boot 3 还从 spring.factories 读自动配置。
    • 认为 imports 文件的行序就是加载顺序。
    • 认为 @Order 能控制自动配置顺序。
    • 认为 @AutoConfigureOrder 对所有 Bean 生效。
    • 认为 @AutoConfigureBefore 引用不存在的类会报错。
    • 认为 ImportSelector 和 DeferredImportSelector 等价。
    • 认为 @ConditionalOnBean 在任何位置都可靠。
    • 认为 @ConditionalOnMissingBean 判断的是 Bean 名称。
    • 认为 @ConditionalOnClass 一定会加载类。
    • 认为条件不满足会抛异常。
    • 认为 @ConditionalOnProperty 默认 matchIfMissing=true。
    • 认为多个条件之间是 OR。
    • 认为 @ConfigurationProperties 类会自动成为 Bean。
    • 认为构造器绑定不需要任何注解(Boot 2.x)。
    • 认为自动配置不能被用户覆盖。
    • 认为同名 Bean 默认允许覆盖。
    • 认为 @SpringBootApplication 只有一个注解。
    • 认为 @EnableAutoConfiguration 可以重复加。
    • 认为自动配置类加 @Configuration 和 @AutoConfiguration 没区别。
    • 认为 proxyBeanMethods=true 更好。
    • 认为排除自动配置只能改代码。
    • 认为 @ConditionalOnWebApplication 对非 Web 也成立。
    • 认为条件评估只发生一次。
    • 认为自定义 starter 的 starter 模块要写代码。
    • 认为自动配置失败一定有清晰报错。
    • 认为 Boot 3 的自动配置机制和 Boot 2 完全一样。
  • 30 秒口述稿:

自动装配的入口是 @EnableAutoConfiguration,它 import 了 AutoConfigurationImportSelector。这个 selector 是 DeferredImportSelector,会等用户配置全部解析完再执行,所以用户 Bean 先注册,自动配置里的 @ConditionalOnMissingBean 才能让位。候选类来自 AutoConfiguration.imports,Boot 3 已经不再读 spring.factories。拿到候选后先去重、排除、用 AutoConfigurationImportFilter 预过滤,再由 AutoConfigurationSorter 按 @AutoConfigureOrder 和 @AutoConfigureBefore/After 排序,最后逐个解析,条件不满足就跳过。排查就看 --debug 或 /actuator/conditions,能直接看到每个配置类为什么没匹配上。

  • 3 分钟展开顺序:结论(注解入口 + imports + 延迟选择器 + 条件 + 排序)→ @SpringBootApplication 注解链 → imports 文件与 Boot 2/3 差异 → DeferredImportSelector 与“用户优先” → 条件注解家族与两个评估阶段 → 排序机制 → 配置属性绑定 → 自定义 starter 结构 → 排障三件套与生产坑。