Vaibhav More Logo
VAIBHAVMORE
Enterprise Backend
5 min readJun 10, 2025

Clean Architecture in Spring Boot 3: Enterprise DTO Mappings, Exception Advisers, and Multi-Tier Validation

Reflections from shipping production microservices at HCL Technologies: patterns for maintainable, type-safe backend systems.

VM

Vaibhav More

Full-Stack Developer & Ex-Intern @ HCL Tech

#Spring Boot#Java 21#Clean Architecture#REST APIs#HCL Tech

During my Full-Stack Engineering internship at HCL Technologies, one lesson stood above all others: in enterprise systems with dozens of developers contributing to the same monorepo, code readability and architectural boundaries are paramount. Exposing JPA entity models directly to controllers inevitably leads to circular serialization leaks, lazy-loading exceptions, and security vulnerabilities.

The Danger of Entity Leaks & Why Java 21 Records Are Perfect DTOs

When a Hibernate @Entity is returned directly from a @RestController, sensitive fields (passwords, internal tenant IDs, auditing timestamps) can accidentally be broadcast to external clients. Furthermore, bidirectional relationships cause infinite JSON recursion.

By enforcing strict boundary DTOs implemented as immutable Java 21 records with Jakarta Validation constraints, controllers remain completely decoupled from underlying database schemas.

dto/BookingRequestDTO.javajava
package com.enterprise.hotel.dto;

import jakarta.validation.constraints.*;
import java.time.LocalDate;

public record BookingRequestDTO(
    @NotNull(message = "Customer ID is mandatory")
    Long customerId,
    
    @NotNull(message = "Room ID is mandatory")
    Long roomId,
    
    @FutureOrPresent(message = "Check-in date cannot be in the past")
    LocalDate checkInDate,
    
    @Future(message = "Check-out date must be in the future")
    LocalDate checkOutDate,
    
    @Min(value = 1, message = "At least one guest required")
    @Max(value = 6, message = "Maximum 6 guests per room")
    Integer guestCount
) {}

Centralized Global Error Envelopes with @RestControllerAdvice

Inconsistent error formats torment frontend engineers. One endpoint returning a string, another returning a JSON stack trace, and another returning a 500 HTML page causes endless client-side bugs.

We implemented a unified API Error Envelope using @RestControllerAdvice, capturing MethodArgumentNotValidException, ResourceNotFoundException, and unexpected runtime exceptions into standard RFC 7807 problem details.

Key Architectural Takeaways

  • Never leak JPA entities past the service layer; use immutable Java 21 records as DTOs.
  • Implement @RestControllerAdvice for consistent, standardized error payloads across all endpoints.
  • Leverage Jakarta Bean Validation to catch bad request payloads before they reach business logic.

Conclusion & Next Steps

Clean architecture isn't about dogmatic academic rules; it's about minimizing cognitive overhead and preventing bugs before they reach production. Strict DTO boundaries and unified error models make enterprise codebases a joy to maintain.

More Engineering Deep Dives