DEV Community: Kamen

The Lombok Illusion (Chapter 5)

Kamen — Mon, 10 Aug 2026 06:36:32 +0000

You open a new Spring Boot project and you create a DTO, then an entity, and you’re staring at getters, setters, constructors, equals(), hashCode(), toString(). Someone on the team suggests to put lombok’s @Data, or “just slap @Builder on it, it’ll be cleaner.” Forty lines become five and it looks great in the PR.

Then it hits a real codebase, OpenAPI generation doesn't behave the way the build expects. Hibernate meets an auto-generated equals() and gets confused about identity. Something throws through a generated builder hierarchy at 2 AM, and the method you need to inspect doesn't exist in any file you can open.

Eleven years into enterprise Java, my rule is simple: Lombok doesn't touch core application behavior. Not because writing a getter is interesting - it isn't, but because the handful of lines it saves rarely covers the compiler magic, tooling friction, and debugging problems it adds to something that has to survive for years after you've moved on to another project.

"It just removes boilerplate"

Worth asking what's actually being removed, though. A getter is part of your public API. A setter is a mutation point someone decided to expose. A constructor defines what states an object is allowed to enter. equals() and hashCode() define identity. toString() is what shows up in your logs when things go wrong at 3 AM.

Write those by hand and they live in the source - visible, searchable, debuggable, owned by whoever's reading the file. Generate them with Lombok and the behavior is still there, it's just moved somewhere you can't see it without a separate step.

The annotation most people reach for first time is @Data:

@Data
@Entity
public class CustomerEntity {

    @Id
    @GeneratedValue
    private Long id;

    private String email;

    @OneToMany(mappedBy = "customer")
    private List<OrderEntity> orders;
}

One line and you get getters, setters, toString(), equals(), hashCode() across every field. For a JPA entity that's already a problem before you've written any business logic - an entity carries persistence identity, lazy proxies, mutable state, none of which behaves like a plain data bag. Field-based equality ignores identity semantics entirely. A toString() that walks relationships is a logging hazard waiting for the wrong moment. Public setters on every field quietly throw out encapsulation.

I've had this exact line take down a support investigation:

log.warn("Could not process customer: {}", customer);

If toString() walks a lazy relationship, that log statement fires a database call. If both sides of a bidirectional association reference each other, you get recursion in your logs - I've seen this crash a logging pipeline, not just produce ugly output. And if the persistence context is already closed by the time you log, you can get a LazyInitializationException thrown while you're trying to log an unrelated failure. A ten-minute incident turns into two hours because the stack trace points at logging code, not the actual bug.

The usual patch is a pile of exclusions bolted back on:

@ToString(exclude = "orders")
@EqualsAndHashCode(onlyExplicitlyIncluded = true)

At which point we've added a code generator to save typing, then added more annotations to undo part of what it generated, and now every future developer has to understand the interaction between Lombok, Hibernate proxies, equality semantics, and logging before they can touch this class safely. That's not less work. It's the same work, deferred and hidden.

Builders aren't free either

@Builder is probably the most defended Lombok annotation, and I get the appeal - long constructors are ugly, named construction reads well at the call site. But a nice call site doesn't automatically mean good architecture underneath it.

For immutable request models, a record usually does the job better:

public record CreateCustomerRequest(
    String firstName,
    String lastName,
    String email
) {
}

No annotation processor, no generated builder class sitting somewhere you'll never look, nothing ambiguous about what exists at compile time - constructor, accessors, equals(), hashCode(), toString(), all from the language itself. Where a builder genuinely earns its place - lots of optional parameters, a real construction protocol - write it by hand. It's not that much typing.

@SuperBuilder I'd flag as the one to be most careful with. Inheritance already makes domain models harder to follow. Add generated nested builders and field shadowing on top of ORM concerns, and you get bugs that compile fine and fail much later. A field ends up null nobody set on purpose, an update silently drops a value, and the row in the database stays technically valid while the business state underneath it is quietly wrong. I've debugged exactly this on a service and it took longer than it should have to even locate which builder was involved.

The toolchain cost nobody budgets for

Lombok isn't standard Java. It works by rewriting the compiler's view of your source during annotation processing. That matters because your compiler isn't the only thing reading that code. IDE indexing, static analysis, coverage tools, Javadoc, OpenAPI generation, MapStruct, QueryDSL, whatever other annotation processors are in the build, CI running on a different JDK than your laptop.

Most of the time it works fine, and that's the trap. It's not that Lombok breaks on day one, it's that it adds one more thing every tool in the pipeline has to keep agreeing on correctly. Springdoc and MapStruct can need specific processor ordering. Lombok's own extensions, like chained accessors, can quietly break JavaBean conventions that some framework tooling assumes without checking. The build accumulates workarounds to compensate, and eventually someone bumps a JDK or an IDE version, and a developer burns half a day figuring out why the generated code and the compiler disagree about what a class looks like.

Debugging wants source code, not a description of generated behavior

