DEV Community: Kamen

Why almost every ‘Temporary’ Workaround is Permanent (Chapter 8)

Kamen — Mon, 31 Aug 2026 05:55:42 +0000

Somewhere around month four of any project I've worked on, someone says a version of the same sentence. "Just hardcode it for now, we'll fix it after the release." Nobody arguing against it and they genuinely believe it's temporary. The problem isn't the shortcut itself, sometimes a shortcut is the correct call. The problem is that "temporary" has no owner, no ticket, and no deadline of its own. It just sits there until someone forgets it was ever supposed to be temporary at all, and by then it's load-bearing. Here's how that actually plays out, because the abstract version of this story is boring and everyone nods along without changing anything.

The shortcut

We needed to ingest pricing updates from an upstream provider. Three days, full stop, because a partner integration deadline had already been communicated externally and nobody wanted to be the one calling to push it back. The fastest path was obvious: inject a RestClient call directly into the business-logic service method that needed the data, parse the JSON inline, map a couple of fields by hand, and move on.

We shipped it on time, it worked and everyone moved on to the next fire, which is what always happens after a deadline shortcut lands successfully. Success is exactly what makes it invisible.

Two months later we get an update: "The upstream team is moving to Kafka. They want to push events, not serve a REST endpoint anymore.", and now the HTTP call is gone, but it was never just a call - it was call semantics baked into a domain-facing method signature. The service method that used to return synchronously now needs to react to a stream. Unit tests that mocked an HttpClient are gone and now they need to mock a Kafka consumer instead. Every call site that invoked the pricing method synchronously has to be reconsidered, because the whole shape of "when do we have this data" changed underneath them.

Three weeks after that migration finished, we got again another update: "Edge devices in the field can't maintain a Kafka connection reliably. We're pushing over MQTT instead." Same story again, except now it's the third rewrite of the same core logic in five months, and each rewrite touches more of the codebase than the last one did, because more things had grown to depend on the leaked transport assumptions in the meantime.

Nobody planned for three transport migrations. Nobody ever does. That's exactly the point - the shortcut wasn't wrong because REST was the wrong choice, it was wrong because it welded a decision that was going to change into logic that was supposed to be stable.

What it should have looked like

This is precisely why business-logic in this project never talks to a transport mechanism directly. It depends on an interface, a port, if you want the textbook word for it, though I'd rather just call it what it is: an interface that answers the domain's question ("give me the latest price for this SKU") without knowing or caring how the answer arrives. Whether that interface is backed by a REST client, a Kafka listener, or an MQTT subscriber is bridge-impl's problem, sealed away from business-logic by the same compiler-enforced module boundary that's been the whole point of this architecture since Chapter 1.

When the transport changes, bridge-impl changes. The interface in bridge-api doesn't move, and neither does a single line in business-logic. Three transport migrations in five months would have been three rewrites of one implementation of the interface instead of three rewrites of everything downstream of a leaked implementation detail.

The uncomfortable part of this story is that we didn't have that boundary in place when the first shortcut happened. We built it because of this exact pain, not before it. That's usually how it goes, the boundary gets built in the shape of whatever already went wrong once, the same way most safety rules only exist because a crash already happened.

The same failure, dressed differently

The transport story is the clean, satisfying version, because it has a name and a fix. The uglier version of the same failure shows up whenever someone decides a mapper is overhead the deadline can't afford. "Why write a DTO and a transformer? Just return the entity from the controller." It takes five minutes to wire up and it works immediately, which is exactly the illusion - the cost isn't paid at the point of the shortcut, it's paid the first time someone needs to rename a column and discovers that half a dozen frontend clients have quietly come to depend on the JPA entity's field names as if they were a public contract.

This is what the Transformer/BiTransformer split from Chapter 4 actually buys you, beyond the argument against MapStruct. It's not really about avoiding a mapping library, It's about there being exactly one place where "how the database shape becomes the domain shape" is decided, so that decision can change without becoming an incident. Skip it under deadline pressure and you haven't saved the mapping work, you've just deferred it to whoever eventually has to reverse-engineer which fields are safe to touch.

The actual cost, after the fact

We went back and counted, roughly, what the three transport rewrites cost against what the port/adapter boundary would have cost to build up front. Building the boundary correctly the first time would have added maybe a half day or a day to the original three-day deadline - one interface, one adapter implementation, tests against the interface instead of the HTTP client. The three subsequent rewrites, combined, cost closer to three weeks, most of it not writing new code but tracing which parts of the business logic had quietly grown to assume synchronous, request-shaped delivery of data that was never going to stay synchronous or request-shaped.

That ratio is the entire chapter. The shortcut doesn't remove the cost, it just moves it downstream, converts it from a schedule risk into a production risk, and hands the bill to whoever's on call when a customer reports that a price didn't update and nobody can immediately say which of three transport layers is currently responsible for getting it there.

