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:

  1. Spring Boot scans packages.
  2. Detects @RestController.
  3. Detects JpaRepository.
  4. Configures Hibernate.
  5. Creates repository implementation.
  6. Starts embedded Tomcat.
  7. Registers REST endpoints.
  8. 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

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!