When something breaks in production I want a straight line: stack trace, source line, method body, state change, fix. Generated code adds fog to every step of that. The file in front of you tells you an annotation exists, not what it expands to. Builders become generated nested types you've never opened. Generated equals() and toString() pull behavior into an incident that nobody in the room actually wrote.

You can delombok a class to see what it really compiles to, but needing a second, generated copy of your own source just to understand what the first one does isn't a workaround. It's the actual problem, restated.

Java 25 already solves this

Lombok got popular in an older Java - verbose syntax, no records, weaker IDE support. We're not in that world anymore, the language itself covers most of what people reach for Lombok to fix:

public record CustomerResponse(
    UUID id,
    String fullName,
    String email
) {
}

public class CustomerEntity {

    private UUID id;
    private String email;

    public CustomerEntity(UUID id, String email) {
        this.id = id;
        this.email = email;
    }

    public UUID getId() {
        return id;
    }

    public String getEmail() {
        return email;
    }

    public void changeEmail(String email) {
        this.email = email;
    }
}

changeEmail() tells you more than a generated setEmail() ever would - it names intent, and naming intent is domain modeling, not boilerplate. For the rare getter or constructor that really is trivial, let the IDE generate it once. That costs less time than a Maven exclusion you'll be maintaining six months from now.

Where I've landed

Records for immutable DTOs like requests, responses, query results. Explicit classes for JPA entities and anything with mutable infrastructure state. Constructors written by hand to protect valid state. Explicit equality on entities where identity actually matters, not field-by-field comparison. No blanket @Data, and nothing generated that the next engineer has to reverse-engineer just to trust the class.

A dependency that shrinks your code but makes the build, the debugger, and the IDE more fragile isn't really improving developer experience, it's borrowing against it, and the interest comes due later. Small at first, then the module count grows, tooling gets stricter, JDK versions move on, and someone's maintaining a pile of invisible generated behavior that nobody currently on the team signed up to own.

What's Next

Stripping out the bytecode magic keeps the codebase predictable, debuggable, and aligned with the standard toolchain instead of fighting it.

Next up, Chapter 6: Implementing the DAO Layer - wiring up Spring Data JPA and Hibernate behind clean data access interfaces, with explicit, reflection-free transformation strategies that respect the database boundary and keep the domain layer pristine.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 5, use the following link:

GitHub Repository (Tag: chapter-05-lombok): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 4: Mapping Strategies Without the Magic
▶️ Read Chapter 6: The Dao Implementation Layer (Coming soon)

Join the Masterclass Journey

This article is part of an ongoing weekly series. If you want to receive every upcoming chapter directly in your inbox, alongside deep-dives, infrastructure architecture diagrams, and premium insights before anyone else, subscribe to my Substack Newsletter here!

Mapping Strategies Without the Magic (Chapter 4)

Kamen — Mon, 03 Aug 2026 06:22:28 +0000

At the end of the previous chapter, I teased that we were about to dive straight into the heavy machinery of DAO implementation - hooking up Spring Data JPA and Hibernate under the hood.

If you look at our original roadmap, concrete implementation was supposed to be right here. But after laying down our domain models, data contracts, and reading some of your feedback, I realized that we need to address an unspoken architectural trap first: data mapping and transformation.

Most teams blindly adopt automated tools - whether runtime reflection wrappers or compile-time generators like MapStruct - until an architectural mismatch or production incident breaks their service. Before we wire up our database infrastructure, let’s see why we chose to completely bypass mapping "magic" in favor of pure, explicit Java transformers.

And yes, some will say that writing explicit transformers is boilerplate - why write it manually when we can just use an annotation? The answer is simple: we’re not building a simple CRUD application that gets thrown to a support team and forgotten. We’re building an enterprise-ready microservice, built for deployment in Kubernetes, integrated with Kafka, Redis, and multi-tenant authorization layers - a product designed to be actively developed and maintained over years, not weeks.

This is where the real value shines: spending a little more time writing explicit transformers - as I call them, rather than standard Mappers. I call them transformers because they actively reshape data. A "mapping" usually implies just copying a field from ClassA to ClassB (whether with the same or a different name). We aren't doing that here because at an enterprise level, field names, types, and structural representations will diverge significantly between your database entities, domain models, and external DTOs.

The Architectural Trap

Across my 11 years in Enterprise Java, I've seen team after team reach for automated mappers to "save time." To understand why we banned them, we must separate them into two distinct categories - because they fail for entirely different technical reasons.

1. The Reflection Black Box (ModelMapper, Dozer, Spring BeanUtils)

Runtime reflection tools attempt to inspect fields dynamically during application execution.

The Production Tax: They rely on deep reflection APIs, bypassing Java's strong compile-time type safety.
The Debugging Wall: When a field type changes or a property is missing, the application crashes under load with a 50-line stack trace originating from the library's internal reflection routines—giving you zero visibility into which object or field caused the failure.
Performance Drag: Continuously resolving fields via reflection adds memory allocation and CPU overhead to every single request.