The part that doesn't fit in a retro

The hard part isn't spotting this pattern in hindsight, it's obvious once it's a war story. The hard part is that at the moment the shortcut gets proposed, it is correctly, the fastest way to hit the date. Refusing every shortcut on principle is its own failure mode. You'll miss real deadlines defending abstractions nobody needed. The distinction that actually matters is whether the shortcut cuts a corner inside a module boundary you're allowed to redo later in isolation, or whether it cuts through a boundary that other code is going to grow around before anyone circles back to it. A hardcoded value inside bridge-impl is an annoyance, a hardcoded assumption smuggled into business-logic about how data arrives is a liability with compound interest, and the interest rate is set by how many other developers touch that code before someone pays it down.

What's Next

Chapter 9 continues into the business logic module itself - what it means to write core services that depend on nothing but interfaces they own, and what actually breaks when that discipline slips.

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 8. There's no code change between Chapter 7 and Chapter 8, I'm tagging each chapter regardless, for consistency:

GitHub Repository (Tag: chapter-08-shortcuts): advanced-spring-multimodule

Maven 3.9.x and Java 25 are required.

◀️ Read Chapter 7: The DAO Testing
▶️ Read Chapter 9: The Core Business Logic Module (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!

What Spring Data Tests Can Miss: Testing Beyond Hibernate’s Persistence Context (Chapter 7)

Kamen — Mon, 24 Aug 2026 07:41:04 +0000

Here's the mechanism, before the war story: every EntityManager keeps a first-level cache, an identity map of every entity it's touched in the current persistence context. Call find() (which is what loadById resolves to, directly or through Spring Data's derived findById) for an entity that's already managed, and Hibernate doesn't ask the database anything. It just hands you back the object it already has. That's not a bug. It's the entire point of the first-level cache, and most of the time it's exactly the behavior you want. The problem is that a green @DataJpaTest can’t tell the difference between 'I verified this round-trips through the database' and 'I got the same Java object reference back.' And I’ve watched teams ship code confident in tests that were only ever validating L1 cache state - right up until a missing constraint violation or a column mapping bug blew up in production because the data was never actually flushed and re-hydrated.

In this chapter of the Evolutionary Architecture series, we're tearing down the illusion of the default Spring Data test. We'll look at exactly where the first-level cache hides bugs, and build a testing architecture around explicit EntityManager clearing, generic test fixtures, and in-memory isolation - so a green test means what you think it means.

What Standard Spring Tests Actually Test

When you write a standard Spring Data test using @DataJpaTest and a repository interface, your test looks clean and harmless:

@Test
void testSaveProduct() {
    var product = new Product("A1", "Gaming Laptop", BigDecimal.valueOf(1500));
    productDao.create(product);

    Product loaded = productDao.loadById(product.getId());
    assertNotNull(loaded);
    assertEquals("Gaming Laptop", loaded.getName());
}

It passes, but let's see here what actually happened:

You call create(). Hibernate generates a managed entity inside the persistence context - the row may or may not have hit the database yet, depending on flush mode. Then, even inside the @Transactional wrapper the test runs in, calling loadById() immediately after doesn't issue a SELECT. The entity you just created is still sitting in the L1 cache, still attached to the same persistence context, and find() short-circuits straight to it. You get the exact object reference back. The table itself never answered a query. To be precise about where this bites and where it doesn't: this specifically applies to find() - based lookups. A custom JPQL or native @Query method always issues real SQL, cache or no cache Hibernate will still try to reconcile the result with anything already managed, but the round-trip to the database happens either way. The gap is narrower than "all your reads are fake." It's specifically the find()/findById() path, which is also the one most CRUD test suites lean on hardest, because it's the one that requires the least code to write. So this test hasn't verified persistence. It's verified Hibernate's in-memory bookkeeping and Spring Data's proxy machinery which isn't nothing, but it's not what the test's name claims. A strict column constraint, a broken mapping, a query that only breaks against a real dialect - all of that can hide behind a green checkmark here.

Forcing a Real Write-and-Read Boundary

If a test exists to verify persistence rather than domain behavior, it needs to force Hibernate to flush its write-behind queue to the database, then clear the persistence context before reading anything back. The next read has to hydrate a fresh entity graph from scratch - no shortcuts, no identity map hits.

Doing that by hand in every test method is exactly the kind of boilerplate that gets skipped under deadline pressure, which defeats the point. So we push the discipline down into the test infrastructure itself, using a test-only proxy that wraps every DAO and forces the flush-and-clear automatically after any write.

Architectural Boundary Note: This proxy layer lives exclusively in test scope (TestConfig, under src/test/java). It's physically unreachable from production code and never ships in a production artifact. Production wiring injects the unproxied DAO implementations directly, so Hibernate keeps its normal write-behind batching with zero caching penalty outside of tests.

Here is our test-only CrudDaoProxy:

public abstract class CrudDaoProxy<
    IdType,
    Domain extends AbstractCreatable<IdType>,
    Dao extends CrudDao<IdType, Domain>
> implements CrudDao<IdType, Domain> {

    protected final Dao proxied;
    private final EntityManager entityManager;

    protected CrudDaoProxy(Dao proxied, EntityManager entityManager) {
        this.proxied = proxied;
        this.entityManager = entityManager;
    }

    @Override
    public Domain create(Domain domain) {
        final var saved = proxied.create(domain);
        flushAndClear();
        return saved;
    }

    @Override
    public Domain update(Domain domain) {
        final var updated = proxied.update(domain);
        flushAndClear();
        return updated;
    }

    @Override
    public Domain loadById(IdType id) {
        return proxied.loadById(id);
    }

    @Override
    public void delete(Domain domain) {
        proxied.delete(domain);
        flushAndClear();
    }

    protected void flushAndClear() {
        // Forces SQL out of write-behind cache into DB
        entityManager.flush(); 
        // Wipes L1 cache, forcing a real JDBC round-trip on next read
        entityManager.clear(); 
    }
}

Notice what's deliberately not overridden here: loadById just delegates straight through to proxied.loadById(id), no flush-and-clear wrapper. It doesn't need one, by the time a test calls it, the previous write already forced the clear. Any DAO with search capability gets the same treatment one level up:

public abstract class SearchableCrudDaoProxy<
        IdType,
        Domain extends AbstractCreatable<IdType>,
        Params extends AbstractParams<? extends SortBy>,
        Dao extends CrudDao<IdType, Domain> & SearchableDao<Domain, Params>
    > extends CrudDaoProxy<IdType, Domain, Dao> implements SearchableDao<Domain, Params> {

    protected SearchableCrudDaoProxy(Dao proxied, EntityManager entityManager) {
        super(proxied, entityManager);
    }

    @Override
    public ResultPage<Domain> search(Params criteria) {
        return proxied.search(criteria);
    }
}

search() passes straight through too - it's backed by a Specification, which always compiles to real SQL regardless of cache state, so there's nothing to force. The proxy only intervenes exactly where the shortcut exists: create, update, delete. That asymmetry isn't an oversight, it's the whole design - wrap the three operations that can lie, leave the two that can't.

A concrete feature DAO just extends the generic proxy and adds whatever custom query methods it has:

public class ProductsDaoProxy extends SearchableCrudDaoProxy<
    UUID,
    Product,
    ProductSearchParams,
    ProductDao
> implements ProductDao {

    public ProductsDaoProxy(ProductDao proxied, EntityManager entityManager) {
        super(proxied, entityManager);
    }

    @Override
    public Product loadBySku(String sku) {
        return proxied.loadBySku(sku);
    }
}

loadBySku isn't part of the generic CRUD/search contract, so it gets a one-line override with no wrapping - same reasoning as loadById.

Ground-Zero: The `TablesEraser`

Relying purely on Spring's @Transactional rollback-per-test can still hide second-level cache pollution, batching side effects, or a connection leak that only shows up across tests, not within one.

So every component test starts from an empty schema. TablesEraser deletes every row from every table before each test runs:

public class TablesEraser {

    public static void emptyAllTables(
        EntityManagerFactory emf,
        DbQueryFactory queryFactory
    ) {
        emptyAllTables(emf, queryFactory, s -> true);
    }

    public static void emptyAllTables(
        EntityManagerFactory emf,
        DbQueryFactory queryFactory,
        Predicate<String> filter
    ) {
        final EntityManager em = emf.createEntityManager();
        try {
            em.getTransaction().begin();

            // Disable foreign key checks dynamically
            em
              .createNativeQuery(queryFactory.disableForeignKeys())
              .executeUpdate();

            // Fetch all table names and truncate them
            final List<String> allTableNames = em
              .createNativeQuery(queryFactory.selectAllTableNames())
              .getResultList();
            for (final var tableName : allTableNames) {
                if (filter.test(tableName)) {
                    em
                    .createNativeQuery("DELETE FROM " + tableName)
                    .executeUpdate();
                }
            }

            // Re-enable foreign keys and commit
            em
              .createNativeQuery(queryFactory.enableForeignKeys())
              .executeUpdate();
            em.getTransaction().commit();
        } catch (Throwable th) {
            em.getTransaction().rollback();
            throw new RuntimeException(th);
        } finally {
            em.close();
        }
    }
}

Worth being precise here: this is a DELETE FROM per table, not a TRUNCATE. That's a deliberate trade-off, not an oversight - DELETE respects the same transaction we're already managing manually and rolls back cleanly if anything in the loop throws, where a bare TRUNCATE in most dialects auto-commits and can't be undone mid-loop. It costs a little raw speed against a TRUNCATE, and it's worth it for a test-suite reset that can fail safely.

Reusable Tests: `AbstractCrudTestCase` & `AbstractSearchableTestCase`

Shared assertions cut real repetition, as long as the abstraction stays shallow. The moment a failing test sends you on a five-class inheritance hunt to understand what actually broke, the abstraction has stopped paying rent.

public abstract class AbstractCrudTestCase<
        ID,
        D extends AbstractCreatable<ID>,
        DAO extends CrudDao<ID, D>
    > extends AbstractDaoTest {

    @Test  
    void testCreate() {  
        final D expectedEntity = runSave();  
        final D dbEntity = getDao().loadById(expectedEntity.getId());  
        assertNotNull(dbEntity, "missing entity");  
        assertEquals(expectedEntity.getId(), dbEntity.getId());  
        getAsserter().assertDeepEquals(expectedEntity, dbEntity);  
    }

    @Test
    void testCreateExisting() {
        final D existing = runSave();
        final var ex = Assertions.assertThrows(
            IllegalArgumentException.class,
            () -> getDao().create(existing)
        );
        Assertions.assertEquals("Entity existing!", ex.getMessage());
    }

    ...

    protected abstract DAO getDao();
    public abstract D createDomain();
    protected abstract DeepEqualsAsserter<D> getAsserter();
}

A concrete case like ProductDaoTestCase stays thin, it implements the domain-specific payload generator (createDomain()) and inherits the full CRUD and search suite for free. It's not only that, though. It also adds its own tests for loadBySku, because that's a query method the generic contract has no way to know about. That's the right shape for this kind of abstraction - the base class owns everything that's structurally identical across every DAO, and the concrete case owns exactly the part that makes this DAO different. If a shared base class tried to guess at loadBySku too, you'd be back to fighting a framework instead of using one.

Not every test in this hierarchy exists to confirm the happy path. One of those tests is in the AbstractSearchableTestCase that specifically is checking a boundary condition:

@Test
public void testSearchNullParams() {
    for (int i = 0; i < 5; i++) {  
        runSave(createDomainWithUniqueData());  
    }

    final ResultPage<Domain> result = getDao().search(null);  
    assertEquals(1, result.totalPages());  
    assertEquals(5, result.totalHits());  
    assertEquals(5, result.elements().size());
}

That test earned its place in the suite the hard way. It didn't start out passing.

What the Null-Params Test Actually Caught

The first version of search() in SearchableDaoImpl assumed a Params object would always be there:

private Pageable toPage(Params criteria) {
    return PageRequest.of(
            criteria.getPage(),
            criteria.getSize(),
            getSortOrDefault(criteria.getSortBy(), criteria.getSortDirection())
    );
}

Reasonable assumption, right up until testSearchNullParams called getDao().search(null) and got a NullPointerException on criteria.getPage() instead of a result page. Which is exactly the point of writing that test before the feature felt finished - a caller passing null to mean "no filters, give me the default page" is a completely ordinary thing to do, and the DAO was punishing it with a stack trace instead of handling it.

The fix has two parts, and both matter for the same reason: Params is a generic type parameter here, so there's no single field-by-field way to "default" a null one into existing. Every concrete DAO defines its own Params subtype with its own fields, which means the null case has to be handled once, centrally, before any of that generic machinery gets involved - not pushed down into every feature DAO's createSpecification implementation as a null-check they'd all have to remember to write.

Paging falls back to a fixed default when there is no parameter to base it on:

private Pageable toPage(Params criteria) {
    if (criteria == null) {
        return PageRequest.of(DEFAULT_PAGE, DEFAULT_SIZE, CREATED_AT_DESC_SORT);
    }
    return PageRequest.of(
            criteria.getPage(),
            criteria.getSize(),
            getSortOrDefault(criteria.getSortBy(), criteria.getSortDirection())
    );
}

And filtering falls back to "match everything" rather than calling the abstract createSpecification(params) with nothing for it to read:

@Override
public ResultPage<Domain> search(Params params) {
    final Pageable pageable = toPage(params);
    final Specification<Entity> spec = params == null
            ? Specification.unrestricted()
            : createSpecification(params);
    final Page<Entity> result = repository.findAll(spec, pageable);
    final List<Domain> content = result.getContent()
            .stream()
            .map(transformer::createOutput)
            .toList();

    return new ResultPage<>(result.getTotalPages(), result.getTotalElements(), content);
}

Specification.unrestricted() is doing real work in that ternary, not just avoiding a null check. The first instinct is usually to pass Specification.where(null) - which is the older, more commonly documented way of expressing "no restriction" in Spring Data JPA. But recent Spring Data versions added a second where(...) overload for PredicateSpecification, and a bare null literal is ambiguous between the two. The compiler can't infer which where you meant, so it refuses to guess. unrestricted() exists to sidestep exactly that ambiguity, it says "match everything" without needing a null argument for the compiler to argue about.

These issues stay hidden if we only test scenarios where valid parameters are provided. Handling unexpected edge cases is where a test suite truly adds value, the testSearchNullParams test might seem boring because it just calls the search method with null param, but it proved its worth because it prevented letting a bug to impact other parts of the system.

Choosing an In-Memory Database

Component tests need to be fast enough that nobody's tempted to skip them, which rules out spinning up a containerized database for every run of a basic CRUD suite. That leaves a choice between H2 and HSQLDB, and it's worth being honest about what that choice costs.

We run H2 in strict compatibility mode (MODE=MySQL, matching our production dialect) for this layer, mainly because startup is sub-second and there's no container to wait on which matters more than it sounds like it should, multiplied across a few hundred local test runs a day. HSQLDB is arguably more stable in isolation, but its dialect compliance with modern MySQL and PostgreSQL features - JSON columns, window functions, strict identifier quoting, lags enough that a test can pass against HSQLDB and break the moment it hits real MySQL. Either way, neither in-memory engine replicates the production query planner, locking behavior, or dialect-specific edge cases. That was never the job we're asking them to do here.

So we split the responsibility deliberately: H2 handles fast, local validation of the mapping and constraint logic through the DAO proxies in this chapter. Later in the series, when we get to end-to-end integration testing, a dedicated suite runs against a real MySQL 9 Testcontainer to validate the behavior H2 can't, that's the layer that's actually authoritative for production-identical engine behavior, and it's allowed to be slower because it runs less often.

What's Next?

With the DAO layer's persistence boundaries actually proven against real database round-trips - not just Hibernate's bookkeeping, the natural next question is what happens to boundaries like this one under deadline pressure.

In Chapter 8: Why almost every ‘Temporary’ Workaround is Permanent, we step back from the happy-path development. The biggest threat to a clean multi-module boundary usually isn’t a missing design pattern, it’s the workaround that was supposed to be temporary. We’ll look at how an unisolated external dependency, a quick infrastructure leak, or a skipped domain boundary compounds quietly over time, before moving on to building the business service layer.

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 7, use the following link:

GitHub Repository (Tag: chapter-07-dao-testing): 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 6: The DAO Implementation Layer
▶️ Read Chapter 8: Why almost every ‘Temporary’ Workaround is Permanent

Join the Masterclass Journey

The Dao Implementation Layer (Chapter 6)

Kamen — Mon, 17 Aug 2026 06:52:51 +0000

The last 11 years through my career, I've seen codebases that suffered from a silent architectural decay. Check any corporate monolith or a microservice and you will find Spring Data repositories, JPA entity annotations, database specifics, and pagination parameters leaking straight into business services, controllers, and domain models. Developers call it "rapid development." What they've actually built is a tightly coupled codebase that is nearly impossible to support, maintain, and bugfix - especially if there are no tests. And guess what? There are none. Because the code is so tightly coupled, developers don't have the time, or honestly the patience, to mock all those dependencies or try to disentangle the mess just to make their lives easier. Divide and conquer - it's the rule I live by whenever I'm building a new service, REST endpoint, or Kafka integration.

In Chapter 2 and Chapter 3, we drew a hard boundary. We established a 100% pure Java domain model completely free of database metadata, and we defined clean DAO API contracts. In Chapter 4, we've shown why we use direct, JIT-optimized Java transformers instead of reflection-based mapping like MapStruct, and in Chapter 5, we explained why we don't even allow Lombok as a dependency.

Now, it's time to open up the engine room. We are implementing the dao-impl infrastructure module using Java 25, Spring Data JPA, and Hibernate. We will look at how generic hierarchy extension and custom Specification execution keep our persistence details locked safely away from the rest of the application.

`CrudDaoImpl` and `SearchableDaoImpl`

Writing boilerplate CRUD and search logic for every single database table is a waste of resources and time. At the same time, copy-pasting generic utility code creates maintenance nightmares. We solve this by structuring a clean, type-safe inheritance hierarchy.

At the base sits CrudDaoImpl. It handles standard entity creation, lifecycle validation, and ID lookups while enforcing the boundary between domain objects and database entities:

public abstract class CrudDaoImpl<
        IdType,
        Domain extends AbstractCreatable<IdType>,
        Entity extends AbstractCreatableEntity,
        Repo extends CrudRepository<Entity, IdType>
    > implements CrudDao<IdType, Domain> {

    protected final Validator validator;
    protected final Repo repository;
    protected final BiTransformer<Entity, Domain> transformer;

    protected CrudDaoImpl(
        Repo repository,
        BiTransformer<Entity, Domain> transformer,
        Validator validator
    ) {
        this.repository = repository;
        this.transformer = transformer;
        this.validator = validator;
    }

    @Override
    public Domain create(Domain domain) {
        if (domain == null) {
            throw new IllegalArgumentException("Entity is mandatory");
        }
        if (domain.getId() != null) {
            throw new IllegalArgumentException("Entity existing!");
        }

        var entity = transformer.createInput(domain);
        preCreate(entity);
        validateEntity(entity);
        entity = repository.save(entity);

        return transformer.createOutput(entity);
    }

    protected void preCreate(Entity entity) {
        final var now = Instant.now();
        entity.setCreatedAt(now);

        if (entity instanceof AbstractUpdatableEntity updatableEntity) {
            updatableEntity.setUpdatedAt(now);
        }
    }

    protected void preUpdate(Entity entity) {
        if (entity instanceof AbstractUpdatableEntity updatableEntity) {
            updatableEntity.setUpdatedAt(Instant.now());
        }
    }
    // Additional shared CRUD machinery...
}

Notice preCreate and preUpdate reach for instanceof instead of calling setUpdatedAt() directly on Entity. That's deliberate, not a gap. CrudDaoImpl has to stay generic over every entity in the hierarchy, including append-only ones like CategoryAssignment that never extend AbstractUpdatableEntity at all - so Entity can only ever be statically bounded by AbstractCreatableEntity, and the compiler genuinely has no way to know, from inside this class, whether a given Entity also supports updatedAt.

The alternative would be a parallel UpdatableDaoImpl layer bounded by AbstractUpdatableEntity, sitting next to SearchableDaoImpl. That sounds cleaner until you remember Java only allows single inheritance: ProductDaoImpl already extends SearchableDaoImpl, so it couldn't also extend a second base class for updatability without either duplicating the search machinery into a combinator class or moving the whole hierarchy to interfaces with default methods. One instanceof check that anyone can read top to bottom is a smaller price than that.

It's also worth being precise about why this isn't the reflection-based magic we spent earlier chapters arguing against: instanceof is a single, explicit, statically-checked type test that the compiler verifies at compile time and the JIT can inline - nothing here is scanning annotations, generating bytecode, or hiding behind a target/generated-sources folder. Runtime type inspection and reflection-based mapping look similar on the surface, but they aren't the same tool, and conflating them would undercut the whole argument this series has been making.

preCreate captures a single now and reuses it for both fields rather than calling Instant.now() twice, so createdAt == updatedAt on a fresh insert is guaranteed exactly, not just approximately - which is what actually makes that equality useful as a "never touched since creation" signal.

Why timestamps are set here, not left to the database

The Flyway migration for this table will have a DEFAULT CURRENT_TIMESTAMP on the created_at and updated_at columns, so it's worth asking directly: if the database is already going to fill it in, why does preCreate and preUpdate set it again in application code? Because the database default and the application value are solving two different problems.

The DB default is a safety net. It exists for anything that touches the table outside the application: a manual INSERT during an incident, a backfill script, another service hitting the same schema directly. It guarantees the column is never null, no matter what wrote the row.

The application-level value is the source of truth for anything going through this DAO, and setting it explicitly in preCreate matters for a concrete reason: Hibernate doesn't automatically read back database-computed defaults after save(). Relying on the DB default alone means the in-memory entity still has createdAt == null right after the insert, and create() hands that same object straight to transformer.createOutput(entity) - so the caller gets back a Product with a null creation timestamp for an entity that very much has one in the database. That's a real bug, not a style nitpick.

The same reasoning is why preCreate sets updatedAt too, not just createdAt. updated_at is NOT NULL, same as created_at, so it can't be left unset until the first real update without hitting the exact null-after-save problem above - except this time the DB default that would normally paper over it isn't guaranteed to fire at all, since CURRENT_TIMESTAMP defaults are typically written to apply on insert, not on every column independently. Setting both fields from a single captured now sidesteps that entirely, and gets you createdAt == updatedAt as a free signal that a record has never been touched since creation, with no extra flag to maintain.

Immutable Audit Fields on the Domain Side

The DAO layer owning createdAt/updatedAt only works if the domain side agrees to stay out of the way. Earlier versions of our domain classes had default no-arg constructors and public setters, which left audit fields mutable and gave the business layer a path to overwrite them by accident.

We removed both. Domain classes no longer have no-arg constructors, and createdAt/updatedAt are final - set once, via the reconstitution constructors covered in Chapter 2, and never touched again for the life of that object. Our transformers reflect this split cleanly: writing domain-to-entity, createInput() ignores audit fields entirely, since preCreate/preUpdate above already own them on the entity side; reading entity-to-domain, createOutput() is the only caller that ever passes a real createdAt/updatedAt into a domain constructor, because it's the only place that has the real, already-persisted values to pass. No service layer and no client payload has a path to either field.

When a domain requires complex search capabilities, pagination, and sorting, we extend CrudDaoImpl with SearchableDaoImpl. Instead of letting business services deal with JPA Criteria APIs or Spring Data Specification objects, the searchable DAO encapsulates query execution internally:

public abstract class SearchableDaoImpl<
        IdType,
        Domain extends AbstractCreatable<IdType>,
        Entity extends AbstractCreatableEntity,
        Repo extends CrudRepository<Entity, IdType> & JpaSpecificationExecutor<Entity>,
        Params extends AbstractParams<? extends SortBy>
    > extends CrudDaoImpl<IdType, Domain, Entity, Repo> implements SearchableDao<Domain, Params> {

    protected static final Sort ID_DESC_SORT = Sort.by(Sort.Direction.DESC, "id");
    protected static final Sort CREATED_AT_DESC_SORT = Sort.by("createdAt").descending().and(ID_DESC_SORT);

    protected SearchableDaoImpl(
        Repo repository,
        BiTransformer<Entity, Domain> transformer,
        Validator validator
    ) {
        super(repository, transformer, validator);
    }

    @Override
    public ResultPage<Domain> search(Params params) {
        final Pageable pageable = toPage(params);
        final Specification<Entity> spec = createSpecification(params);
        final Page<Entity> result = repository.findAll(spec, pageable);
        final List<Domain> content = result.getContent()
                .stream()
                .map(transformer::createOutput)
                .toList();

        return new ResultPage<>(
            result.getTotalPages(),
            result.getTotalElements(),
            content
        );
    }

    protected abstract Specification<Entity> createSpecification(Params params);
}

Why `Repo` needs two bounds, not one

Look closely at the type bound on SearchableDaoImpl:

Repo extends CrudRepository<Entity, IdType> & JpaSpecificationExecutor<Entity>

That & is an intersection type, and it's doing more work than it looks like. CrudRepository gives us save(), findById(), delete() - the basic CRUD operations that CrudDaoImpl needs. But CrudRepository has no idea what a Specification is, that interface lives entirely in JpaSpecificationExecutor, which is what actually declares findAll(Specification<T>, Pageable).

If we bounded Repo on CrudRepository alone, the search() method above simply wouldn't compile - repository.findAll(spec, pageable) calls a method that doesn't exist on that interface. If we bounded it on JpaSpecificationExecutor alone, we'd lose save() and the rest of the CRUD surface that CrudDaoImpl depends on. We need both interfaces satisfied by the same concrete repository type, and Java's intersection bounds are the only clean way to express "this generic parameter must implement A and B" without collapsing the two responsibilities into one bloated interface.

The payoff shows up downstream, in ProductRepository and CategoryRepository, they simply extend both interfaces, and every method from both becomes available on repository inside the DAO, fully typed, with no casting. If any entity doesn't need to be paginated, it will simply extend only the CrudRepository.

Notice also how sorting is handled above. By appending id DESC as a deterministic tie-breaker to every sort order, we eliminate unstable pagination results when multiple records share identical timestamps or property values. I've chased that exact bug in production before - page 3 of a listing quietly returns a row you already saw on page 2, because two rows had the same createdAt millisecond and the database made no promises about their relative order.

`ProductDaoImpl` and `CategoryDaoImpl`

With the generic abstraction we just created, implementing concrete data access objects requires minimal code. Look at how clean CategoryDaoImpl is:


public class CategoryDaoImpl extends SearchableDaoImpl<
        UUID,
        Category,
        CategoryEntity,
        CategoryRepository,
        CategorySearchParams
        > implements CategoryDao {

    public CategoryDaoImpl(CategoryRepository repository, Validator validator) {
        super(repository, CategoryTransformer.instance, validator);
    }

    @Override
    protected Specification<CategoryEntity> createSpecification(CategorySearchParams params) {
        return (root, query, cb) -> {
            final List<Predicate> predicates = new ArrayList<>();

            if (params.getName() != null && !params.getName().isBlank()) {
                predicates.add(cb.like(cb.lower(root.get("name")), "%" + params.getName().toLowerCase() + "%"));
            }

            if (params.getActive() != null) {
                predicates.add(cb.equal(root.get("active"), params.getActive()));
            }

            return cb.and(predicates.toArray(new Predicate[0]));
        };
    }
}

For domain-specific queries like SKU lookups, ProductDaoImpl delegates directly to custom repository methods while keeping the transformation logic fully explicit:

public class ProductDaoImpl extends SearchableDaoImpl<
        UUID,
        Product,
        ProductEntity,
        ProductRepository,
        ProductSearchParams
    > implements ProductDao {

    public ProductDaoImpl(ProductRepository repository, Validator validator) {
        super(repository, ProductTransformer.instance, validator);
    }

    @Override
    public Product loadBySku(String sku) {
        final var product = repository.loadBySku(sku);
        return transformer.createOutput(product);
    }

    @Override
    protected Specification<ProductEntity> createSpecification(ProductSearchParams params) {
        return (root, query, cb) -> {
            final List<Predicate> predicates = new ArrayList<>();

            if(params.getName() != null && !params.getName().isBlank()){
                predicates.add(cb.like(cb.lower(root.get("name")), "%" + params.getName().toLowerCase() + "%"));
            }

            return cb.and(predicates.toArray(new Predicate[0]));
        };
    }
}

Why I don't use Spring Data Method Naming

Look at ProductRepository, or any custom repository method in this codebase, and you won't find something like findByProductStatusAndNameContainingIgnoreCaseAndCreatedAtAfterOrderByPriceDesc. Spring Data will happily generate that query for you from the method name alone - no annotation, no SQL, just string parsing at startup. It seems easy and intuitive, but when we get in a production service taking real traffic, I don't want it anywhere near my persistence layer, for a few concrete reasons.

The first is fragility, if we rename a field on the entity, let's say for example sku becomes productSku, and the derived-name query built on the old name either breaks at startup with a PropertyReferenceException, or, depending on how the method's structured, doesn't break at all and just silently stops matching what you think it matches. Either way, the compiler never told you. An explicit query, by contrast, references the actual JPQL or SQL, so a rename is a normal refactor with a normal compile error, not a runtime surprise waiting for the right request to trigger it.

The second is readability, and the method name above is the proof, once a query needs more than two or three conditions, the method name stops being a name and becomes a run-on sentence encoding your entire WHERE clause in camelCase. Nobody reads that and understands the query faster than they'd understand the five lines of JPQL it's standing in for - they read it slower, and they have to mentally decode ContainingIgnoreCase and OrderByPriceDesc back into SQL concepts they already know.

The third is the one that actually matters most at midnight during an incident: derived queries hide the generated SQL from you until it runs. An explicit @Query shows you the exact projection, the exact joins, the exact fetch strategy, right there in the repository interface, during code review, before it had the chance to quietly become an N+1 problem in production.

ProductRepository's loadBySku makes this concrete:

public interface ProductRepository extends CrudRepository<ProductEntity, UUID>, JpaSpecificationExecutor<ProductEntity> {

    @Query("SELECT p FROM ProductEntity p WHERE p.sku = :sku")
    ProductEntity loadBySku(@Param("sku") String sku);
}

Spring Data could derive this one from a method named findBySku without any annotation at all, it's simple enough. I write the @Query anyway, because the moment this method needs a join or a second condition, I want it to already look like every other query in this codebase, not like a special case that started simple and grew a name nobody can parse at a glance.

What's Next?

We've built a flexible persistence infrastructure: clean generic DAO hierarchies, explicit Java transformers, and validation that fails fast in application code instead of at the database.

Spoiler alert: a green Spring integration test does not necessarily prove that an entity can be written and hydrated correctly by the database. In Chapter 7, we expose Hibernate’s write-behind cache and dirty checking. When a test’s purpose is to verify database constraints or fresh hydration, it should intentionally use .flush() and .clear() at the relevant boundary rather than accidentally read managed state from the persistence context.

See you in the next chapter.

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 6, use the following link:

GitHub Repository (Tag: chapter-06-dao-impl): 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 5: The Lombok Illusion
▶️ Read Chapter 7: The Persistence layer Testing

Join the Masterclass Journey

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

Join the Masterclass Journey

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

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

Why almost every ‘Temporary’ Workaround is Permanent (Chapter 8)

The shortcut

What it should have looked like

The same failure, dressed differently

The actual cost, after the fact

The part that doesn't fit in a retro

What's Next

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Reading & Interview Preparation

What Spring Data Tests Can Miss: Testing Beyond Hibernate’s Persistence Context (Chapter 7)

What Standard Spring Tests Actually Test

Forcing a Real Write-and-Read Boundary

Ground-Zero: The TablesEraser

Reusable Tests: AbstractCrudTestCase & AbstractSearchableTestCase

What the Null-Params Test Actually Caught

Choosing an In-Memory Database

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

The Dao Implementation Layer (Chapter 6)

CrudDaoImpl and SearchableDaoImpl

Why timestamps are set here, not left to the database

Immutable Audit Fields on the Domain Side

Why Repo needs two bounds, not one

ProductDaoImpl and CategoryDaoImpl

Why I don't use Spring Data Method Naming

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

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?

Ground-Zero: The `TablesEraser`

Reusable Tests: `AbstractCrudTestCase` & `AbstractSearchableTestCase`

`CrudDaoImpl` and `SearchableDaoImpl`

Why `Repo` needs two bounds, not one

`ProductDaoImpl` and `CategoryDaoImpl`

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