AutoConfiguration.imports适合用过 Spring Boot、写过Configuration、但在碰到为什么这个自动配置没生效时一脸茫然的开发者。不适合刚学 Spring 第一天的新手。Spring Boot 的核心就是自动配置——这句话我听过不下二十遍。但直到有一天排查一个诡异的 bug引入了一个数据源的 starter启动时配置类没被执行数据源根本没创建。当时除了断点调试也别无他法但断点打哪里呢自动配置类什么时候被加载的条件判断为什么没通过说实话用了四五年 Spring Boot我自认对它的理解停留在配置中心 starter的层面。直到翻了一遍AutoConfigurationImportSelector的源码才真正明白自动配置是怎么自动的。从 SpringBootApplication 说起// org.springframework.boot.autoconfigure.SpringBootApplication.java Target(ElementType.TYPE) Retention(RetentionPolicy.RUNTIME) Documented Inherited SpringBootConfiguration EnableAutoConfiguration // ← 关键 ComponentScan(excludeFilters ...) public interface SpringBootApplication { // ... }SpringBootApplication是三个注解的合成体但起自动配置作用的是EnableAutoConfiguration。// org.springframework.boot.autoconfigure.EnableAutoConfiguration.java Target(ElementType.TYPE) Retention(RetentionPolicy.RUNTIME) Documented Inherited AutoConfigurationPackage Import(AutoConfigurationImportSelector.class) // ← 核心 public interface EnableAutoConfiguration { String ENABLED_OVERRIDE_PROPERTY spring.boot.enableautoconfiguration; Class?[] exclude() default {}; String[] excludeName() default {}; }核心就一行Import(AutoConfigurationImportSelector.class)。Import这玩意儿在 Spring 3.x 就有但 Spring Boot 把它用到了极致——通过ImportSelector接口可以在运行时动态决定要导入哪个配置类。这在 Spring 4.x 之前只能靠 XML 或者context:component-scan做到。// org.springframework.context.annotation.ImportSelector.java // ——运行时决定导入哪个配置类 public interface ImportSelector { String[] selectImports(AnnotationMetadata importingClassMetadata); }Import在处理时会调用ImportSelector.selectImports()返回的类名数组会被注册成 BeanDefinition。这就是自动配置的入口。AutoConfigurationImportSelector 的执行流程// org.springframework.boot.autoconfigure.AutoConfigurationImportSelector.java // ——自动配置的核心选择器极度精简 public class AutoConfigurationImportSelector implements DeferredImportSelector, BeanClassLoaderAware, ... { Override public String[] selectImports(AnnotationMetadata annotationMetadata) { if (!isEnabled(annotationMetadata)) { return NO_IMPORTS; } // 1. 获取所有自动配置项 AutoConfigurationEntry autoConfigurationEntry getAutoConfigurationEntry( annotationMetadata); // 2. 返回配置类的全限定名 return StringUtils.toStringArray(autoConfigurationEntry.getConfigurations()); } protected AutoConfigurationEntry getAutoConfigurationEntry( AnnotationMetadata annotationMetadata) { // 1. 从 META-INF/spring/org.springframework.boot.autoconfigure. // AutoConfiguration.imports 读取 ListString configurations getCandidateConfigurations(annotationMetadata, getSpringFactoriesLoaderFactoryClass()); // 2. 去重 configurations removeDuplicates(configurations); // 3. 按 AutoConfigureOrder、AutoConfigureAfter、AutoConfigureBefore 排序 configurations sort(configurations); // 4. 根据 exclude 过滤 SetString exclusions getExclusions(annotationMetadata, exclusions); configurations.removeAll(exclusions); // 5. 条件过滤——根据 Conditional 系列注解判断 configurations filter(configurations, autoConfigurationMetadata); return new AutoConfigurationEntry(configurations, exclusions); } }整个流程清晰读取配置文件 → 去重 → 排序 → 排除 → 条件过滤 → 注册为 BeanDefinition配置文件的进化在 Spring Boot 2.7 之前自动配置项写在META-INF/spring.factories# spring.factories旧方案 org.springframework.boot.autoconfigure.EnableAutoConfiguration\ org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration,\ org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfigurationSpring Boot 2.7 开始换成独立的文件# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration说实话这个改动挺实在的——spring.factories是个大杂烩什么都能往里塞。换成.imports文件之后自动配置的列表单独管理也方便 Spring Boot 做编译时优化。我看了下 JDK 的实现Spring Boot 通过SpringFactoriesLoader加载这些文件// org.springframework.core.io.support.SpringFactoriesLoader.java // ——加载 META-INF/spring/*.imports 文件 public static ListString loadFactoryNames(Class? factoryType, Nullable ClassLoader classLoader) { String factoryTypeName factoryType.getName(); return loadSpringFactories(classLoader).getOrDefault(factoryTypeName, Collections.emptyList()); }Conditional 条件装配自动配置的灵魂如果自动配置只是读配置、注册 Bean那跟 Spring 3.x 的Import没区别。真正的自动在于条件判断。// org.springframework.context.annotation.Conditional.java Target({ElementType.TYPE, ElementType.METHOD}) Retention(RetentionPolicy.RUNTIME) Documented public interface Conditional { Class? extends Condition[] value(); }Spring Boot 内置了十几个条件注解注解判断条件ConditionalOnClassclasspath 中有指定类ConditionalOnMissingClassclasspath 中无指定类ConditionalOnBean容器已有指定 BeanConditionalOnMissingBean容器无指定 BeanConditionalOnProperty指定属性存在且有特定值ConditionalOnResource指定资源文件存在ConditionalOnWebApplication当前是 Web 应用ConditionalOnNotWebApplication当前不是 Web 应用ConditionalOnExpressionSpEL 表达式为 trueConditionalOnJavaJava 版本满足条件ConditionalOnJndiJNDI 资源存在DataSourceAutoConfiguration 的实际例子// org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration.java AutoConfiguration ConditionalOnClass({ DataSource.class, EmbeddedDatabaseType.class }) ConditionalOnMissingBean(type io.r2dbc.spi.ConnectionFactory) EnableConfigurationProperties(DataSourceProperties.class) Import({ DataSourcePoolMetadataProvidersConfiguration.class, DataSourceInitializationConfiguration.InitializationSpecificCredentialsDataSourceInitializationConfiguration.class }) public class DataSourceAutoConfiguration { Configuration ConditionalOnMissingBean(DataSource.class) ConditionalOnProperty(name spring.datasource.type) static class Generic { Bean DataSource dataSource(DataSourceProperties properties) { return properties.initializeDataSourceBuilder().build(); } } Configuration ConditionalOnClass(HikariDataSource.class) ConditionalOnMissingBean(DataSource.class) ConditionalOnProperty(name spring.datasource.type, havingValue com.zaxxer.hikari.HikariDataSource, matchIfMissing true) static class Hikari { Bean ConditionalOnMissingBean(DataSource.class) HikariDataSource dataSource(DataSourceProperties properties) { HikariDataSource ds properties.initializeDataSourceBuilder() .type(HikariDataSource.class).build(); // ... return ds; } } }这个类的条件逻辑链非常典型DataSourceAutoConfiguration 生效需要 1. classpath 有 javax.sql.DataSource必须有 JDBC 驱动 2. classpath 有 EmbeddedDatabaseType不能是纯 R2DBC 3. 容器里没有 io.r2dbc.spi.ConnectionFactory避免冲突 → 然后进入内部配置类 Generic 配置只在 spring.datasource.type 有值时生效 Hikari 配置classpath 有 HikariCP 时优先使用matchIfMissing true 如果 classpath 同时有 HikariCP 和 TomcatCP → Hikari 配置因为 matchIfMissingtrue在没有 spring.datasource.type 时默认生效 → Spring Boot 官方推荐 HikariCP默认优先我调试这段代码时发现了一个有趣的事ConditionalOnClass的类找不到时不会报错只是默默地跳过这个配置。这意味着你即使往 classpath 里多塞了几个数据源的 jar最终只会有一个 DataSource 被创建——其余的自动配置都被条件绊住了。这是我认为 Spring Boot 自动配置最精巧的地方条件失败不是异常而是静默跳过。这就允许所有的 starter 无脑导入所有依赖框架自己判断哪个生效。条件评估的短路策略// org.springframework.boot.autoconfigure.condition.OnClassCondition.java // Order(Ordered.HIGHEST_PRECEDENCE) class OnClassCondition extends SpringBootCondition { Override public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) { // 检查 ConditionalOnClass 和 ConditionalOnMissingClass // 通过 ClassLoader.loadClass() 或 sun.misc.Unsafe.defineClass 判断 } }Spring Boot 的ConditionEvaluator在评估条件时有个优化多个ConditionalOnClass条件只要第一个不满足就直接返回 false不继续判断后面的。这种短路策略在大量自动配置类时能省不少时间。自定义 Starter一个完整的例子理解了原理后写个 starter 其实就那么几步。my-starter/ ├── src/main/java/... │ └── MyAutoConfiguration.java // 自动配置类 ├── src/main/resources/ │ └── META-INF/spring/ │ └── org.springframework.boot.autoconfigure.AutoConfiguration.imports └── pom.xml// MyAutoConfiguration.java AutoConfiguration ConditionalOnClass(MyService.class) ConditionalOnProperty(prefix my.starter, name enabled, havingValue true, matchIfMissing true) EnableConfigurationProperties(MyProperties.class) public class MyAutoConfiguration { Bean ConditionalOnMissingBean public MyService myService(MyProperties properties) { return new MyService(properties.getHost(), properties.getPort()); } }# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports com.example.starter.MyAutoConfiguration就这么简单。启动 Spring Boot只要 classpath 有这个 jar 环境变量允许MyService自动创建好。我觉得 Spring Boot 的 starter 机制最成功的地方不在于降低了使用门槛——它降低了框架创造者的门槛。以前写个框架要配 XML、写一堆集成文档、让用户手动导入。现在一包依赖 一行配置自动搞定。自动配置常见问题排查1. 自动配置没生效最常见的疑惑。我引了 starter为什么 Bean 没创建打开 debug 日志# application.yml debug: true或者logging: level: org.springframework.boot.autoconfigure: DEBUG然后看控制台会输出类似这样的条件评估报告 AUTO-CONFIGURATION REPORT Positive matches: ----------------- DataSourceAutoConfiguration matched: - ConditionalOnClass found required classes javax.sql.DataSource, org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType (OnClassCondition) - ConditionalOnMissingBean (types: io.r2dbc.spi.ConnectionFactory) did not find any beans (OnBeanCondition) Negative matches: ----------------- ActiveMQAutoConfiguration: Did not match: - ConditionalOnClass did not find required class javax.jms.ConnectionFactory (OnClassCondition)Positive matches是匹配成功的Negative matches是匹配失败——会写明为什么失败。这个日志是我排查自动配置问题的第一手段。2. 自动配置的优先级问题有时候两个 starter 都试图创建同一个类型的 Bean谁胜出Spring Boot 按这个顺序决定AutoConfigureOrder注解的 order 值越小越优先AutoConfigureBefore/AutoConfigureAfter指定的顺序默认顺序——取决于配置文件中出现的顺序AutoConfiguration AutoConfigureBefore(DataSourceAutoConfiguration.class) // 在 DataSource 之前 AutoConfigureAfter(JdbcTemplateAutoConfiguration.class) // 在 JdbcTemplate 之后 public class MyDataSourceConfiguration { // ... }3. 条件判断的时序问题ConditionalOnBean是个容易踩坑的点Configuration public class AConfig { Bean public A a() { return new A(); } } Configuration ConditionalOnBean(A.class) public class BConfig { Bean public B b() { return new B(); } }因为 Spring Boot 的自动配置类是在Bean解析之前就已经注册到容器的ConditionalOnBean的判断是基于已经注册的 BeanDefinition 而不是运行时容器。如果A没有在另一个配置类中提前注册 BeanDefinitionBConfig的条件就可能失败。解决方案用ConditionalOnClass基于 ClassLoader代替或者把A的优先级提高。从源码看设计原则我觉得 Spring Boot 自动配置这部分的代码质量非常高最值得学习的是它的可扩展性和防御性设计基于 SPI 的扩展点.imports文件等价于 Java 的 ServiceLoader 机制但它支持排序、过滤和条件判断条件失败不是异常这是最优雅的设计决策——不合适的配置静默跳过ConfigurationClassPostProcessor所有配置类解析都在这个 BeanFactoryPostProcessor 中完成保证在 Bean 实例化之前就完成了所有配置决策总结Spring Boot 自动配置的核心就三环入口EnableAutoConfiguration→Import(AutoConfigurationImportSelector.class)加载读.imports文件获知所有自动配置类的全限定名过滤通过Conditional条件族只注册满足条件的配置类反过来如果你是一个框架作者想写 starter 也就三步写配置类和 Bean加条件注解在.imports文件中声明文中引用的 Spring Boot 源码路径org.springframework.boot.autoconfigure.EnableAutoConfiguration.javaorg.springframework.boot.autoconfigure.AutoConfigurationImportSelector.javaorg.springframework.context.annotation.Conditional.javaorg.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration.javaorg.springframework.core.io.support.SpringFactoriesLoader.java完整源码github.com/spring-projects/spring-boot