Spring boot

[richouan]

🏷️ Discussion Type

Question

Body

I'm learning Spring Boot while building a project with a REST API. I'm trying to understand how to keep controllers, services, and repositories well organized without overengineering things. What helped you understand this architecture in practice?

Guidelines

• I have read and understood this category's guidelines before making this post.

[aymansalkhatib]

What made it click for me was giving each layer one clear job and checking every class against that, instead of following a diagram:

Controller = HTTP only. Map the URL, validate input (@Valid), call one service method, return a DTO and a status. No business rules and no repository calls. If a controller method is longer than ~10 lines, logic is leaking into it.

Service = the use cases. "Place order", "cancel subscription". This is where the rules live, and where @Transactional goes, because one use case = one transaction. It's the only layer that talks to repositories.

Repository = data access. Usually just a Spring Data interface (interface OrderRepository extends JpaRepository<Order, Long>) plus a few query methods. No logic.

A few habits that prevent most of the mess without overengineering:

1. Package by feature, not by layer. order/OrderController, order/OrderService, order/OrderRepository, order/Order together, instead of controllers/, services/, repositories/ folders. Everything about one feature is in one place, and you can keep classes package-private.
2. Don't return entities from controllers. Use small record DTOs (record OrderResponse(Long id, String status)). This avoids lazy-loading surprises, accidental exposure of fields, and coupling your API to your tables.
3. Skip OrderService interface + OrderServiceImpl unless you really have two implementations. Spring doesn't need the interface, and it doubles the files for nothing.
4. One place for errors: throw domain exceptions (OrderNotFoundException) from services and map them once in a @RestControllerAdvice that returns ProblemDetail. Controllers then never need try/catch.
5. Test by layer: @WebMvcTest for controllers (service mocked), plain unit tests for services, @DataJpaTest for custom queries. If a test is hard to write, the class usually has two jobs.

@RestController
@RequestMapping("/orders")
class OrderController {
    private final OrderService orders;
    OrderController(OrderService orders) { this.orders = orders; }

    @PostMapping
    ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest req) {
        OrderResponse created = orders.create(req);
        return ResponseEntity.created(URI.create("/orders/" + created.id())).body(created);
    }
}

@Service
class OrderService {
    private final OrderRepository repo;
    OrderService(OrderRepository repo) { this.repo = repo; }

    @Transactional
    OrderResponse create(CreateOrderRequest req) {
        Order order = repo.save(new Order(req.customerId(), req.items()));
        return new OrderResponse(order.getId(), order.getStatus().name());
    }
}

Good references: the official Building REST services with Spring tutorial walks through exactly this structure step by step, and if the project grows, Spring Modulith builds on the package-by-feature idea and verifies the boundaries between features for you.

[cachewraith]

What helped me was thinking of it like a restaurant:

• Controller = waiter. Takes the request, passes it on, returns the response. No business logic.
• Service = kitchen. All the real rules live here.
• Repository = pantry. Only talks to the database.

Example: POST /orders

1. Controller receives the OrderRequest and calls orderService.create(request).
2. Service checks the user exists, checks stock, calculates the total, then calls orderRepository.save(order).
3. Controller returns 201 Created with an OrderResponse.

If you ever see an if about a business rule inside the controller, it belongs in the service.

To avoid overengineering:

• Skip interfaces like OrderService + OrderServiceImpl until you actually need a second implementation.
• Just extend JpaRepository, no extra wrapper around it.
• Use DTOs for request/response so you don't leak entities.
• Group packages by feature (order/, user/) instead of one giant controllers/ and services/ folder.
• Don't add a layer until the code starts to hurt.

Build it small first. You'll feel when something is in the wrong place, and moving it later is easy.

[sapuCodes]

here’s what helped me as a beginner,

Controller: only handles HTTP (receive the request, call the service, return a response). No business logic.
Service: holds the actual logic and rules.
Repository: only talks to the database.

if you’re writing a business rule if inside a controller, move it to the service.

To avoid overengineering, skip things like UserService + UserServiceImpl until you actually need two implementations, and use DTOs instead of returning entities directly. Start simple and refactor only when it starts to hurt.

Building a small CRUD project (like a to-do API) end to end made me understand it. Good luck!