Auto-Configuration Mechanism

Introduction

Spring Boot's auto-configuration inspects your classpath and config, then registers beans you would otherwise wire manually—DataSource, Jackson, Tomcat, JPA, and more. Understanding how it works helps you fix "bean not created" issues, exclude unwanted config, and build custom starters. This chapter traces @SpringBootApplication, condition annotations, and the AutoConfiguration.imports file in Boot 3.

Prerequisites

• Create First Spring Boot Project
• JDBC DataSource and Connection Pool Basics

What Auto-Configuration Does

Without Boot you might write:

@Bean
public DataSource dataSource() {
    HikariDataSource ds = new HikariDataSource();
    ds.setJdbcUrl("...");
    return ds;
}

With Boot + spring-boot-starter-jdbc + spring.datasource.* properties, DataSourceAutoConfiguration creates HikariDataSource when conditions match.

Flow:

Classpath has Hikari + JDBC driver
        ↓
DataSourceAutoConfiguration matches
        ↓
Reads spring.datasource.* properties
        ↓
Registers DataSource bean

@SpringBootApplication Breakdown

@SpringBootApplication
public class DemoApplication { }

Combines:

Exclude specific auto-config:

@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class
})

Or in YAML:

spring:
  autoconfigure:
    exclude:
      - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

Boot 3 Registration: AutoConfiguration.imports

Spring Boot 2 used META-INF/spring.factories. Boot 3 uses:

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

Each line is fully qualified auto-config class name, e.g.:

org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

Spring Boot loads listed classes and evaluates their @Conditional* annotations.

Conditional Annotations

Excerpt pattern from DataSourceAutoConfiguration concept:

@AutoConfiguration
@ConditionalOnClass(DataSource.class)
@ConditionalOnMissingBean(DataSource.class)
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {
    // ...
}

Your custom @Bean DataSource replaces auto-configured one (@ConditionalOnMissingBean).

View Auto-Configuration Report

Startup with debug:

java -jar app.jar --debug

Or:

logging:
  level:
    org.springframework.boot.autoconfigure: DEBUG

Look for Positive matches / Negative matches sections—shows why config applied or skipped.

Example negative match reason:

Did not match:
   - @ConditionalOnClass did not find required class 'org.h2.Driver'

Starter = Dependencies + Auto-Config

spring-boot-starter-web pulls:

• Tomcat (embedded)
• Spring MVC
• Jackson JSON
• Related auto-config classes

You add one dependency; Boot assembles the stack.

See Maven for dependency management basics.

Override Auto-Configuration Safely

Preferred order:

1. Properties — application.yml tune behavior
2. Custom @Bean — replace specific component
3. Exclude auto-config — last resort when feature unused

FAQ

Bean defined twice?

Your @Bean plus auto-config—use @ConditionalOnMissingBean on custom or exclude auto-config.

Auto-config not running?

Class not in AutoConfiguration.imports, condition failed, or excluded.

Spring Boot 2 vs 3 imports file?

Upgrade uses new AutoConfiguration.imports path—check third-party starters support Boot 3.

How many auto-config classes?

100+—you rarely read all; use debug report for one feature.

Test slice without full context?

@WebMvcTest, @DataJpaTest import subset—faster tests.

Custom starter next?

Custom Starter Extension packages your auto-config.