2. The Compile-Time Generation (MapStruct)

Unlike reflection tools, MapStruct generates standard Java code in target/generated-sources/ during compilation. It is inspectable, debuggable, and fast at runtime.

To be fair: for a simple, flat 1:1 DTO with no structural divergence, MapStruct works fine and gets out of your way. But the pain scales linearly with how much your layers diverge - and in real-world enterprise systems, domain aggregates, database entities, and REST DTOs diverge rapidly.

When structural divergence happens, MapStruct introduces distinct friction points:

IDE Refactoring Friction: MapStruct relies on string-based path configurations: @Mapping(source = "shippingDetails.address.street", target = "streetAddress"). IDE rename refactoring doesn't reach into these annotation strings the way it does for real Java field references. Even with dedicated MapStruct IDE plugins installed, you're relying on static inspection warnings after the fact, rather than a guaranteed, seamless edit-time rewrite across your codebase.
The Fallacy of 1:1 Matching: If your Domain Model (pure POJO/Record protecting business invariants), your JPA Entity (polluted by Hibernate requirements, proxies, and persistence states), and your REST DTO (flat JSON contract) look identical and map 1:1... you have a severe architectural issue. They should never match 1:1. The domain protects business rules. The entity fights the relational database. The DTO adapts to external API clients.
Framework Leakage into Domain Logic: The moment your domain uses composite hierarchies or custom value objects, MapStruct forces you to write custom @Named helper methods or embed raw Java strings inside annotation parameters: expression = "java(new Money(...))". Writing raw Java code inside annotation strings is a clear indicator that the abstraction has broken down.

Composite Hierarchy Reality Check: MapStruct vs. Pure Java

MapStruct tutorials always feature trivial 1:1 flat classes (UserDto to UserEntity). But real enterprise software uses rich composite value objects on the domain side while entities flatten them or restructure audit information. Let’s compare how MapStruct handles composite hierarchies versus how pure Java solves it safely.

The MapStruct Way (Annotation Spaghetti & Untyped String Expressions)

When field names mismatch, unit conversions are required, or composite objects need instantiation, MapStruct forces you into string-based paths and Java string expressions:

@Mapper(componentModel = "spring")
public interface OrderMapper {

    @Mapping(source = "totalMoney.amount", target = "totalAmountCentimes", qualifiedByName = "amountToCentimes")
    @Mapping(source = "totalMoney.currency", target = "currencyCode")
    @Mapping(source = "shippingDetails.recipientName", target = "deliveryContact")
    @Mapping(source = "shippingDetails.address.street", target = "streetAddress")
    @Mapping(source = "shippingDetails.address.zipCode", target = "postalCode")
    OrderEntity toEntity(Order domain);

    @Named("amountToCentimes")
    default long amountToCentimes(BigDecimal amount) {
        if (amount == null) {
            return 0L;
        }
        return amount.multiply(BigDecimal.valueOf(100)).longValue();
    }

    @InheritInverseConfiguration
    @Mapping(
        target = "totalMoney",
        expression = "java(new Money(entity.getTotalAmountCentimes(), entity.getCurrencyCode()))"
    )
    Order toDomain(OrderEntity entity);
}

Notice what happened: to handle a simple composite conversion, we ended up writing untyped Java inside an annotation string parameter (expression = "java(...)") and configuring string property paths that don't refactor cleanly with standard IDE tools.

The Pure Java Transformer Way (Zero Reflection, 100% Control)

In our multi-module architecture, we stripped out both runtime reflection libraries and compile-time code generators. We replaced them with simple, fully deterministic contracts written in vanilla Java. Here are the root interfaces that dictate the contracts for data transformation:

public interface Transformer<Input, Output> {  

    /**
     * Creates a new instance of an Output type, with transformed data from the input object.
     * @param input the input object  
     * @return the newly created Output object  
     */    
    Output createOutput(Input input);  

    /**
     * Copies the data from input to output.     
     * @param input  the input object  
     * @param output the output object  
     */    
    default void copyToOutput(Input input, Output output) {  
    }  
}

And our transformer contract for reverse transformations (used when models require bi-directional mapping across boundaries):

public interface BiTransformer<Input, Output> extends Transformer<Input, Output> {  

    /**
     * Creates a new instance of an Input type, with transformed data from the output object. 
     * @param output the output object  
     * @return the newly created Input object  
     */
    Input createInput(Output output);  

    /**
     * Copies the data from output to input. 
     * @param output the output object 
     * @param input  the input object  
     */
    default void copyToInput(Output output, Input input) {  

    }  
}

Leveraging Hierarchy: Polymorphic Auditing Without Annotation Duplication

To see how this works beyond abstract interfaces, look at our foundational audit layer. Just as we have domain-level base models, our infrastructure layer features shared concepts like creation and auditing (AbstractCreatableEntity in dao-impl and AbstractCreatable<UUID> in domain).

Instead of writing repetitive @Mapping annotations across dozens of child mappers, our transformer hierarchy follows the class hierarchy:

