Spring Boot & Spring Cloud
Spring Boot Explained: Starters, Auto-Configuration and Your First Application
Beginner9 min readReviewed by Mariem Ouled on Updated
After this guide you will understand what Spring Boot adds on top of the Spring Framework, how a starter and an auto-configuration class work together, how to read the condition evaluation report when a bean is missing, and how to write your first Boot 3 application without treating the framework as magic.
What you will learn
- Explain what Spring Boot adds on top of the Spring Framework and what it does not change
- Describe how starters, auto-configuration classes and conditions produce beans at startup
- Create and run a Spring Boot 3 application with Maven and understand its entry point
- Read the condition evaluation report to find out why an auto-configuration did or did not apply
- Override or exclude an auto-configuration safely by declaring your own bean
Spring Boot is the way most Java services are built today, and the reason is not a new programming model. Boot keeps the Spring Framework exactly as it is and removes the part that used to consume a project's first week: choosing compatible library versions, wiring the infrastructure beans, configuring a servlet container and writing the deployment descriptor. You add a dependency, Boot notices it, and a sensible configuration appears. This page explains the machinery behind that experience so you can predict what Boot will do, find out why it did something else, and override it when its opinion is not yours. Everything targets Spring Boot 3 on Java 17 or later.
What Boot adds and what it leaves alone
The Spring Framework gives you an inversion-of-control container, aspect-oriented programming, transaction management, Spring MVC and a long list of integrations. What it deliberately does not give you is an opinion about how to assemble them. A classic Spring application therefore declared a DataSource, a EntityManagerFactory, a transaction manager, a DispatcherServlet, message converters and a view resolver by hand, in XML or Java configuration, and packaged everything as a WAR for an external application server.
Spring Boot contributes four things on top of that foundation.
Dependency management. The spring-boot-dependencies bill of materials (BOM) pins the version of several hundred libraries that are known to work together. You declare spring-boot-starter-web without a version and inherit a coherent set.
Starters. A starter is an empty Maven or Gradle artifact whose only job is to pull in a curated group of dependencies for one capability: web, data, security, validation, testing.
Auto-configuration. A set of @Configuration classes that register infrastructure beans only when the right conditions hold: the library is on the classpath, no user bean of that type exists, a property is set.
Production features. An embedded servlet or reactive server so the application runs with java -jar, externalised configuration, and the Actuator module for health, metrics and management endpoints.
Nothing in that list changes how you write a service, a repository or a controller. If you can read a plain Spring application, you can read a Boot application; the difference is how much infrastructure configuration is visible in the source tree.
A first application
Generate a project from Spring Initializr (the website, the spring CLI, or the wizard built into IntelliJ IDEA, Eclipse and VS Code) with the Web dependency. Maven users get a pom.xml whose parent is spring-boot-starter-parent:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.5</version>
</parent>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
The parent POM supplies the BOM, sensible compiler and resource-filtering settings, and the plugin that repackages the build into an executable jar. If your organisation already has a corporate parent, import spring-boot-dependencies in dependencyManagement with <scope>import</scope> instead; you lose the plugin defaults but keep the version alignment.
The entry point is a single class:
package com.example.shop;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class ShopApplication {
public static void main(String[] args) {
SpringApplication.run(ShopApplication.class, args);
}
}
@RestController
class HelloController {
@GetMapping("/hello")
String hello() {
return "Hello from Spring Boot";
}
}
Run ./mvnw spring-boot:run (or java -jar target/shop-0.0.1-SNAPSHOT.jar after ./mvnw package) and Tomcat answers on port 8080. Nothing declared the servlet container, the DispatcherServlet, Jackson's JSON converter or the error page; auto-configuration did, because spring-boot-starter-web put the relevant classes on the classpath.
@SpringBootApplication is a composition of three annotations:
| Annotation | Effect |
|---|---|
@SpringBootConfiguration | Marks the class as a @Configuration and lets tests locate it automatically |
@EnableAutoConfiguration | Turns on the auto-configuration mechanism described below |
@ComponentScan | Scans the package of this class and its sub-packages for @Component, @Service, @Repository, @Controller and @Configuration |
The component-scan detail has a practical consequence: put the application class in your root package (com.example.shop), not in the default package and not in a sub-package such as com.example.shop.config. Classes outside the scanned tree are silently ignored, which is one of the most common "my bean is not found" surprises.
Starters: dependency bundles with a naming convention
Open spring-boot-starter-web in your IDE's dependency view and you will find no code, only transitive dependencies: spring-boot-starter (the core, logging and YAML support), spring-boot-starter-json (Jackson), spring-boot-starter-tomcat and the spring-web/spring-webmvc framework modules. Starters exist so that "I want to build a web application" is one line rather than eight, and so that swapping a technology is a matter of exclusions: exclude spring-boot-starter-tomcat, add spring-boot-starter-jetty, and the embedded server changes with no code edits.
Official starters are named spring-boot-starter-*. The reference documentation asks third parties to use the reverse pattern, acme-spring-boot-starter, so that the spring-boot-starter- prefix stays reserved for the Spring team. That convention tells you at a glance whether a starter is maintained by the project or by a community.
A few starters worth knowing early:
| Starter | What it brings |
|---|---|
spring-boot-starter-web | Spring MVC, Jackson, embedded Tomcat |
spring-boot-starter-webflux | Reactive web stack on Reactor Netty |
spring-boot-starter-data-jpa | Spring Data JPA, Hibernate, HikariCP connection pool |
spring-boot-starter-validation | Jakarta Bean Validation with Hibernate Validator |
spring-boot-starter-security | Spring Security with a secure-by-default configuration |
spring-boot-starter-actuator | Health, metrics and management endpoints |
spring-boot-starter-test | JUnit 5, AssertJ, Mockito, Spring Test, JSON assertions |
Notice that spring-boot-starter-validation is separate from -web. That split happened in Boot 2.3; if @Valid seems to do nothing in a fresh project, the missing starter is usually the cause.
How auto-configuration works
Auto-configuration is ordinary Spring Java configuration with two additions: a registration file that lists the candidate classes, and conditions that decide whether each one applies.
Registration
Since Boot 2.7, and exclusively since 3.0, auto-configuration classes are listed, one fully qualified name per line, in a resource named META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports inside the jar that provides them. The older spring.factories key for auto-configuration was removed in 3.0; a library that still relies on it will not be picked up. @EnableAutoConfiguration reads every such file on the classpath and imports the classes it finds. The spring-boot-autoconfigure jar alone ships well over a hundred.
Conditions
Each class, and often each @Bean method inside it, carries conditions from the org.springframework.boot.autoconfigure.condition package:
| Condition | Applies when |
|---|---|
@ConditionalOnClass / @ConditionalOnMissingClass | A class is (or is not) on the classpath |
@ConditionalOnBean / @ConditionalOnMissingBean | A bean of a type or name is (or is not) already defined |
@ConditionalOnProperty | A property has a given value, or is absent with matchIfMissing |
@ConditionalOnWebApplication / @ConditionalOnNotWebApplication | The application is (or is not) a servlet or reactive web app |
@ConditionalOnResource | A resource such as a file exists on the classpath |
@ConditionalOnExpression | A SpEL expression evaluates to true |
@ConditionalOnMissingBean is the one that makes Boot polite. Auto-configuration classes are processed after your own @Configuration classes, so whenever you declare a bean of a type Boot would otherwise create, Boot's version backs off. That is why the standard advice for customising Boot is "define the bean yourself" rather than "turn Boot's bean off".
Here is a simplified version of what the data-source auto-configuration looks like, written the way you would write your own:
@AutoConfiguration
@ConditionalOnClass(DataSource.class) // only if JDBC support is present
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {
@Bean
@ConditionalOnMissingBean // back off if the app declared one
@ConditionalOnProperty(prefix = "spring.datasource", name = "url")
DataSource dataSource(DataSourceProperties properties) {
HikariDataSource ds = new HikariDataSource();
ds.setJdbcUrl(properties.getUrl());
ds.setUsername(properties.getUsername());
ds.setPassword(properties.getPassword());
return ds;
}
}
@AutoConfiguration (introduced in 2.7) replaces @Configuration for these classes. It disables proxying of bean methods, which auto-configuration does not need, and accepts before/after attributes for ordering relative to other auto-configurations. Ordering matters because a condition such as @ConditionalOnBean is only meaningful if the bean it looks for has had a chance to be registered first.
Writing your own
Teams that maintain several services usually end up with a shared library that configures common concerns the same way everywhere: a tuned ObjectMapper, an HTTP client with tracing headers, a standard error handler. Packaging that as an auto-configuration rather than a base class keeps consuming services free to override any piece:
acme-http-spring-boot-starter/
└── src/main/resources/META-INF/spring/
└── org.springframework.boot.autoconfigure.AutoConfiguration.imports
(contains: com.acme.http.AcmeRestClientAutoConfiguration)
@AutoConfiguration
@ConditionalOnClass(RestClient.class)
public class AcmeRestClientAutoConfiguration {
@Bean
@ConditionalOnMissingBean
RestClient.Builder acmeRestClientBuilder() {
return RestClient.builder()
.defaultHeader("X-Acme-Caller", "shop");
}
}
Keep auto-configuration classes out of the @ComponentScan range of applications that use them; if a scan picks them up as ordinary @Configuration classes, the ordering guarantee is lost and @ConditionalOnMissingBean can behave unexpectedly. Placing the library in its own package hierarchy (com.acme.http, not com.example.shop.*) is enough.
Finding out what happened
Auto-configuration is deterministic but not always obvious, and Boot gives you two ways to see its decisions.
Start the application with --debug (or debug=true in application.properties) and read the condition evaluation report in the log. It has three parts: positive matches (auto-configurations that applied, with the condition that let them in), negative matches (those that did not, with the condition that failed), and exclusions. A typical negative entry reads like this:
DataSourceAutoConfiguration:
Did not match:
- @ConditionalOnClass did not find required class 'javax.sql.DataSource'
That line tells you exactly which dependency to add. When a bean is unexpectedly missing, this report answers the question faster than reading source.
If the Actuator starter is present, the same information is available at runtime from the conditions endpoint once you expose it, which is handy in environments where you cannot restart with a flag.
Overriding and excluding
Three levels of control exist, from gentlest to bluntest.
- Set a property. Most auto-configurations are driven by
@ConfigurationPropertiesclasses, soserver.port,spring.datasource.urlorspring.jackson.default-property-inclusionchange behaviour without touching code. The full list is in the "Common Application Properties" appendix of the reference documentation. - Declare the bean yourself. Because of
@ConditionalOnMissingBean, your bean replaces Boot's. If you need Boot's bean plus a tweak, look for a customizer hook:WebMvcConfigurer,Jackson2ObjectMapperBuilderCustomizer,RestClientCustomizer,TomcatConnectorCustomizerand many others exist precisely so that you can adjust without replacing. - Exclude the auto-configuration.
@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)or thespring.autoconfigure.excludeproperty removes it entirely. Use this when the library is on the classpath for a reason unrelated to the feature Boot infers, for example a JDBC driver that is only used by a build-time tool.
Reach for level 3 rarely. An excluded auto-configuration often has dependants (DataSourceAutoConfiguration feeds JPA, JDBC templates, Flyway, health indicators), and excluding one can cascade into a chain of missing beans that is harder to debug than the original problem.
Common mistakes
Application class in the wrong package. Components in a sibling or parent package are never scanned. Either move the class to the root package or add scanBasePackages to @SpringBootApplication; the former is cleaner.
Fighting the parent POM. Overriding a managed version (say, forcing a newer Hibernate) is legitimate but should be done through the property the BOM exposes (<hibernate.version>), not by declaring a version on the dependency, so that transitive alignment still holds. Read the release notes of the library first; the BOM's version is the one Boot's auto-configuration was tested with.
Assuming a starter equals a feature. Adding spring-boot-starter-data-jpa without a database driver and a spring.datasource.url fails at startup with a message about an embedded database. Boot can only configure what the classpath and properties describe.
Mixing javax.* and jakarta.*. A Boot 3 application with a dependency that still uses javax.servlet or javax.persistence compiles but fails at runtime with NoClassDefFoundError or unmapped entities. Check every third-party library for a Jakarta-compatible version before upgrading.
Treating --debug as a log level. The flag enables the condition report and DEBUG logging for a few core loggers, not for your own packages; use logging.level.com.example=DEBUG for that.
Key takeaways
- Spring Boot is the Spring Framework plus dependency management, starters, auto-configuration and production features; the programming model is unchanged.
- A starter is a dependency bundle; an auto-configuration is a conditional
@Configurationclass registered inMETA-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. - Conditions such as
@ConditionalOnClassand@ConditionalOnMissingBeanmake Boot's beans back off whenever you declare your own, which is the intended way to customise it. @SpringBootApplicationcombines configuration, auto-configuration and component scanning from the class's package downward, so its location matters.- When a bean is missing or unexpected, the condition evaluation report (
--debug, or the Actuatorconditionsendpoint) tells you which condition decided. - Prefer properties and customizer beans over excluding auto-configurations; exclusions cascade.
Sources and further reading
Frequently asked questions
- Is Spring Boot a different framework from Spring?
- No. Spring Boot is a layer on top of the Spring Framework. Every bean, annotation and abstraction you use in a Boot application (dependency injection, @Transactional, Spring MVC, Spring Data) comes from the framework and its portfolio projects. Boot adds opinionated dependency management, auto-configuration, an embedded server and production features such as Actuator.
- Why does Spring Boot 3 require Java 17 and the jakarta.* packages?
- Spring Boot 3 is built on Spring Framework 6, which set Java 17 as its baseline and moved from Java EE to Jakarta EE 9+. Jakarta EE 9 renamed every javax.* API package to jakarta.*, so servlet, persistence, validation and other imports change. Libraries that still ship javax.* classes will not work with Boot 3 until they are upgraded.
- How do I know which auto-configurations were applied to my application?
- Start the application with the debug property set (for example --debug on the command line or debug=true in application.properties). Boot logs a condition evaluation report listing positive matches, negative matches and the exact condition that decided each one. With Actuator you can read the same data at runtime from the conditions endpoint.
- If I define my own DataSource bean, will Boot still create one?
- No. Boot's DataSourceAutoConfiguration is guarded by @ConditionalOnMissingBean, and user configuration is processed before auto-configuration. Your bean wins and the auto-configured one is skipped. This back-off behaviour is the standard way to customise Boot: define the bean yourself rather than fighting the defaults.
- Does auto-configuration slow down startup?
- Each auto-configuration class is evaluated at startup, but most are rejected almost immediately by a cheap @ConditionalOnClass check that fails before the class is even loaded. What dominates startup time is the work of the beans that do get created (opening connection pools, building Hibernate metamodels, starting Tomcat), not the condition evaluation itself.