Mastering Spring Boot Auto-Configuration: Full 3.x Mechanism Explained

Overview

Spring Boot’s auto‑configuration (Auto‑Configuration) is the cornerstone of its "out‑of‑the‑box" experience, combining SPI extension mechanisms with conditional bean registration so developers can use common features without writing explicit @Bean definitions.

Core Mechanism Overview

@EnableAutoConfiguration : Entry annotation for auto‑configuration.

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports : The sole registration method recommended for Spring Boot 3.x.

META-INF/spring.factories : Used up to Spring Boot 2.6; deprecated in 2.7 and removed in 3.x.

@Conditional* annotations : Enable conditional loading of beans based on classpath, environment, existing beans, properties, etc.

SpringFactoriesLoader : Reads auto‑configuration class declarations from .imports or spring.factories.

Auto‑Configuration Execution Chain (Source‑Level)

Entry annotation: @SpringBootApplication (equivalent to @EnableAutoConfiguration, @ComponentScan, @Configuration).

During SpringApplication.run(...), the AutoConfigurationImportSelector is invoked.

The selector calls SpringFactoriesLoader.loadFactoryNames(...) to read either .imports or spring.factories.

Loaded class names are filtered by the various @Conditional annotations.

Classes that satisfy the conditions are registered as configuration beans in the container.

Conditional Annotation Quick Reference

@ConditionalOnClass : Loads if the specified class is present on the classpath.

@ConditionalOnMissingBean : Loads if the specified bean is absent in the container.

@ConditionalOnProperty : Loads if a configuration property matches the given condition.

@ConditionalOnBean : Loads if the specified bean already exists.

@ConditionalOnWebApplication : Loads only for web environments.

@EnableConfigurationProperties : Binds external configuration to a Java bean.

Evolution of Registration Methods

Spring Boot 2.6 and earlier : Uses spring.factories (now deprecated).

Spring Boot 2.7 (including) : Introduces .imports under META-INF/spring/… as the new mechanism.

Spring Boot 3.x : Completely removes spring.factories; only .imports is supported.

Spring Boot 3.x .imports New Mechanism

Fixed path:

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

.

File content: one fully‑qualified auto‑configuration class name per line, optional comments prefixed with #.

Example line: com.example.config.MyAutoConfiguration # comment.

Important Considerations

Configuration classes must be annotated with @AutoConfiguration or meet the conditions of @Configuration.

The file must reside in the resources directory and be packaged correctly inside the JAR.

Only auto‑configuration classes use .imports; other SPI mechanisms still rely on spring.factories.

Case Study: DataSourceAutoConfiguration

@AutoConfiguration
@ConditionalOnClass({DataSource.class, EmbeddedDatabaseType.class})
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {
    @Configuration(proxyBeanMethods = false)
    @Conditional(EmbeddedDatabaseCondition.class)
    @ConditionalOnMissingBean({DataSource.class, XADataSource.class})
    @Import(EmbeddedDataSourceConfiguration.class)
    protected static class EmbeddedDatabaseConfiguration {}

    @Configuration(proxyBeanMethods = false)
    @Conditional(PooledDataSourceCondition.class)
    @ConditionalOnMissingBean({DataSource.class, XADataSource.class})
    @Import({DataSourceConfiguration.Hikari.class, DataSourceConfiguration.Tomcat.class})
    protected static class PooledDataSourceConfiguration {}
}

Creating Custom Auto‑Configuration (3.x)

Write the auto‑configuration class:

@AutoConfiguration
@ConditionalOnClass(MyService.class)
public class MyServiceAutoConfiguration {
    @Bean
    public MyService myService() {
        return new MyService();
    }
}

Register it in the .imports file located at

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

.

com.example.config.MyServiceAutoConfiguration

Debugging and Troubleshooting

View loaded auto‑configuration classes: java -jar app.jar --debug Exclude a specific auto‑configuration:

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)

List all beans in the context: curl http://localhost:8080/actuator/beans Inspect the .imports file inside a JAR:

jar -xf your-lib.jar META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

Conclusion

Spring Boot auto‑configuration combines SPI with conditional loading.

spring.factories was deprecated in 2.7 and removed in 3.x; .imports is now the sole registration method.

The core selector is AutoConfigurationImportSelector.

Understanding the loading chain and conditional annotations is essential for creating custom auto‑configuration.