public abstract class AbstractCreatableTransformer<
    S extends AbstractCreatableEntity,
    D extends AbstractCreatable<UUID>
> extends AbstractBiTransformer<S, D> {

    @Override
    public void copyToInput(D output, S input) {  
        input.setId(output.getId());  
        input.setCreatedAt(output.getCreatedAt());
    }

    @Override
    public void copyToOutput(S input, D output) {  
        output.setId(input.getId());  
        output.setCreatedAt(input.getCreatedAt());
    }
}

Every concrete implementation extends AbstractCreatableTransformer and gains out-of-the-box, strongly-typed transformation of parent audit fields without a single line of duplicated configuration or annotation processing.

The Honest Trade-Off: What We Give Up

I don't claim pure Java transformers come at zero cost. There is no free lunch in software architecture:

More Physical Files: You write and maintain explicit .java transformer classes for every boundary mapping rather than single-line interface annotations.
Initial Writing Time: Setting up a direct transformer takes a minute longer than dropping an @Mapper annotation on a brand-new entity.
Onboarding Learning Curve: New hires accustomed to MapStruct or ModelMapper have to learn your module hierarchy (Transformer vs. BiTransformer) before they write their first transformer.

We deliberately pay this price. We trade a few seconds of initial writing time for 100% compile-time predictability, zero annotation processor build friction, seamless IDE refactoring, and instant local debugging under pressure.

What we win for the price we pay

0% Reflection Magic: The compiler knows everything. Every assignment is an explicit, strongly-typed method call (get / set / constructor / builder).
Guaranteed Refactoring Safety: Rename any field or record component in your domain model, and your IDE renames it across all transformer classes natively.
No Java Strings in Annotations: You write real Java code in Java files—not inside expression = "java(...)" annotation parameter strings.
JIT-Optimized Direct Assignments: The JVM easily unrolls and inlines straightforward Java method calls directly into native machine code. There is simply no faster execution path than raw Java.
Full Debugging Clarity: Place a breakpoint anywhere inside your transformer, hit F7, and inspect your real in-memory objects step-by-step.
Zero Annotation Processor Conflicts: No extra build-phase steps, no processor ordering headaches between tools, and zero build plugin friction.

What's Next?

Before we open up the dao-impl module and start building concrete JPA implementations, we have one more compile-time trap to tear down. In Chapter 5: The Lombok Illusion, we will see why we removed Lombok from our builds and how modern Java features make AST bytecode mutation obsolete.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 4, use the following link:

GitHub Repository (Tag: chapter-04-mappers): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 3: Anatomy of the Data Access Contract
▶️ Read Chapter 5: The Lombok Illusion (Coming soon)

Join the Masterclass Journey

Anatomy of the Data Access Contract: Protect Your Domain from Framework Leaks (Chapter 3)

Kamen — Mon, 27 Jul 2026 07:27:55 +0000

In almost every modern Java textbook, data persistence is introduced with a dangerous shortcut. You are told to create an interface, extend JpaRepository<Product, UUID>, and call it a day.

The result? Without even noticing, you have tightly coupled your entire application to Spring Data and Hibernate.

The moment a junior developer leaks Pageable or Specification from Spring into your clean @Service layer, or worse—directly into your REST controllers (as we discussed in Chapter 1)—your clean architecture is officially dead. Your core module now depends on the database infrastructure framework.

If tomorrow you want to switch a high-throughput read-heavy path to raw JDBC, or migrate a specific sub-domain to MongoDB, you will realize your business logic is trapped in a framework prison.

In Chapter 3 of our Evolutionary Architecture series, we are building the Dao API Module. A zero-dependency, pure Java module that strictly defines the contracts for persistence and querying, without knowing a single thing about SQL, Hibernate, or Spring.

1. Separation of Concerns: Split Creation from Updates

A common mistake in generic DAO design is introducing a single save(Entity) method that acts as both an INSERT and an UPDATE (the typical CRUD/Upsert pattern).

While frameworks love this because it hides complexity, it introduces an architectural and performance issue.

When creating a new domain object, it enters the system without an ID, allowing the infrastructure layer (like Hibernate with its modern, time-ordered UUIDv7 generator) to assign it upon persistence. However, when updating an existing entity, the ID is already present.

If you expose a unified .save() method to the outer layers, the underlying framework is forced to run a hidden, expensive SELECT query just to check whether the ID already exists in the database before deciding to execute an INSERT or an UPDATE. By explicitly splitting these actions in our core contract, we remove this infrastructure ambiguity entirely:

public interface CrudDao<E, ID> {

    void create(E entity);

    void update(E entity);

    // Return the object or null. The business layer will decide how to proceed
    E loadById(ID id);

    void delete(ID id);
}

Unlike standard frameworks that blindly force you to wrap your lookups in Optional, our core interface relies on clean, raw type returns. Optional at the database level is a costly abstraction. It doesn't eliminate missing values; it just masks them behind wrapper objects, eating up your heap allocation and putting unnecessary pressure on the Garbage Collector in high-throughput enterprise systems. If an object is missing, the database layer should return null. It is up to the business context on the invocation side to decide whether that missing record warrants a NotFoundException or signals an entry point for an initialization flow.

