Auto-configuration, starters and conditions that back off

Add spring-boot-starter-web to a build and, with no configuration at all, the application starts an embedded Tomcat, serves JSON through Jackson and routes requests through Spring MVC. Two separate mechanisms make that happen.

A starter is only a dependency descriptor: a POM that pulls in a curated, version-aligned set of libraries. spring-boot-starter-web brings Spring MVC, an embedded Tomcat and Jackson; it contains almost no code of its own.

Auto-configuration is the code. @SpringBootApplication combines @SpringBootConfiguration, @ComponentScan and @EnableAutoConfiguration. The last one loads a list of candidate configuration classes — in Spring Boot 3, every class named in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports on the classpath — and evaluates the conditions on each one before registering any of its beans.

@AutoConfiguration
@ConditionalOnClass(ObjectMapper.class)
public class MyJacksonAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    ObjectMapper objectMapper() { return new ObjectMapper(); }
}

The conditions you will meet

• @ConditionalOnClass — apply only if a class is on the classpath. This is how adding a dependency switches a feature on.
• @ConditionalOnMissingBean — create this bean only if the context does not already contain a bean of that type. This is how your own bean replaces Boot's.
• @ConditionalOnProperty — apply depending on a property's value, for a feature flag such as @ConditionalOnProperty(name = "acme.audit.enabled", havingValue = "true").
• Others: @ConditionalOnBean, @ConditionalOnWebApplication, @ConditionalOnResource.

Why your bean wins

Auto-configuration classes are processed after your own configuration and scanned components. By the time Boot evaluates @ConditionalOnMissingBean on its ObjectMapper, yours is already registered, so Boot's backs off. The model below evaluates three candidates against a classpath and the user's own beans, the way the conditions report describes them.

The same rule explains why the order matters between auto-configurations: a missing-bean check sees only what has been registered so far. Boot orders its own classes with @AutoConfiguration(after = ...), and its documentation recommends using the bean conditions only in auto-configuration classes, where that ordering is controlled.

Seeing and changing the decisions

Start the application with --debug (or debug=true in application.properties) and Boot logs a conditions evaluation report: every candidate, which conditions matched, and why the others did not. With Actuator, /actuator/conditions exposes the same data. To switch a candidate off entirely use @SpringBootApplication(exclude = DataSourceAutoConfiguration.class) or the spring.autoconfigure.exclude property.

A custom starter follows the same pattern: an autoconfigure module with an @AutoConfiguration class listed in the imports file, guarded by conditions, and a starter POM that depends on it. Third-party starters are named acme-spring-boot-starter; the spring-boot-starter-* prefix is reserved for Spring Boot's own.

Common mistakes

• Declaring your own ObjectMapper bean to change one setting: Boot's backs off completely, and with it go Boot's defaults, the spring.jackson.* properties and every builder customizer. Customise through the properties or a Jackson2ObjectMapperBuilderCustomizer bean instead; customizers without an run after the properties have been applied.