SpringBoot中自動配置與條件裝配原理詳解

更新時間：2026年07月01日 09:28:23 作者：路從腳起

這篇文章深入解析了SpringBoot自動配置的核心機制,涵蓋@@EnableAutoConfiguration、@AutoConfigurationImportSelector、條件Evaluator等關鍵注解與類,文中的示例代碼講解詳細,感興趣的小伙伴可以了解下

"Spring Boot 的核心就是自動配置"——這句話我聽過不下二十遍。但直到有一天排查一個詭異的 bug：引入了一個數(shù)據(jù)源的 starter，啟動時配置類沒被執(zhí)行，數(shù)據(jù)源根本沒創(chuàng)建。當時除了斷點調(diào)試也別無他法，但斷點打哪里呢？自動配置類什么時候被加載的？條件判斷為什么沒通過？

說實話，用了四五年 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 接口，可以在運行時動態(tài)決定要導入哪個配置類。這在 Spring 4.x 之前只能靠 XML 或者 context:component-scan 做到。

// org.springframework.context.annotation.ImportSelector.java
// ——運行時決定導入哪個配置類
public interface ImportSelector {
    String[] selectImports(AnnotationMetadata importingClassMetadata);
}

@Import 在處理時會調(diào)用 ImportSelector.selectImports()，返回的類名數(shù)組會被注冊成 BeanDefinition。這就是自動配置的入口。

AutoConfigurationImportSelector 的執(zhí)行流程

// 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. 根據(jù) exclude 過濾
        Set<String> exclusions = getExclusions(annotationMetadata, exclusions);
        configurations.removeAll(exclusions);
        
        // 5. 條件過濾！——根據(jù) @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 做編譯時優(yōu)化。

我看了下 JDK 的實現(xiàn)，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 沒區(qū)別。真正的"自動"在于條件判斷。

// org.springframework.context.annotation.Conditional.java
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Conditional {
    Class<? extends Condition>[] value();
}

Spring Boot 內(nèi)置了十幾個條件注解：

