企业官网建设流程全解析

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 读取 List<String> configurations = getCandidateConfigurations(annotationMetadata, getSpringFactoriesLoaderFactoryClass()); // 2. 去重 configurations = removeDuplicates(configurations); // 3. 按 @AutoConfigureOrder、@AutoConfigureAfter、@AutoConfigureBefore 排序 configurations = sort(configurations); // 4. 根据 exclude 过滤 Set<String> 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.DataSourceAutoConfiguration

Spring 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 List<String> 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 内置了十几个条件注解：

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 配置因为 matchIfMissing=true，在没有 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 按这个顺序决定：

1. @AutoConfigureOrder注解的 order 值（越小越优先）
2. @AutoConfigureBefore/@AutoConfigureAfter指定的顺序
3. 默认顺序——取决于配置文件中出现的顺序

@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没有在另一个配置类中提前注册 BeanDefinition，BConfig的条件就可能失败。

解决方案：用@ConditionalOnClass（基于 ClassLoader）代替，或者把A的优先级提高。

从源码看设计原则

我觉得 Spring Boot 自动配置这部分的代码质量非常高，最值得学习的是它的可扩展性和防御性设计：

1. 基于 SPI 的扩展点：.imports文件等价于 Java 的 ServiceLoader 机制，但它支持排序、过滤和条件判断
2. 条件失败不是异常：这是最优雅的设计决策——不合适的配置静默跳过
3. ConfigurationClassPostProcessor：所有配置类解析都在这个 BeanFactoryPostProcessor 中完成，保证在 Bean 实例化之前就完成了所有配置决策

总结

Spring Boot 自动配置的核心就三环：

1. 入口：@EnableAutoConfiguration→@Import(AutoConfigurationImportSelector.class)
2. 加载：读.imports文件，获知所有自动配置类的全限定名
3. 过滤：通过@Conditional条件族，只注册满足条件的配置类

反过来，如果你是一个框架作者，想写 starter 也就三步：

1. 写配置类和 Bean
2. 加条件注解
3. 在.imports文件中声明

文中引用的 Spring Boot 源码路径：

• org.springframework.boot.autoconfigure.EnableAutoConfiguration.java
• org.springframework.boot.autoconfigure.AutoConfigurationImportSelector.java
• org.springframework.context.annotation.Conditional.java
• org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration.java
• org.springframework.core.io.support.SpringFactoriesLoader.java

完整源码：github.com/spring-projects/spring-boot