If you’ve ever started a Java project, you probably know how much configuration is usually required. You need to configure XML files, register beans, set up component scanning, define database connections, and configure the web server before writing any business logic.
Imagine buying a new smartphone. Instead of manually configuring Wi-Fi, camera settings, keyboard, language, notifications, and apps one by one, the phone already comes with sensible defaults that work for most people. You simply turn it on and start using it.
That’s exactly what Convention over Configuration in Spring Boot does.
Instead of asking developers to configure every small detail, Spring Boot follows a set of conventions (standard rules). If your project follows these conventions, Spring Boot automatically configures everything for you.
This approach dramatically reduces boilerplate code, speeds up development, and lets developers focus on building features instead of writing configuration files.
In this guide, you’ll learn:
- What Convention over Configuration in Spring Boot means
- Why it exists
- How Spring Boot automatically configures applications
- Practical Java 21 examples
- Complete REST API setup
- cURL requests and responses
- Best practices followed in production
What is Convention over Configuration?
Convention over Configuration (CoC) is a software development principle where a framework assumes sensible default settings instead of requiring developers to configure everything manually.
Instead of writing:
- XML configuration
- Bean definitions
- Servlet configuration
- DispatcherServlet setup
- Embedded server configuration
Spring Boot automatically configures them based on:
- Project dependencies
- Package structure
- Class annotations
- Configuration properties
You only customize what is different from the defaults.
Real-Life Analogy
Think of booking a hotel room.
When you enter your room, you expect:
- A bed
- Lights
- Bathroom
- Air conditioning
- Television
You don’t ask the hotel to install these every time.
These are conventions.
Only if you want something special—like an extra bed or baby crib—you make a request.
Spring Boot works exactly the same way.
It provides sensible defaults and only asks you to configure exceptions.
Why Was Convention over Configuration Introduced?
Before Spring Boot, creating a Spring application involved configuring:
- web.xml
- DispatcherServlet
- Component Scan
- Bean definitions
- Tomcat deployment
- Database configuration
- Logging configuration
A simple REST API could require hundreds of lines of configuration.
Spring Boot eliminated most of this work using Convention over Configuration in Spring Boot.
How Convention over Configuration Works
Spring Boot makes assumptions based on your project.
For example:
If your project contains:
spring-boot-starter-web
Enter fullscreen mode Exit fullscreen mode
Spring Boot assumes:
- You are building a web application
- Tomcat should start automatically
- Jackson should convert JSON
- Spring MVC should be enabled
- DispatcherServlet should be registered
You configure nothing.
Another Example
If Spring Boot finds:
spring-boot-starter-data-jpa
Enter fullscreen mode Exit fullscreen mode
It automatically configures:
- EntityManager
- Hibernate
- Transaction Manager
- JPA Repository
- DataSource
Again…
No XML required.
Common Spring Boot Conventions
1. Main Application Class
Spring Boot expects the main class to be at the root package.
Example:
com.example.demo
├── DemoApplication
├── controller
├── service
├── repository
Enter fullscreen mode Exit fullscreen mode
Component scanning starts from here automatically.
2. application.properties
Spring Boot expects configuration inside
src/main/resources/application.properties
Enter fullscreen mode Exit fullscreen mode
Example:
server.port=8080
Enter fullscreen mode Exit fullscreen mode
No XML.
3. Controller Annotation
Any class annotated with
@RestController
Enter fullscreen mode Exit fullscreen mode
automatically becomes a REST endpoint.
No servlet registration required.
4. Repository Interfaces
Simply write:
interface UserRepository extends JpaRepository<User, Long>
Enter fullscreen mode Exit fullscreen mode
No implementation class needed.
Spring Boot generates it.
Benefits of Convention over Configuration
Faster Development
Less setup.
More coding.
Cleaner Codebase
No unnecessary XML files.
Easier Learning Curve
Beginners don’t need to understand every Spring configuration.
Better Productivity
Teams spend time building business logic instead of configuring frameworks.
Easier Maintenance
Standard project structures are easier for everyone to understand.
Use Cases
Convention over Configuration in Spring Boot is commonly used for:
- REST APIs
- Microservices
- Banking Applications
- E-commerce Platforms
- Cloud-native Applications
- Enterprise Java Applications
- Backend Services
- Internal APIs
Complete Example 1 — Spring Boot REST API (Java 21)
Project Structure
demo
│
├── controller
│ HelloController.java
│
├── DemoApplication.java
│
└── resources
application.properties
Enter fullscreen mode Exit fullscreen mode
application.properties
spring.application.name=demo
server.port=8080
Enter fullscreen mode Exit fullscreen mode
DemoApplication.java
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* Main application.
*
* @SpringBootApplication combines:
* - @Configuration
* - @EnableAutoConfiguration
* - @ComponentScan
*
* Thanks to Convention over Configuration,
* no additional XML configuration is needed.
*/
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
Enter fullscreen mode Exit fullscreen mode
HelloController.java
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Simple REST Controller.
*
* Spring Boot automatically detects this class
* because it follows the package convention.
*/
@RestController
public class HelloController {
@GetMapping("/hello")
public MessageResponse hello() {
return new MessageResponse(
"Hello from Spring Boot!",
"Convention over Configuration makes development easier."
);
}
/**
* Java 21 Record used as DTO.
*/
public record MessageResponse(String message, String description) {
}
}
Enter fullscreen mode Exit fullscreen mode
Run Application
./mvnw spring-boot:run
Enter fullscreen mode Exit fullscreen mode
or
mvn spring-boot:run
Enter fullscreen mode Exit fullscreen mode
Test API
cURL Request
curl --request GET http://localhost:8080/hello
Enter fullscreen mode Exit fullscreen mode
Response
{
"message": "Hello from Spring Boot!",
"description": "Convention over Configuration makes development easier."
}
Enter fullscreen mode Exit fullscreen mode
Notice:
We never configured:
- Tomcat
- DispatcherServlet
- JSON converter
- Component scan
Spring Boot handled everything automatically.
Complete Example 2 — Auto Configuration with Spring Data JPA (Java 21)
Entity
package com.example.demo.entity;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
/**
* User entity.
*/
@Entity
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String name;
protected User() {
// Required by JPA
}
public User(String name) {
this.name = name;
}
public Long getId() {
return id;
}
public String getName() {
return name;
}
}
Enter fullscreen mode Exit fullscreen mode
Repository
package com.example.demo.repository;
import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;
/**
* No implementation required.
* Spring Boot automatically creates it.
*/
public interface UserRepository extends JpaRepository<User, Long> {
}
Enter fullscreen mode Exit fullscreen mode
Controller
package com.example.demo.controller;
import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/users")
public class UserController {
private final UserRepository repository;
public UserController(UserRepository repository) {
this.repository = repository;
}
/**
* Creates a new user.
*/
@PostMapping
public User create(@RequestBody CreateUserRequest request) {
return repository.save(new User(request.name()));
}
/**
* Java 21 Record for request body.
*/
public record CreateUserRequest(String name) {
}
}
Enter fullscreen mode Exit fullscreen mode
cURL Request
curl --request POST http://localhost:8080/users \
--header "Content-Type: application/json" \
--data '{
"name":"Alex"
}'
Enter fullscreen mode Exit fullscreen mode
Response
{
"id": 1,
"name": "Alex"
}
Enter fullscreen mode Exit fullscreen mode
Notice:
There is:
- No repository implementation
- No SQL configuration in Java code
- No bean creation
- No XML
Everything is created automatically.
Behind the Scenes
When the application starts:
- Spring Boot scans packages.
- Detects
@RestController. - Detects
JpaRepository. - Configures Hibernate.
- Creates repository implementation.
- Starts embedded Tomcat.
- Registers REST endpoints.
- Configures JSON serialization using Jackson.
All automatically.
Best Practices
1. Follow the Standard Package Structure
Place your main application class at the root package so component scanning works automatically.
2. Override Defaults Only When Necessary
Avoid unnecessary configuration. Spring Boot’s defaults are optimized for most applications.
3. Use Starter Dependencies
Use Spring Boot Starter dependencies such as:
- spring-boot-starter-web
- spring-boot-starter-data-jpa
- spring-boot-starter-validation
These starters enable the appropriate auto-configuration.
4. Keep Configuration in application.properties or application.yml
Store environment-specific settings in configuration files instead of hardcoding values.
5. Don’t Fight the Framework
A common mistake is trying to manually configure components that Spring Boot already manages. Understand the defaults first before customizing behavior.
Common Mistakes
- Placing the main application class in the wrong package, preventing component scanning.
- Adding unnecessary manual bean definitions that duplicate auto-configured beans.
- Excluding auto-configuration classes without understanding the impact.
- Using outdated XML configuration alongside Spring Boot conventions.
- Ignoring Spring Boot’s startup logs, which explain what has been auto-configured.
Conclusion
Convention over Configuration in Spring Boot is one of the biggest reasons why Spring Boot has become the preferred framework for modern Java programming. Instead of spending hours configuring infrastructure, developers can focus on writing business logic.
By following standard project structures, using starter dependencies, and relying on Spring Boot’s sensible defaults, you can build production-ready applications with significantly less code and configuration.
Whether you’re just starting to learn Java or building enterprise microservices, understanding this principle will help you write cleaner, faster, and more maintainable applications.
Further Reading
- Oracle Java Documentation: https://docs.oracle.com/en/java/
- Spring Boot Reference Documentation: https://docs.spring.io/spring-boot/docs/current/reference/html/
- Spring Framework Documentation: https://docs.spring.io/spring-framework/reference/
Frequently Asked Questions (FAQ)
Is Convention over Configuration the same as Auto Configuration?
No. Convention over Configuration is a design philosophy that favors sensible defaults, while Auto Configuration is the Spring Boot feature that implements many of those defaults automatically based on your application’s dependencies and environment.
Can I override Spring Boot’s default behavior?
Yes. Spring Boot allows you to override almost every default using configuration properties, custom beans, or annotations. The framework provides defaults but does not prevent customization.
Does Convention over Configuration reduce flexibility?
Not at all. It reduces unnecessary setup for common scenarios while still allowing complete customization when your application’s requirements differ from the defaults.
Is this approach suitable for enterprise applications?
Absolutely. Most enterprise Spring Boot applications rely heavily on Convention over Configuration because it improves consistency, reduces boilerplate, and makes projects easier for teams to maintain.
Call to Action
Did this guide help you understand Convention over Configuration in Spring Boot? Share your thoughts or questions in the comments below. If there’s another Java or Spring Boot topic you’d like to explore, let us know—we’d be happy to cover it in a future article. Happy coding!
답글 남기기