SpringBoot中自动配置与条件装配原理详解

更新时间：2026年07月01日 09:28:23 作者：路从脚起

这篇文章深入解析了SpringBoot自动配置的核心机制,涵盖@@EnableAutoConfiguration、@AutoConfigurationImportSelector、条件Evaluator等关键注解与类,文中的示例代码讲解详细,感兴趣的小伙伴可以了解下

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

注解	判断条件
`@ConditionalOnClass`	classpath 中有指定类
`@ConditionalOnMissingClass`	classpath 中无指定类
`@ConditionalOnBean`	容器已有指定 Bean
`@ConditionalOnMissingBean`	容器无指定 Bean
`@ConditionalOnProperty`	指定属性存在且有特定值
`@ConditionalOnResource`	指定资源文件存在
`@ConditionalOnWebApplication`	当前是 Web 应用
`@ConditionalOnNotWebApplication`	当前不是 Web 应用
`@ConditionalOnExpression`	SpEL 表达式为 true
`@ConditionalOnJava`	Java 版本满足条件
`@ConditionalOnJndi`	JNDI 资源存在

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 按这个顺序决定：

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

解决方案：用 @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.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

以上就是SpringBoot中自动配置与条件装配原理详解的详细内容，更多关于SpringBoot自动配置的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

解析Tars-Java客户端源码
Tars是基于名字服务使用Tars协议的高性能RPC开发框架，同时配套一体化的服务治理平台，帮助个人或者企业快速的以微服务的方式构建自己稳定可靠的分布式应用
2021-06-06
SpringCloud实现基于RabbitMQ消息队列的详细步骤
在Spring Cloud框架中,我们可以利用RabbitMQ实现强大而可靠的消息队列系统,本篇将详细介绍如何在Spring Cloud项目中集成RabbitMQ,并创建一个简单的消息队列,感兴趣的朋友一起看看吧
2024-03-03
Java中@ExcelIgnoreUnannotated注解小结
本文主要介绍了Java中@ExcelIgnoreUnannotated注解小结,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
2025-08-08
Mybatis-Plus分页的使用与注意事项
分页查询每个人程序猿几乎都使用过,下面这篇文章主要给大家介绍了关于Mybatis-Plus分页的使用与注意事项的相关资料,文中通过实例代码介绍的非常详细,需要的朋友可以参考下
2022-04-04
Java中的Lombok使用及工作原理详解
这篇文章主要介绍了Java中的Lombok使用及工作原理详解,Lombok是一个Java库,能自动插入编辑器并构建工具,简化Java开发,通过添加注解的方式,不需要为类编写getter或eques方法,同时可以自动化日志变量,需要的朋友可以参考下
2023-10-10
Java执行.bat文件的四种高效方法
在Windows操作系统中,.bat 文件是一种批处理脚本文件,它可以包含一系列命令,用于执行特定的任务,在Java开发中,.bat 文件通常用于简化Java程序的启动和执行过程,本文给大家介绍了Java执行.bat文件的四种高效方法,需要的朋友可以参考下
2025-08-08
Java多线程继承Thread类详解
Java多线程的两种实现方式：继承Thread类 & 实现Runable接口，今天我们来学习下继承Thread类，希望大家能够喜欢
2016-06-06
使用springboot不自动初始化数据库连接池
这篇文章主要介绍了使用springboot不自动初始化数据库连接池，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-09-09
控制台显示java冒泡排序流程示例
这篇文章主要介绍了控制台显示java冒泡排序流程示例,需要的朋友可以参考下
2014-03-03
spring集成httpclient配置的详细过程
spring框架是一个非常强大的框架这里就不多说了，那么主要是介绍spring与httpclient的整合集成过程，感兴趣的朋友跟随小编一起看看吧
2021-07-07