Building Services with @Service

The Why: Understanding Layered Architecture

Most well-structured Spring applications are organized into layers, each with a distinct responsibility. The most common and effective pattern is the three-layer architecture:

1. Presentation Layer (Controller): Its only job is to handle HTTP requests and responses. It validates incoming data, calls the appropriate service method to do the actual work, and formats the result into an HTTP response. It should contain no business logic.
2. Service Layer (Business Logic): This is the heart of the application. It contains the core business rules and logic. It orchestrates operations, such as calling one or more repositories to fetch or save data, interacting with other services, or performing complex calculations.
3. Data Access Layer (Repository): This layer's sole responsibility is to communicate with the database. It provides a simple, data-centric API for creating, reading, updating, and deleting (CRUD) data.

To get a clear overview of these responsibilities, let's watch a short video.

This separation provides several key benefits that are crucial for building scalable and maintainable systems.

The How: Implementing the Service Layer

Now that we understand the "why," let's move to the "how." Implementing a service layer in Spring is straightforward. It involves two main steps:

1. Creating a service class and annotating it with @Service.
2. Injecting the service into the controller.

The @Service Annotation

The @Service annotation is one of Spring's stereotype annotations (along with @Component, @Repository, and @Controller). Its primary function is to mark a Java class as a bean—an object that Spring's Inversion of Control (IoC) container will instantiate and manage.

While you could technically use the generic @Component annotation, using @Service is a best practice because it clearly communicates the class's role in the application architecture. It tells other developers, "This class contains business logic."

Refactoring from a Fat Controller

The best way to understand the process is to see it in action. We'll follow a common refactoring path: moving business logic out of a "fat controller" and into a lean, focused service class.

Let's watch a video that demonstrates this exact refactoring process.

As you saw in the video, the result is a controller that is "thin" and a service that contains the actual logic.

Here is a look at a more detailed service implementation that includes business rules.

This UserServiceImpl is a perfect example of what a service layer component should do. The controller that calls createUser doesn't need to know about any of these details; it simply calls the service and trusts it to do the right thing.

Best Practices and Common Pitfalls

Adopting a layered architecture is a huge step forward, but there are some common mistakes to avoid.

To reinforce this, here is one more clear example. In the code below, from the "Controller-Service-Repository" article, notice how the service adds value by handling the Optional returned by the repository and throwing a custom CatNotFoundException if the Optional is empty. This is business logic that protects the controller from persistence-layer details.

// From the "Controller-Service-Repository" article (resource [LINK](https://tom-collings.medium.com/controller-service-repository-16e29a4684e5))
@Service
public class CatService {

    private CatRepository catRepository;

    public CatService(CatRepository catRepository) {
        this.catRepository = catRepository;
    }

    public Cat findById(long id) throws CatNotFoundException {
        // Business logic: translate the repository's Optional into a concrete
        // object or a business-specific exception.
        Optional<Cat> oCat = catRepository.findById(id);
        if (oCat.isEmpty()) {
            throw new CatNotFoundException();
        }
        return oCat.get();
    }
}

This is a great example of a service that isn't "anemic." It performs a crucial translation between the data layer and the layers above it.

Conclusion

In this lesson, we established a robust structure for our application by introducing a service layer. This is a foundational pattern that you will use in virtually every Spring application you build.

Key Takeaways:

• Layered Architecture separates an application into a Presentation (Controller), Service (Business), and Data Access (Repository) layer.
• Separation of Concerns is the guiding principle: controllers handle web concerns, services handle business logic, and repositories handle data persistence.
• The @Service annotation marks a class as a service layer component, making it a Spring-managed bean.
• Business logic should be moved out of controllers and into service classes. Controllers then become "thin" by delegating calls to injected service beans.
• A good service layer adds value by orchestrating operations, enforcing business rules, and handling transactions, avoiding the "anemic service" anti-pattern.

You now have the tools to structure the core logic of your application in a way that is clean, testable, and maintainable.

In our next lesson, we will continue to refine our application's internal structure. We'll tackle a common challenge: the data model used by our API (@RestController) is often different from the data model used by our database (@Entity). We'll learn how to implement Data Transfer Objects (DTOs) to decouple API models from data models, a critical technique for building flexible and robust APIs.