注解	判斷條件
`@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 驅(qū)動）

2. classpath 有 EmbeddedDatabaseType（不能是純 R2DBC）

3. 容器里沒有 io.r2dbc.spi.ConnectionFactory（避免沖突）

然后進入內(nèi)部配置類：

Generic 配置：只在 spring.datasource.type 有值時生效
Hikari 配置：classpath 有 HikariCP 時優(yōu)先使用（matchIfMissing = true）

如果 classpath 同時有 HikariCP 和 TomcatCP？

Hikari 配置因為 matchIfMissing=true，在沒有 spring.datasource.type 時默認生效
Spring Boot 官方推薦 HikariCP，默認優(yōu)先

我調(diào)試這段代碼時發(fā)現(xiàn)了一個有趣的事：@ConditionalOnClass 的類找不到時不會報錯，只是默默地跳過這個配置。這意味著你即使往 classpath 里多塞了幾個數(shù)據(jù)源的 jar，最終只會有一個 DataSource 被創(chuàng)建——其余的自動配置都被條件絆住了。

這是我認為 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 在評估條件時有個優(yōu)化：多個 @ConditionalOnClass 條件，只要第一個不滿足就直接返回 false，不繼續(xù)判斷后面的。這種短路策略在大量自動配置類時能省不少時間。

自定義 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 + 環(huán)境變量允許，MyService 自動創(chuàng)建好。

我覺得 Spring Boot 的 starter 機制最成功的地方不在于降低了使用門檻——它降低了框架創(chuàng)造者的門檻。以前寫個框架要配 XML、寫一堆集成文檔、讓用戶手動導入?，F(xiàn)在一包依賴 + 一行配置，自動搞定。

自動配置常見問題排查

1. 自動配置沒生效

最常見的疑惑。"我引了 starter，為什么 Bean 沒創(chuàng)建？"

打開 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. 自動配置的優(yōu)先級問題

有時候兩個 starter 都試圖創(chuàng)建同一個類型的 Bean，誰勝出？

Spring Boot 按這個順序決定：

@AutoConfigureOrder 注解的 order 值（越小越優(yōu)先）
@AutoConfigureBefore / @AutoConfigureAfter 指定的順序
默認順序——取決于配置文件中出現(xiàn)的順序

@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 解析之前就已經(jīng)注冊到容器的，@ConditionalOnBean 的判斷是基于已經(jīng)注冊的 BeanDefinition 而不是運行時容器。如果 A 沒有在另一個配置類中提前注冊 BeanDefinition，BConfig 的條件就可能失敗。

解決方案：用 @ConditionalOnClass（基于 ClassLoader）代替，或者把 A 的優(yōu)先級提高。

從源碼看設計原則

我覺得 Spring Boot 自動配置這部分的代碼質(zhì)量非常高，最值得學習的是它的可擴展性和防御性設計：

基于 SPI 的擴展點：.imports 文件等價于 Java 的 ServiceLoader 機制，但它支持排序、過濾和條件判斷
條件失敗不是異常：這是最優(yōu)雅的設計決策——不合適的配置靜默跳過
ConfigurationClassPostProcessor：所有配置類解析都在這個 BeanFactoryPostProcessor 中完成，保證在 Bean 實例化之前就完成了所有配置決策

總結

Spring Boot 自動配置的核心就三環(huán)：

入口：@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中自動配置與條件裝配原理詳解的詳細內(nèi)容，更多關于SpringBoot自動配置的資料請關注腳本之家其它相關文章！

您可能感興趣的文章:

解析Tars-Java客戶端源碼
Tars是基于名字服務使用Tars協(xié)議的高性能RPC開發(fā)框架，同時配套一體化的服務治理平臺，幫助個人或者企業(yè)快速的以微服務的方式構建自己穩(wěn)定可靠的分布式應用
2021-06-06
SpringCloud實現(xiàn)基于RabbitMQ消息隊列的詳細步驟
在Spring Cloud框架中,我們可以利用RabbitMQ實現(xiàn)強大而可靠的消息隊列系統(tǒng),本篇將詳細介紹如何在Spring Cloud項目中集成RabbitMQ,并創(chuàng)建一個簡單的消息隊列,感興趣的朋友一起看看吧
2024-03-03
Java中@ExcelIgnoreUnannotated注解小結
本文主要介紹了Java中@ExcelIgnoreUnannotated注解小結,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友們下面隨著小編來一起學習學習吧
2025-08-08
Mybatis-Plus分頁的使用與注意事項
分頁查詢每個人程序猿幾乎都使用過,下面這篇文章主要給大家介紹了關于Mybatis-Plus分頁的使用與注意事項的相關資料,文中通過實例代碼介紹的非常詳細,需要的朋友可以參考下
2022-04-04
Java中的Lombok使用及工作原理詳解
這篇文章主要介紹了Java中的Lombok使用及工作原理詳解,Lombok是一個Java庫,能自動插入編輯器并構建工具,簡化Java開發(fā),通過添加注解的方式,不需要為類編寫getter或eques方法,同時可以自動化日志變量,需要的朋友可以參考下
2023-10-10
Java執(zhí)行.bat文件的四種高效方法
在Windows操作系統(tǒng)中,.bat 文件是一種批處理腳本文件,它可以包含一系列命令,用于執(zhí)行特定的任務,在Java開發(fā)中,.bat 文件通常用于簡化Java程序的啟動和執(zhí)行過程,本文給大家介紹了Java執(zhí)行.bat文件的四種高效方法,需要的朋友可以參考下
2025-08-08
Java多線程繼承Thread類詳解
Java多線程的兩種實現(xiàn)方式：繼承Thread類 & 實現(xiàn)Runable接口，今天我們來學習下繼承Thread類，希望大家能夠喜歡
2016-06-06
使用springboot不自動初始化數(shù)據(jù)庫連接池
這篇文章主要介紹了使用springboot不自動初始化數(shù)據(jù)庫連接池，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教
2021-09-09
控制臺顯示java冒泡排序流程示例
這篇文章主要介紹了控制臺顯示java冒泡排序流程示例,需要的朋友可以參考下
2014-03-03
spring集成httpclient配置的詳細過程
spring框架是一個非常強大的框架這里就不多說了，那么主要是介紹spring與httpclient的整合集成過程，感興趣的朋友跟隨小編一起看看吧
2021-07-07