2. Type-Safe Pagination and Sorting Without Spring

How do we support enterprise-grade searching, pagination, and sorting without importing org.springframework.data.domain.Pageable?

We define our own lightweight, framework-agnostic parameter objects. To enforce compile-time safety on sorting and prevent malicious SQL injections via arbitrary string sorting parameters, we introduce the SortBy interface:

public interface SortBy {
    String getPropertyName();
}

Every domain can now declare its own concrete sorting capabilities using type-safe Java Enums:

public enum ProductSort implements SortBy {
    PRICE("price"),
    CREATED_AT("createdAt"),
    NAME("name");

    private final String propertyName;

    ProductSort(String propertyName) {
        this.propertyName = propertyName;
    }

    @Override
    public String getPropertyName() {
        return this.propertyName;
    }
}

Using this, our base search query transport object remains incredibly clean, pure, and descriptive:

public abstract class AbstractParams<S extends SortBy> {

    private int page;
    private int size;
    private S sortBy;
    private Direction direction = Direction.DESC;

    protected AbstractParams(int page, int size) {
        this.page = Math.max(page, 0);  
        this.size = size < 1 ? 10 : size;
    }
    ...
}

3. Defining Domain-Specific Contracts

To tie everything together, we compose these capabilities into a distinct SearchableDao contract and extend it for our specific Aggregate Roots.

public interface SearchableDao<Type, P extends AbstractParams<?>> {
    ResultPage<Type> search(P params);
}

Notice how the ProductDao interface lives entirely within the API module, requires zero infrastructure annotations, and can easily be extended with specialized, high-performance business queries that aren't a good fit for standard CRUD, where ProductSearchParams simply extends our AbstractParams<ProductSort>

public interface ProductDao extends
    CrudDao<Product, UUID>,
    SearchableDao<Product, ProductSearchParams> {

    // Explicit business-driven query contract
    Product findBySku(String sku);
}

4. Continuous Architecture: The Contract Test Blueprint

The hidden superpower of this architecture is how trivial it makes testing. Because our DAO interfaces in this module are completely clean contracts, they allow us to implement bulletproof Contract Testing later on.

While the dao-api module itself contains zero code execution and thus carries no tests, it defines the absolute baseline behaviors. In the next chapter—when we build the concrete database implementation module—we won't just write random tests for our repositories. Instead, we will construct an abstract test suite containing 15 to 20 foundational scenarios: covering successful creation, updates, constraint violations, optimistic locking behaviors, and sorting correctness.

If someone breaks the data contract during a database migration or framework upgrade, the contract test will fail immediately before the code ever leaves the infrastructure module.

What's Next?

By decoupling our data contracts, our domain module remains pristine, bulletproof, and completely independent. Frameworks are put back where they belong: as external delivery mechanisms.

In the next chapter, we will finally bring in the heavy machinery. We will implement the concrete Infrastructure Database Module, plug in Hibernate and Spring Data JPA under the hood, and look into how to seamlessly map database entities back to our rich domain models without losing encapsulation.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the baseline state established in Chapter 3, use the following link:

GitHub Repository (Tag: chapter-03-dao-api): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 2: Anatomy of the Domain Module
▶️ Read Chapter 4: Mapping Strategies Without the Magic

Join the Masterclass Journey

Anatomy of the Domain Module: Throw Away Anemic Models and Ban `@ManyToMany` (Chapter 2)

Kamen — Thu, 23 Jul 2026 07:37:53 +0000

Years ago, when I was starting my career, I religiously followed the standard textbooks. The ones that teach you that entities should be anemic (just data holders) and that the "service layer" should orchestrate everything.

The result? After just а couple of months in production, the @Service classes bloated into thousands of lines of spaghetti code, filled with endless validation checks, state mutations, and structural mess. The domain entities completely lost their integrity—anyone could mutate their state from anywhere.

And if you throw physical mappings like @ManyToMany into the data access layer later? You are guaranteed to face N+1 query issues, tight coupling, and a schema so tangled that splitting it into microservices feels like performing open-heart surgery.

In this article, we will break down the design of our domain module. It is written in modern Java, remains completely free of Spring dependencies, guarantees encapsulation through a Rich Domain Model, and runs unit tests in milliseconds.

1. Pure OOP (Without Spring Data Magic)

When writing a clean domain model, we must isolate the infrastructure. Instead of relying on Spring Data JPA’s auditing framework at such an early stage, we define the rules for creation, modification, and naming directly within our domain's Java hierarchy.

Here is the blueprint of our base domain classes:

// Every domain object that requires creation audit tracking
public abstract class AbstractCreatable<IdType> {

    private IdType id;
    private Instant createdAt;

    protected AbstractCreatable(IdType id) {
        this.id = Objects.requireNonNull(id);
        this.createdAt = Instant.now();
    }

