Spring Boot Auto‑Configuration Unveiled: The @EnableAutoConfiguration SPI Mechanism

SPI Mechanism

SPI (Service Provider Interface) defines an interface and lists implementations in external files, enabling decoupled, plug‑and‑play extensions. Major frameworks use SPI, e.g., JDBC driver loading, Dubbo extension mechanism, Spring Boot auto‑configuration, and SLF4J binding.

Java Native SPI

Configuration files reside in META-INF/services/<fully‑qualified‑interface> and are loaded via ServiceLoader.load(Interface.class). For Spring Boot this approach has critical drawbacks:

All implementations are instantiated eagerly, preventing lazy loading and hurting performance.

No conditional filtering based on environment, classpath, or configuration.

Cannot sort, exclude, or override implementations.

Only implementation classes can be listed; configuration classes cannot be registered.

No priority or override mechanism, making it unsuitable for the Spring container.

Spring’s Two Generations of SPI

Old mechanism (spring.factories) – Spring Boot < 2.7

File: META-INF/spring.factories Format: properties key‑value pairs where the key is an extension interface or annotation and the value is a comma‑separated list of implementation or configuration classes.

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.MyAutoConfiguration

New mechanism (imports) – Spring Boot 2.7+ / 3.x

File: META-INF/spring/<package>.imports Key changes:

Each line contains a single configuration class, making parsing faster.

Dedicated auto‑configuration file, isolated from other SPI extensions.

Supports the new @AutoConfiguration annotation.

Significant startup‑time improvement and precise ordering.

Comparison

Spring Boot version : old – 2.7‑, new – 2.7+ / 3.x.

File location : old – META-INF/spring.factories, new – META-INF/spring/xxx.imports.

File format : old – properties key‑value, new – plain‑text one class per line.

Dedicated annotation : old – none (plain @Configuration), new – @AutoConfiguration.

Load performance : old – slow (properties parsing), new – fast (line‑by‑line read).

Extensibility : old – mixed with all extensions, new – separate auto‑configuration, single responsibility.

@EnableAutoConfiguration Annotation

Source code

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@AutoConfigurationPackage
@Import(AutoConfigurationImportSelector.class)
public @interface EnableAutoConfiguration {
    Class<?>[] exclude() default {};
    String[] excludeName() default {};
}

Two core components are imported: @AutoConfigurationPackage: registers the root package of the application for component scanning, enabling automatic detection of MyBatis, JPA, Mapper, etc. @Import(AutoConfigurationImportSelector.class): entry point for loading auto‑configuration classes.

@AutoConfigurationPackage

Records the root package of the main class.

Ensures @ComponentScan scans all business beans by default.

Supports automatic scanning for MyBatis, JPA, and Mapper interfaces.

Eliminates the need for manual package‑scan configuration.

AutoConfigurationImportSelector

Implements DeferredImportSelector, performing delayed import after all user configuration classes have been processed. This delay allows user‑defined beans to override auto‑configured beans.

Reads both the new .imports file and the legacy spring.factories (the latter still used for listeners, initializers, etc.).

Collects candidate auto‑configuration classes, removes duplicates, and applies user‑specified exclude filters.

Runs the auto‑configuration filter, which evaluates @Conditional annotations.

Applies a three‑level sorting rule (order, before/after, class name) before registering the classes as @Configuration beans.

Each bean method is processed; @ConditionalOnMissingBean ensures user beans take precedence.

Full Auto‑Configuration Execution Flow (10 Steps)

Run the Spring Boot main class, triggering @SpringBootApplication. @EnableAutoConfiguration imports AutoConfigurationImportSelector.

The container parses the deferred import selector after all user configuration classes are loaded. selectImports() reads both the new .imports and the old spring.factories files.

All candidate auto‑configuration classes are loaded and de‑duplicated.

Classes listed in exclude are removed.

The auto‑configuration filter evaluates @Conditional annotations.

Classes are sorted according to the three‑level ordering rule.

Valid auto‑configuration classes are imported as @Configuration beans.

Each @Bean method is processed; @ConditionalOnMissingBean decides whether to create the bean.

Auto‑Configuration Sorting Mechanism

Level 1: @AutoConfigureOrder – lower values load first.

Level 2: @AutoConfigureBefore / @AutoConfigureAfter – explicit before/after relationships.

Level 3: Alphabetical order of class names as a fallback.

Conditional Annotations – The Soul of Auto‑Configuration

@ConditionalOnClass

: activates when the specified class is present on the classpath. @ConditionalOnMissingBean: activates when the bean is not already defined, giving user beans priority. @ConditionalOnProperty: activates based on a property value in application.yml or environment variables. @ConditionalOnWebApplication: activates only in a web environment.

Standard Auto‑Configuration Template

@AutoConfiguration
@ConditionalOnClass(RedisTemplate.class)
@EnableConfigurationProperties(RedisProperties.class)
public class RedisAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public RedisTemplate<Object, Object> redisTemplate(RedisConnectionFactory factory) {
        RedisTemplate<Object, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(factory);
        return template;
    }
}

The complete flow is: add a starter → required class appears → no user bean defined → auto‑configuration creates the bean.

Common Reasons Auto‑Configuration Fails (10‑Point SOP)

Using the new Spring Boot version but still providing the old spring.factories file.

Incorrect file path or case‑sensitive name. @ConditionalOnClass points to a missing class (starter not added).

Explicit exclude removes the configuration.

Property in application.yml disables the auto‑configuration.

User‑defined bean registers before the auto‑configuration, causing the condition to fail.

Auto‑configuration class lacks the @AutoConfiguration annotation.

Package scanning does not include the auto‑configuration class.

Multiple starters conflict, leading to wrong load order.

IDE cache or uncompiled classes prevent the latest bytecode from being loaded.

Debugging Auto‑Configuration

Add the JVM argument --debug when starting the application. The console will list:

Positive matches : auto‑configurations that succeeded.

Negative matches : auto‑configurations that failed and the reason why.

Conclusion

Spring Boot’s auto‑configuration combines a custom SPI, deferred import selectors, multi‑level sorting, and rich conditional annotations to provide zero‑XML, plug‑and‑play functionality while keeping user‑defined beans in control. The new .imports mechanism and @AutoConfiguration annotation further improve startup speed and modularity.