BackendBench
Coffee

Unravel › Java concepts › Spring and Boot

Spring

Spring Boot auto-configuration and starters

Spring Boot looks at the libraries on your classpath and your properties, and configures sensible beans for you (a web server, a data source, a JSON mapper) unless you define your own.

🔎 Unravel this examplePrerequisites (1)

Learn these first

Spring beans and dependency injection

At a glance

Mental model

A furnished rental flat: the basics are already there when you move in (bed, kettle, lamp).

What happens, in order
  1. 1SpringApplication.run(App.class, args) creates the application context@SpringBootApplication on the main class combines three things: @Configuration, @ComponentScan (find your beans below this package) and @EnableAutoConfiguration.
  2. 2A starter such as spring-boot-starter-web is only a dependency bundleAdding it puts Tomcat, Spring MVC and Jackson on the classpath, and that is what the auto-configuration reacts to.
  3. 3Auto-configuration classes are ordinary @Configuration classes guarded by conditions: @ConditionalOnClass (a library is present), @ConditionalOnMissingBean (you did not define your own) and @ConditionalOnProperty (a setting is on)
  4. 4Your own bean of the same type always wins, because the auto-configured one backs offThis is how you replace the default ObjectMapper or DataSource without disabling anything.
Remember
Watch out
Putting the main class in a sub-package so scanning misses sibling packagesDefining a bean of the wrong type and wondering why the default did not back offAdding a starter and not realising it changes behaviour just by being on the classpathDisabling auto-configuration instead of overriding one bean
Example (highlighted lines explain it)
@SpringBootApplicationpublic class ShopApplication {    public static void main(String[] args) {        SpringApplication.run(ShopApplication.class, args);    }    @Bean    @ConditionalOnMissingBean    public Clock clock() {        return Clock.systemUTC();    }}
  1. line 4 uses SpringApplication, the core of Spring Boot auto-configuration and starters
  2. line 8 uses ConditionalOnMissingBean, the core of Spring Boot auto-configuration and starters
Read the full explanation (about 2 min)

Spring Boot looks at the libraries on your classpath and your properties, and configures sensible beans for you (a web server, a data source, a JSON mapper) unless you define your own.

A mental model

A furnished rental flat: the basics are already there when you move in (bed, kettle, lamp). If you bring your own kettle, the landlord quietly removes theirs. Boot is the landlord and your beans are your own furniture.

How it works

SpringApplication.run(App.class, args) creates the application context. @SpringBootApplication on the main class combines three things: @Configuration, @ComponentScan (find your beans below this package) and @EnableAutoConfiguration.

A starter such as spring-boot-starter-web is only a dependency bundle. Adding it puts Tomcat, Spring MVC and Jackson on the classpath, and that is what the auto-configuration reacts to.

Auto-configuration classes are ordinary @Configuration classes guarded by conditions: @ConditionalOnClass (a library is present), @ConditionalOnMissingBean (you did not define your own) and @ConditionalOnProperty (a setting is on).

Your own bean of the same type always wins, because the auto-configured one backs off. This is how you replace the default ObjectMapper or DataSource without disabling anything.

Going deeper

Start the application with --debug (or debug=true) to print the conditions report: which auto-configurations matched and why the others did not. It is the first tool to reach for when "Boot did not configure my thing".

Exclude an auto-configuration with @SpringBootApplication(exclude = DataSourceAutoConfiguration.class) or spring.autoconfigure.exclude. Needed, for example, when a library is on the classpath but you do not want its default setup.

Component scanning only covers the main class package and below. A controller placed in a sibling package is silently ignored, which looks like a mysterious 404.

Under the hood

Candidate auto-configurations are listed in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports inside each starter jar. An import selector loads them late (after your own configuration) so that the ConditionalOnMissingBean checks can see what you defined.

Common mistakes

  • Putting the main class in a sub-package so scanning misses sibling packages.
  • Defining a bean of the wrong type and wondering why the default did not back off.
  • Adding a starter and not realising it changes behaviour just by being on the classpath.
  • Disabling auto-configuration instead of overriding one bean.

How Unravel recognises it

When you paste code, Unravel looks for these signs of spring boot auto-configuration and starters. Spotting them yourself is a good habit when you read unfamiliar code:

Part of a learning path

Related concepts

Spring configuration propertiesSpring@Configuration, @Bean and bean wiringSpring

Frequently asked questions

What is Spring Boot auto-configuration and starters?

Spring Boot looks at the libraries on your classpath and your properties, and configures sensible beans for you (a web server, a data source, a JSON mapper) unless you define your own.

What are the most common mistakes with Spring Boot auto-configuration and starters?

Putting the main class in a sub-package so scanning misses sibling packages. Defining a bean of the wrong type and wondering why the default did not back off. Adding a starter and not realising it changes behaviour just by being on the classpath. Disabling auto-configuration instead of overriding one bean.

How can I see Spring Boot auto-configuration and starters in real code?

Paste your own Java into Unravel and it will point out where spring boot auto-configuration and starters appears, explain how it works at the detail level you choose, and draw the flow of the code around it.