    ...
}

// Every domain object that also tracks modification timestamps
public abstract class AbstractUpdatable<IdType>
    extends AbstractCreatable<IdType> {

    private Instant updatedAt;

    protected AbstractUpdatable(IdType id) {
        super(id);
        this.updatedAt = Instant.now();
    }

   ...
}

// Every domain object requiring a full audit trail (who created and updated it)
public abstract class AbstractAuditable<IdType>
    extends AbstractUpdatable<IdType> {

    private UUID createdById;
    private UUID updatedById;

    protected AbstractAuditable(IdType id) {  
     super(id);  
    }  

    protected AbstractAuditable(IdType id, UUID createdById) { 
        super(id);  
        this.createdById = Objects.requireNonNull(createdById);
        this.updatedById = createdById; // At creation, updatedBy matches creator
    }

    ...
}

💡 But wait... why initialize timestamps directly in the constructor?

Because your domain models must be self-contained and fully functional from the very millisecond they are instantiated. Since our domain module is a pure Java library with zero infrastructure awareness, we cannot and should not rely on database triggers or external framework lifecycles.

By setting Instant.now() directly in the constructor, we guarantee that the domain object is always complete, valid, and immediately testable in-memory, without waiting for some future persistence layer to "hydrate" its state. It also prevents NullPointerException bugs when sorting or processing newly instantiated domain events in memory before database transactions.

2. Death to `@ManyToMany` – Designing Decoupled Relationships

In real-world, highly scalable systems, physically coupling two independent business contexts (like Product and Category) via Hibernate mappings is an architectural dead-end.

Therefore, in our architecture, @ManyToMany relationships are strictly banned. Instead, we model them as completely decoupled Aggregates that communicate solely through identifiers (UUIDs) using a dedicated Relationship Entity:

// Aggregate Root #1: Category
public class Category extends AbstractAuditable<UUID> {

    private String name;
    private boolean active;

    public Category() {  
        // POJO  
    }

    ...
}

// The decoupled junction: CategoryAssignment (Relationship Entity)
// Since relationship assignments are append-only, inheriting from AbstractCreatable is perfect!
public class CategoryAssignment extends AbstractCreatable<UUID> {

    private UUID productId;     // Pure UUID instead of Product
    private UUID categoryId;    // Pure UUID instead of Category
    private UUID assignedById;  // For auditing purpose, who made the association

    public CategoryAssignment(
        UUID id,
        UUID productId,
        UUID categoryId,
        UUID assignedById
    ) {
        super(id);
        this.productId = Objects.requireNonNull(productId);
        this.categoryId = Objects.requireNonNull(categoryId);
        this.assignedById = Objects.requireNonNull(assignedById);
    }

    ...
}

Why is this "Distributed Ready"?

If tomorrow your business decides to migrate Categories to a separate microservice (e.g., a dedicated Catalog Service), the code of your Product domain won't change by a single line. The Product database will simply store the categoryId as a plain UUID received via Kafka or a REST payload, without caring about the internal database tables or Hibernate proxies of the neighboring context.

3. When Are Direct Relationships Allowed? (Aggregate Root & 1-to-1)

While we decouple large business units via UUIDs, how do we handle tightly bound details?

If an entity (e.g., ProductSpecification) has no independent business meaning and shares 100% of the lifecycle of the main object (Product), they become part of the same Aggregate Root. When the product is deleted, the specification must be deleted cascadingly.

Here is how we model this in our domain, where Product holds a direct reference to ProductSpecification but acts as the strict transactional boundary:

public class ProductSpecification extends AbstractUpdatable<UUID> {

    private String dimensions;
    private double weight;

    public ProductSpecification(UUID id, String dimensions, double weight) {
        super(id);
        this.dimensions = Objects.requireNonNull(dimensions);
        this.weight = weight;
    }

   ...
}

// Aggregate Root: Product controlling the lifecycle of its nested entities
public class Product extends AbstractAuditable<UUID> {

    private String name;
    private String sku;
    private BigDecimal price;
    private ProductStatus status;
    private ProductSpecification specifications; // Strongly bound 1-to-1

    public Product(
        UUID id,
        String name,
        String sku,
        BigDecimal price,
        ProductSpecification specifications
    ) {
        super(id);  
        this.name = Objects.requireNonNull(name);
        this.sku = Objects.requireNonNull(sku);
        this.price = Objects.requireNonNull(price);
        this.specifications = Objects.requireNonNull(specifications);
        this.status = ProductStatus.DRAFT;
    }

    public void transitionTo(ProductStatus nextStatus) {  
        if (!this.status.canTransitionTo(nextStatus)) {  
            throw new IllegalStateException("Business rule violated: Cannot transition from " + this.status + " to " + nextStatus);  
        }  
        this.status = nextStatus;  
    }
}

4. State Machine: Inside the Enum or in an External State Manager?

A common debate among senior engineers is: Where should the state transition logic live—inside the Enum or delegated to an external State Manager?

