Spring Boot - Code Structure

Spring Boot does not enforce a fixed project structure, but organizing a project properly makes the application easier to develop, test, and maintain. Developers commonly organize Spring Boot applications by feature or by layer, depending on the project's size and requirements.

• A well-organized project separates responsibilities such as controllers, services, repositories, and entities.
• Spring Boot recommends placing the main application class in a root package to support component scanning.
• Projects can be organized by feature, by layer, or into multiple modules.

Package Structure in Spring Boot

Spring Boot provides flexibility in organizing application code. However, following certain package-organization practices helps prevent scanning issues and improves maintainability.

1. Avoid Using the Default Package

A class belongs to the default package when it does not contain a package declaration. Using the default package is discouraged because Spring Boot annotations such as @ComponentScan, @EntityScan, and @SpringBootApplication may cause unnecessary scanning of classes from application dependencies.

Instead, use a named package:

package com.gfg.demo;

Note: Follow Java's reverse-domain package naming convention, such as com.gfg.demo.

2. Place the Main Application Class in the Root Package

The main application class should be placed in a root package, with controllers, services, repositories, and other components organized into subpackages.

For example, if the root package is com.gfg.demo, all application components can be placed under it.

Example: MyApplication.java

package com.gfg.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Explanation:

• @SpringBootApplication enables Spring Boot's main configuration, component scanning, and auto-configuration.
• SpringApplication.run() starts the application and initializes the Spring application context.
• By default, component scanning starts from com.gfg.demo and includes its subpackages.

Keeping the main class in the root package helps Spring Boot discover application components without additional component-scan configuration.

Approaches to Organizing Spring Boot Code

There are two commonly used approaches for organizing classes in Spring Boot applications:

1. Structure by Feature

In a feature-based structure, classes related to a particular functionality are grouped into the same package.

For example, an e-commerce application may contain separate packages for customer management and order management. Each package contains the classes required for that feature.

Here,

The image shows a feature-based Spring Boot project structure in which classes are grouped according to their functionality.

• The customer package contains Customer.java, CustomerController.java, CustomerRepository.java, and CustomerService.java to manage customer-related operations.
• The order package contains the corresponding classes for handling order-related operations.
• MyApplication.java is placed in the root package (com.gfg.demo), allowing Spring Boot to discover components in its subpackages.

This structure keeps related classes together, making individual features easier to develop, test, and maintain.

Advantages:

• Related classes are grouped together, making them easier to locate and modify.
• Individual features can be developed, tested, and refactored independently.
• Changes to a feature generally involve fewer unrelated packages.
• Clear feature boundaries make future modularization easier.

When to Use: Feature-based organization is suitable for medium to large applications containing multiple business features.

2. Structure by Layer

In a layer-based structure, classes are organized according to their technical responsibilities. Controllers, services, repositories, and entities are placed in separate packages.

Example:

Here,

The image shows a layer-based Spring Boot project structure in which classes are grouped according to their technical responsibilities.

• The controller package handles incoming HTTP requests and responses.
• The service package contains application business logic.
• The repository package handles data access operations.
• The entity package contains classes representing application data.
• MyApplication.java is placed in the root package (com.gfg.demo) to enable component scanning across the subpackages.

This structure provides a clear separation of responsibilities and is commonly used in small to medium-sized Spring Boot applications.

Each layer has a specific responsibility:

Advantages:

• Provides a clear separation of technical responsibilities.
• Makes the code structure easy to understand for beginners.
• Keeps business logic separate from request handling and data access.
• Works well for smaller applications with limited functionality.

Limitations:

• Classes related to the same feature are distributed across different packages.
• Modifying one feature may require navigating multiple packages.
• Large applications may develop overcrowded controller, service, and repository packages.
• Extracting individual features into modules may require additional restructuring.

When to Use: Layer-based organization is suitable for small applications, learning projects, and applications with relatively simple business logic.

Difference Between Structure by Feature and Structure by Layer