The architectural answer is clear: State transition rules belong to the Domain (inside the Enum), while an external State Manager/orchestrator should only handle structural side-effects.

If you leak state validation rules outside, you anemicize Product and allow any developer to bypass the state machine, mutating the object into an invalid state.

Here is our encapsulated ProductStatus enum:

public enum ProductStatus {
    DRAFT {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return next == ACTIVE || next == ARCHIVED;
        }
    },
    ACTIVE {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return next == OUT_OF_STOCK || next == ARCHIVED;
        }
    },
    OUT_OF_STOCK {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return next == ACTIVE || next == ARCHIVED;
        }
    },
    ARCHIVED {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return false; // Terminal state. No transitions allowed!
        }
    };

    public abstract boolean canTransitionTo(ProductStatus next);
}

What about the external State Machine? It acts purely as an orchestrator. Once the domain layer successfully performs the transition, the orchestrator commits the transactions and triggers the side-effects (e.g., publishing a ProductActivatedEvent to Kafka or clearing a cache).

5. The 5-Millisecond Unit Test

Since our domain module does not import a single @Component, @Service, or @Autowired annotation, we don't need a slow boot context to validate our business rules.

We test pure Java objects, and the execution completes in under 5 milliseconds:

class ProductDomainTestCase {  

    private static final UUID CREATOR_ID = UUID.randomUUID();  
    private static final ProductSpecification spec = new ProductSpecification(...);  

    private Product product;  

    @BeforeEach  
    void setUp() {  
        product = new Product(...);  
    }  

    // --- DRAFT Status Transitions ---  

    @Test  
    void shouldAllowTransitionFromDraftToActive() {  
        product.transitionTo(ProductStatus.ACTIVE);  
        assertEquals(ProductStatus.ACTIVE, product.getStatus());  
    }  
    ...
}

By keeping the business layer pure, you establish a highly testable, robust, and decoupled domain core. Frameworks, databases, and network protocols are just external details plugged in at a later stage.

What's Next?

In the next part, we will dive into the very foundation of Data Access Layer design — the DAO API Module — and discuss how to keep it 100% pure without a single specific implementation (hibernate, mysql, oracle sql, etc.).

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 2, use the following link:

GitHub Repository (Tag: chapter-02-domain): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 1: Stop returning Spring Data Page from your REST endpoints
▶️ Read Chapter 3: The Dao API Module

📨 Liked this architecture blueprint? This article is part of my Evolutionary Architecture series. I publish deep-dive technical pieces every week.
👉 Subscribe to my Substack Newsletter to get full source code repositories (Git tags) and new chapters straight to your inbox!

Why Package Structures Won't Save Your Spring Boot Architecture (And How Maven Enforces It) (Chapter 1)

Kamen — Thu, 23 Jul 2026 07:29:50 +0000

How We Turned Architectural Guidelines Into Compilation Errors

Have you ever found yourself doing a Friday afternoon Code Review, only to discover that someone injected the EntityManager directly into a REST controller, writing raw SQL strings, and mapping rows manually with a loop? Or worse, have you seen a @RequestParam accepting org.springframework.data.domain.Pageable while the controller returns a raw Page<Entity> directly to the frontend?

Congratulations. You have just exposed your database schema to the entire world and completely bypassed the concept of an Anti-Corruption Layer (ACL).

The Illusion of Package Control

When an application is structured within a single module and we rely strictly on package separation (.controller, .service, .repository), we live in an illusion of architectural control.

⚠️ The hard truth: Packages do not stop anyone.

In the heat of a tight deadline, when "things just need to work," Java package visibility rules will not prevent a junior or stressed developer from committing architectural crimes that you will be debugging for months.

Here is how we solved this problem in our team by breaking down the system into highly specialized Maven modules, effectively turning architectural guidelines into compilation errors.

The Architectural Blueprint: Divide, Conquer, and Version

The first step toward true isolation was radical: we extracted the API contract into a completely separate Git repository. Why? Because your API contract version should be independent of your backend implementation. If we fix a bug tomorrow in the core business logic, it makes absolutely no sense to bump the version of the REST/Event contract if nothing changed there. The frontend team and QA engineers need a stable contract to work against, completely shielded from our internal refactoring.

Next, we split the main backend project into highly specialized Maven modules. When I first proposed this, the team was highly skeptical: "It's too complex," "Why do we need this? We already have packages."

So, I built a quick proof-of-concept. Instead of relying on a developer’s goodwill, we shifted the enforcement of architectural boundaries directly to the compiler.

The Dependency Topology

Here is what the real dependency topology looks like:

├── RestService API (Git Repo 1)
│   ├── dto (Jackson & Swagger)
│   └── events (Event Contracts)
│   └── rest-api (The API intefaces from which documentation is generated)
│
└── Backend (Git Repo 2)
    ├── domain (Pure Domain Models & Core Logic (No Frameworks))
    ├── business-logic (Core Business Logic (Depends only on domain & APIs))
    ├── dao-api (Database Access Interfaces (No JPA/Spring Data))
    ├── dao-impl (Actual DB Integration (Spring Data JPA, Hibernate))
    ├── bridge-api (External Services Communication APIs)
    ├── bridge-impl (Actual Integration with External APIs)
    ├── integration-tests (Testing layer via Testcontainers (Docker-based))
    └── application (Spring Boot Bootstrapper)

In this structure, the heart of the system — the business-logic module — depends strictly on the interfaces defined in dao-api and bridge-api.

It has zero access to dao-impl or bridge-impl. Your core business logic does not have spring-boot-starter-data-jpa, Hibernate, Kafka, or Redisson in its classpath.

Let Maven Keep Your Code Reviews Clean

Once we introduced this change, it didn’t take long for the team to realize its power.

If a developer attempts to inject the EntityManager or write raw SQL queries inside the core business logic tomorrow, the code simply will not compile. The build will break right on their local machine.

To circumvent this, they would have to deliberately go into the pom.xml of business-logic and introduce a dependency on the database module — an action that would instantly trigger a massive red flag during any Code Review.

Immediate Benefits in an Enterprise Environment

No More Cyclic Dependencies: Maven physically forbids module A from depending on B if B already depends on A.
Lightning-Fast Unit Tests: Because the business logic is entirely decoupled from infrastructure frameworks, unit tests are written effortlessly. We only mock pure Java interfaces, and the tests execute in milliseconds. No one can use the "tests take too much time" excuse anymore.
Pure Infrastructure Interchangeability: The business-logic module interacts solely with the contract in dao-api. It doesn't know — nor does it care — whether the data underneath comes from MySQL (via dao-impl), is cached in Redis, or is being streamed via Kafka (via bridge-impl). The implementations are wired together at the very top layer — in the application module.

Conclusion: Is it Overengineering?

If you are building a small CRUD app with five tables, this approach is undoubtedly overengineering. But if you are building an Enterprise system designed for long-term maintainability, high team velocity, and strict domain boundaries, you cannot afford to build your house on sand.

Relying purely on folder structures means that sooner or later, under pressure, someone will break the rules. Transitioning to a multi-module design requires more initial boilerplate, but it eliminates 70% of long-term architectural decay.

What's Next?

In the next part, we will dive into the very foundation of this design — the Domain Module — and discuss how to keep it 100% pure (POJO) without allowing a single JPA or Hibernate annotation to pollute your business models.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the baseline state established in Chapter 1, use the following link:

GitHub Repository (Tag: chapter-01-baseline): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

▶️ Read Chapter 2: The Domain module

DEV Community: Kamen

The Lombok Illusion (Chapter 5)

"It just removes boilerplate"

Builders aren't free either

The toolchain cost nobody budgets for

Debugging wants source code, not a description of generated behavior

Java 25 already solves this

Where I've landed

What's Next

Codebase & Architecture Blueprint

Join the Masterclass Journey

Mapping Strategies Without the Magic (Chapter 4)

The Architectural Trap

1. The Reflection Black Box (ModelMapper, Dozer, Spring BeanUtils)

2. The Compile-Time Generation (MapStruct)

Composite Hierarchy Reality Check: MapStruct vs. Pure Java

The MapStruct Way (Annotation Spaghetti & Untyped String Expressions)

The Pure Java Transformer Way (Zero Reflection, 100% Control)

Leveraging Hierarchy: Polymorphic Auditing Without Annotation Duplication

The Honest Trade-Off: What We Give Up

What we win for the price we pay

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

Anatomy of the Data Access Contract: Protect Your Domain from Framework Leaks (Chapter 3)

1. Separation of Concerns: Split Creation from Updates

2. Type-Safe Pagination and Sorting Without Spring

3. Defining Domain-Specific Contracts

4. Continuous Architecture: The Contract Test Blueprint

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

Anatomy of the Domain Module: Throw Away Anemic Models and Ban `@ManyToMany` (Chapter 2)

1. Pure OOP (Without Spring Data Magic)

💡 But wait... why initialize timestamps directly in the constructor?

2. Death to @ManyToMany – Designing Decoupled Relationships

Why is this "Distributed Ready"?

3. When Are Direct Relationships Allowed? (Aggregate Root & 1-to-1)

4. State Machine: Inside the Enum or in an External State Manager?

5. The 5-Millisecond Unit Test

What's Next?

Codebase & Architecture Blueprint

Why Package Structures Won't Save Your Spring Boot Architecture (And How Maven Enforces It) (Chapter 1)

How We Turned Architectural Guidelines Into Compilation Errors

The Illusion of Package Control

The Architectural Blueprint: Divide, Conquer, and Version

The Dependency Topology

Let Maven Keep Your Code Reviews Clean

Immediate Benefits in an Enterprise Environment

Conclusion: Is it Overengineering?

What's Next?

Codebase & Architecture Blueprint

2. Death to `@ManyToMany` – Designing Decoupled Relationships