DEV Community: Kyryl

"🚩 readOnly = true Is Not a Comment"

Kyryl — Fri, 03 Jul 2026 18:54:38 +0000

@Transactional(readOnly = true) gets slapped on every query method out of habit, the way people sprinkle final on local variables. A marker for the next reader, a bit of documentation that says "this method does not write anything." Except it is not documentation. It is a flag that Hibernate and, if you have set it up, your Postgres routing DataSource both actually read and act on.

Ignore that and you get one of two failures. Either a write silently vanishes with no exception, or every read in your app hits the primary database because nothing ever told the driver it was allowed to go to a replica.

What people think readOnly = true does

The common mental model: it is a hint for whoever reads the code later, maybe a small optimization Spring does under the hood, nothing that changes behavior you would notice. Under that model, marking a method readOnly = true when it is not strictly read-only feels harmless. Worst case, a wasted annotation.

That model is wrong on the part that matters most: the flush mode.

What it actually does: changes Hibernate's flush mode

Inside a transaction marked readOnly = true, Spring propagates that flag down to the underlying Hibernate Session and sets its flush mode to manual. Normally, Hibernate auto-flushes: before you run a query, it checks the persistence context for dirty managed entities and writes them out first, so the query sees consistent state. Under manual flush mode, none of that happens.

@Transactional(readOnly = true)
Report load(Long id) {
    // Hibernate sets FlushMode.MANUAL here
    // no dirty-checking, no auto-flush
    return repo.findById(id);
}

For a genuinely read-only method, this is a pure win. Skipping dirty-checking on every entity in the persistence context is real overhead, and readOnly = true removes it. That is the entire justification for slapping it on query methods, and it is a good one, right up until someone mutates state inside that method.

The trap: a write inside a read-only transaction

Here is the version that gets shipped:

@Transactional(readOnly = true)
// "just documentation", right?
Report loadAndPatch(Long id) {
    Report r = repo.findById(id);
    r.setLastViewedAt(now()); // looks persisted
    return r;
}
// ...it never flushes. The update vanishes.

r is a managed entity. setLastViewedAt mutates its field. Every instinct built from normal Spring Data usage says this change will be picked up on flush, the way it would in any other @Transactional method. It will not. The flush mode is manual, nothing triggers a flush, and the transaction commits with the mutation sitting in memory and nowhere else.

No exception. Nothing in the logs. The method returns a Report object with the field looking correctly set, because the in-memory object really was mutated. Only the database was never told. The bug surfaces days or weeks later as "last viewed timestamps are not updating," and the first three places anyone looks are the query, the column mapping, and the transaction boundary. The annotation that caused it reads like the most innocent line in the method.

This is worse than a typo in a query. A typo throws. This just quietly does nothing, forever, until someone notices the data is stale.

The other half: it can route your read to a replica

The flush-mode change is reason enough to take readOnly = true seriously, but on a Postgres setup with read replicas it does a second job. If you have wired an AbstractRoutingDataSource that inspects the current transaction's read-only flag, that flag is the actual signal deciding which physical database the query hits:

class ReplicaRoutingDataSource
        extends AbstractRoutingDataSource {

    protected Object determineCurrentLookupKey() {
        boolean ro = TransactionSynchronizationManager
            .isCurrentTransactionReadOnly();
        return ro ? "replica" : "primary";
    }
}

TransactionSynchronizationManager.isCurrentTransactionReadOnly() returns exactly the value Spring set from your @Transactional(readOnly = true) annotation. Get the annotation right and your reads spread across replicas, taking load off the primary. Get it wrong, forget it on a genuinely read-only method, and that query hits the primary for no reason. Put it on a method that writes, and depending on your routing setup you can end up sending a write-carrying transaction at a replica connection that rejects writes outright, or worse, one that does not reject them and you get an inconsistency between primary and replica state.

The annotation is not decoration in either direction. It is the single signal two separate systems, your ORM's flush behavior and your connection routing, both key off.

The honest trade-off

Mislabeling a write path as readOnly = true fails silently, not loudly. That is the real cost here, and it is worse than it sounds. A method that should compile-error or throw at runtime instead just does nothing to the database, and the visible parts of the system, the returned object, the lack of any exception, all look correct. You do not get a stack trace pointing at the problem. You get a support ticket three weeks later asking why a field never updates.

The fix is not to avoid readOnly = true. It genuinely helps, both for the flush-mode overhead and for replica routing. The fix is discipline: only mark a method readOnly = true when you have actually checked that it never mutates a managed entity, directly or through a called method. Treat the annotation as a contract, not a habit. If a method's purpose changes later and someone adds a write to it, the missing exception means nobody will be warned. Code review is the only real defense, along with grep-ing for readOnly = true methods that call setters on entities pulled from a repository.

Have you tracked a "why is this not saving" bug back to a stray readOnly = true? What caught it, a test, a code review, or production data going stale?

"🔇 Calling Your Own @Async Method Does Nothing"

Kyryl — Fri, 03 Jul 2026 18:54:03 +0000

Called this.notify(o) from inside placeOrder(), both methods on the same @Service. No exception. No warning. It just ran the mailer call inline, blocking the request thread like @Async was never there.

Here is the setup that broke:

@Service
class OrderService {

    void placeOrder(Order o) {
        save(o);
        this.notify(o); // bypasses the proxy
    }

    @Async
    void notify(Order o) {
        mailer.send(o); // never actually async
    }
}

Nothing here looks wrong on a first read. notify() is annotated @Async, it lives on a @Service, the class is wired into the container correctly. And yet placeOrder() blocks on mailer.send() every single time. No thread pool, no exception, no log line telling you the annotation got ignored.

Why this.method() Skips the Proxy

Spring AOP does not rewrite your class. When you annotate a method with @Async, @Transactional, or @Cacheable, Spring wraps the bean in a proxy: a JDK dynamic proxy if the bean implements an interface, a CGLIB subclass otherwise. Every advice you rely on, the async executor handoff, the transaction interceptor, the cache lookup, lives on that proxy, not on your class.

When another bean calls orderService.notify(o), it is calling the proxy. The proxy runs its advice, then delegates to the real method. That is the whole mechanism working as designed.

When placeOrder() calls this.notify(o), there is no proxy in the picture. this inside a Spring-managed object is the raw, unproxied instance. It was never wrapped, because Spring only ever gets a chance to wrap the object other beans see when they ask the container for it. The object refers to itself directly, and Java resolves this.notify(o) as an ordinary virtual method call. Spring cannot intercept a call it never sees, because the call never leaves the object.

This is not a bug in Spring. It is a direct consequence of how proxy-based AOP works, and it applies to every annotation-driven aspect Spring ships: @Async, @Transactional, @Cacheable, @Retryable, custom @Aspect advice, all of it. Self-invocation quietly skips every one.

Fix 1: Split the Callee Into a Second Bean

The textbook answer is to make sure the call always crosses a real bean boundary. Pull the annotated method out into its own class:

@Service
class OrderService {
    private final NotifyService notifyService;

    void placeOrder(Order o) {
        save(o);
        notifyService.notify(o); // real proxy
    }
}

@Service
class NotifyService {
    @Async
    void notify(Order o) {
        mailer.send(o); // now actually async
    }
}

This works. notifyService is a container-managed reference, Spring hands OrderService the proxy, and the call to notify() goes through it like any other cross-bean call. @Async fires, mailer.send() runs on the executor, placeOrder() returns immediately.

The cost is a class that has no reason to exist except to dodge this one behavior. NotifyService is not a domain concept. It does not group related responsibilities, it does not hide an implementation detail worth hiding, it exists purely because Spring's proxy model requires a bean boundary between caller and callee. Every time someone reads the codebase and asks "why is notification logic split out into its own service", the honest answer is "so a self-invocation bug does not resurface", which is not an answer that belongs in a design review.

For a genuinely separate concern, this split is the right call regardless of the AOP issue. For a single method that happens to need @Async, it is architecture shaped by a framework limitation, not by the domain.

Fix 2: Inject the Bean Into Itself

The pragmatic fix keeps the method where it belongs and instead gets a real proxy reference inside the class:

@Service
class OrderService {

    @Lazy @Autowired
    private OrderService self; // proxy to itself

    void placeOrder(Order o) {
        save(o);
        self.notify(o); // through the proxy, for real
    }

    @Async
    void notify(Order o) {
        mailer.send(o);
    }
}

self is a field of the bean's own type, autowired like any other dependency. Spring resolves it to the actual proxy, the same object every other bean gets when it asks the container for an OrderService. Calling self.notify(o) instead of this.notify(o) sends the call through that proxy, the async advice runs, and mailer.send() finally executes on the executor instead of the caller's thread.

The @Lazy is not optional. Without it, Spring tries to fully construct OrderService, including resolving its self field, which means it needs a fully constructed OrderService to finish constructing OrderService. That is a circular dependency, and Spring fails at startup rather than silently accepting it. @Lazy tells Spring to inject a lazy proxy for self instead, one that only resolves the real bean the first time self.notify() (or any method on it) actually gets called, well after the container has finished wiring everything else. By then OrderService exists, the cycle never has to resolve eagerly, and startup succeeds.

The Honest Trade-off

Self-injection needs @Lazy to avoid that circular-dependency failure, which means the fix does not work by just adding a field, it works by adding a field plus an annotation whose job is to explain to Spring why injecting a bean into itself is not actually circular. Anyone unfamiliar with the trick reads @Lazy @Autowired private OrderService self; and reasonably assumes something is wrong with the code, because nothing about "inject the class into itself" looks intentional on a first pass.

It is still the better trade. Splitting notify() into NotifyService solves the same problem by growing the class hierarchy, and that growth has to be maintained forever: another file, another bean to wire in tests, another indirection for anyone tracing the call path, all to work around a framework detail that has nothing to do with what the domain actually looks like. The self-injected field is uglier at the point you read it, but it stays contained to the one class that needs it, and it does not force a design decision that only exists because of AOP.

Neither fix is free. Pick the one whose cost you would rather explain in a code review: a class that exists for no domain reason, or a field that looks wrong until someone tells you why it is there.

Ever shipped a silently-skipped @Async or @Transactional to production because of self-invocation? What finally gave it away?

"🥊 Your Retry Aspect Is Retrying a Dead Transaction"

Kyryl — Fri, 03 Jul 2026 18:53:28 +0000

A retry aspect and a @Transactional aspect were both wrapping the same method. Neither had @Order. I assumed Spring would nest them the way I had pictured in my head. It did not, and the failure mode was a UnexpectedRollbackException on a method that should have quietly succeeded on the third attempt.

Here is the setup:

@Aspect
@Component
class RetryAspect {
    @Around("@annotation(Retryable)")
    Object retry(ProceedingJoinPoint pjp) {
        // retry loop around pjp.proceed()
    }
}

@Aspect
@Component
class TxAspect {
    @Around("@annotation(Transactional)")
    Object wrap(ProceedingJoinPoint pjp) {
        return tx.execute(status -> proceed(pjp));
    }
}
// no @Order on either one

Both aspects match the same method through two different annotations. Nothing in that code tells Spring which one should run first. Spring AOP will still pick something, deterministically for a given build, but that something is not documented, not guaranteed across versions, and not something you chose.

Why nesting order matters here

An @Around advice wraps the method call. When two advices target the same join point, they nest like Russian dolls: the outer one runs first, calls into the inner one, which calls into the actual method. Which aspect ends up outer decides what the inner one is running inside of.

For a retry aspect and a transaction aspect, that is not a cosmetic detail. It decides whether "retry" means "retry the whole transaction" or "retry inside a transaction that has already failed once."

Wrong order: transaction outer, retry inner

@Aspect
@Order(1)   // OUTER: opens the tx first
class TxAspect {
    @Around("@annotation(Transactional)")
    Object wrap(ProceedingJoinPoint pjp) {
        return tx.execute(status -> proceed(pjp));
    }
}

@Aspect
@Order(2)   // INNER: retries land in that tx
class RetryAspect {
    @Around("@annotation(Retryable)")
    Object retry(ProceedingJoinPoint pjp) {
        // retry loop around pjp.proceed()
    }
}

Lower @Order values run first on the way in, which puts TxAspect on the outside. One transaction opens before the retry loop even starts, and every retry attempt runs inside that same transaction.

That is the bug. The moment the first attempt throws whatever transient exception the retry logic is supposed to swallow, Spring's transaction machinery marks the current transaction rollback-only. That flag does not clear on the next attempt. It cannot, it is the same transaction. So attempt two runs inside a transaction that is already condemned. It might even succeed on its own terms, the business logic completes fine, but when the retry aspect's @Around unwinds and the transaction tries to commit, it hits the rollback-only flag and throws UnexpectedRollbackException instead of committing anything.

From the caller's side this looks insane. The logs show the operation succeeding on retry, then the whole thing still fails. The retry loop did its job. The transaction it was retrying inside of was already dead before the second attempt began.

Right order: retry outer, transaction inner

@Aspect
@Order(1)   // OUTER: retries first
class RetryAspect {
    @Around("@annotation(Retryable)")
    Object retry(ProceedingJoinPoint pjp) {
        // retry loop around pjp.proceed()
    }
}

@Aspect
@Order(2)   // INNER: fresh tx per attempt
class TxAspect {
    @Around("@annotation(Transactional)")
    Object wrap(ProceedingJoinPoint pjp) {
        return tx.execute(status -> proceed(pjp));
    }
}

Swap the @Order values and the nesting flips. RetryAspect is now outer, so its retry loop calls into TxAspect fresh on every attempt. TxAspect opens a brand-new transaction each time it is invoked, because from its point of view each retry is a completely separate call. Attempt one fails and rolls back cleanly. Attempt two starts an unmarked, unrelated transaction and gets a real shot at succeeding. No transaction ever carries scar tissue from a previous attempt.

This is the nesting you actually want for "retry a transactional operation": each attempt is its own unit of work, committed or rolled back on its own, with no memory of the attempt before it.

The honest trade-off

A fresh transaction per retry attempt is not free. Each one is a new database round trip: begin, do the work, commit or roll back. If your retry policy allows five attempts, a failing call can now open five transactions instead of one, and depending on your isolation level and connection pool size, that adds real latency and real contention under load.

That cost is worth paying for genuinely transient failures: a deadlock victim getting picked, a connection reset mid-query, a lock wait timeout. Those are cases where the exact same operation, run again a moment later, plausibly succeeds because the condition that broke it was temporary.

It is not worth paying for a bug. If the method fails because of bad input, a null somewhere it should not be, a constraint violation that is always going to violate, retrying it just runs the same doomed logic multiple times against a fresh transaction each time, burning connections and latency for a result that was never going to change. Retry policies need to be scoped to exceptions that are actually retryable, not Exception.class as a catch-all, or this whole ordering fix just gives you a more expensive way to fail five times instead of once.

@Order is not decoration on these two annotations. It is the only thing that decides whether "retry" means a clean second attempt or a slow-motion replay inside a transaction that already gave up.

Have you hit an aspect ordering bug like this, and how did you end up debugging it back to @Order?

"🔁 Your Prototype Bean Is a Singleton in Disguise"

Kyryl — Fri, 03 Jul 2026 18:52:46 +0000

A prototype-scoped bean injected into a singleton is created exactly once. That is not a corner case, it is how Spring's dependency injection works by design, and it catches people who assume @Scope("prototype") means "new instance whenever someone asks."

Here is the setup that trips people up:

@Component
@Scope("prototype")
class TokenGenerator {
    private final String seed = UUID.randomUUID().toString();

    String next() {
        return seed + "-" + System.nanoTime();
    }
}

@Service
class ReportService {

    private final TokenGenerator gen;

    ReportService(TokenGenerator gen) {
        // resolved ONCE, right here, when the container wires ReportService
        this.gen = gen;
    }

    String generate() {
        return gen.next();
    }
}

ReportService is a singleton. Spring builds it once at startup, and to build it, it has to resolve the TokenGenerator constructor argument. That resolution happens exactly one time. The prototype scope on TokenGenerator never gets a second chance to do its job, because nothing ever asks the container for another one. ReportService just holds onto the first instance it got, for the rest of the application's life.

If TokenGenerator were stateless, nobody would ever notice. The bug shows up the moment the prototype bean carries state that is supposed to reset per use, a running total, a per-request seed, a cache that should not outlive one call. Then every "fresh" instance is actually the same object, and callers start stepping on each other's state.

Fix 1: ApplicationContext.getBean() — it works, but it is ugly

The instinctive patch is to stop injecting the bean directly and instead ask the container for it on demand:

@Service
class ReportService {

    @Autowired
    private ApplicationContext ctx;

    String generate() {
        TokenGenerator gen = ctx.getBean(TokenGenerator.class);
        return gen.next();
    }
}

This does fix the bug. Every call to generate() pulls a brand-new TokenGenerator from the container, because getBean() triggers scope resolution every time it runs, not just at wiring time.

The problem is what it costs you. ReportService now holds a live reference to the whole ApplicationContext, which means it can reach any bean in the application, not just the one it needs. Unit testing gets worse too: instead of mocking one collaborator, you have to mock the entire context or stand up a real one. And the lookup is stringly typed by class, which means a typo or a refactor that renames the bean fails at runtime, not at compile time. It works. It also does not belong in application code that has any other option.

Fix 2: an abstract @Lookup method — cleaner, still Spring-flavored

Spring has a purpose-built mechanism for exactly this case:

@Service
abstract class ReportService {

    @Lookup
    abstract TokenGenerator gen();

    String generate() {
        return gen().next();
    }
}

@Lookup tells Spring to generate a subclass of ReportService at runtime (via CGLIB) that overrides gen() to fetch a fresh TokenGenerator from the container every time it is called. Your code never touches ApplicationContext directly, never does a stringly-typed getBean() call, and the method signature documents exactly what type it returns.

The catch: ReportService and the gen() method cannot be final, because CGLIB needs to subclass them. Constructor injection for other dependencies still works fine alongside @Lookup, but the class itself has to stay proxyable. It is still coupled to Spring, just through an annotation instead of an API call, and it depends on a runtime-generated subclass existing, which occasionally surprises people debugging stack traces for the first time.

Fix 3: inject ObjectProvider — the one to actually reach for

The cleanest option skips both the container reference and the CGLIB proxy:

@Service
class ReportService {

    private final ObjectProvider<TokenGenerator> genProvider;

    ReportService(ObjectProvider<TokenGenerator> genProvider) {
        this.genProvider = genProvider;
    }

    String generate() {
        TokenGenerator gen = genProvider.getObject();
        return gen.next();
    }
}

ObjectProvider<T> is a plain constructor-injected dependency, no ApplicationContext, no abstract class, no CGLIB subclass. Calling .getObject() resolves a fresh prototype bean at that exact moment, and only at that moment. The rest of ReportService stays a normal, final, easily-mocked class. If you are on jakarta.inject, Provider<T> gives you the same behavior with a one-method interface, if you prefer not to depend on a Spring-specific type at all.

This is also the version that is easiest to test. Mock ObjectProvider<TokenGenerator> to return a stub TokenGenerator from getObject(), and ReportService never needs a real Spring context in the test.

The honest trade-off

None of these three fixes matter if TokenGenerator is stateless. A stateless prototype bean behaves identically to a singleton, so field-injecting it directly is not a bug, it is just an unnecessary scope declaration. Reach for ObjectProvider only when the prototype bean genuinely carries per-call state that would otherwise leak between callers. Adding indirection to fetch a bean that never needed to be re-created is its own kind of mistake, just a quieter one.

There is a real cost either way: ObjectProvider (or @Lookup, or getBean()) adds a layer of indirection that a reader has to understand before they see why the bean is not just constructor-injected like everything else. That indirection earns its keep exactly when the state leak is real, and nowhere else.

Have you shipped the ApplicationContext.getBean() version to production before catching it in review? What made you notice?

🧱 Your Test Fixtures Are Lying About What Matters

Kyryl — Fri, 03 Jul 2026 11:51:05 +0000

Open a test file with a thirty-argument constructor call and try to spot the one value the test actually cares about. You cannot do it at a glance. Every field looks equally important, because the constructor treats them that way.

Here is the domain object in question, a fairly ordinary User:

public class User {
    private final UUID id;
    private final String email;
    private final String firstName;
    private final String lastName;
    private final String phone;
    private final Address address;
    private final Role role;
    private final AccountStatus status;
    private final boolean emailVerified;
    private final boolean twoFactorEnabled;
    private final String sessionToken;
    private final Instant tokenIssuedAt;
    private final Instant createdAt;
    private final Instant lastLoginAt;
    // ... 16 more fields exactly like this

    public User(UUID id, String email, String firstName, String lastName,
                String phone, Address address, Role role, AccountStatus status,
                boolean emailVerified, boolean twoFactorEnabled, String sessionToken,
                Instant tokenIssuedAt, Instant createdAt, Instant lastLoginAt
                /* ...16 more parameters */) {
        // assign everything
    }
}

Now here is a test that exercises exactly one behavior: a session with an expired token gets rejected.

@Test
void expiredTokenIsRejected() {
    User user = new User(
        UUID.randomUUID(),
        "jane.doe@example.com",
        "Jane",
        "Doe",
        "+1-555-0100",
        Address.of("221B Baker St", "London", "NW1", "UK"),
        Role.CUSTOMER,
        AccountStatus.ACTIVE,
        true,
        false,
        "expired-token-abc123",           // <- the one value this test cares about
        Instant.now().minus(Duration.ofDays(30)),
        Instant.now(),
        null
        // ... 16 more arguments exactly like this
    );

    assertThat(sessionService.isValid(user)).isFalse();
}

The fact under test, a token issued thirty days ago, sits at position eleven out of thirty. A reviewer has to read the whole argument list to find it, and count commas to be sure they found the right one. Six months from now, when User grows a preferredLanguage field, every one of these constructor calls either breaks or silently gets a null nobody reviewed.

Why this happens

Nobody designs a test this way on purpose. It happens because the constructor is the only tool available, and the constructor's job is to build a fully valid object, not to communicate what a specific test is checking. The constructor is honest about the shape of User. It says nothing about which of those thirty values is the point.

That is the actual problem, and it is not verbosity. It is signal-to-noise. A fixture constructor forces every test to restate the entire object graph, every time, whether that test cares about eviction dates, marketing consent, or nothing but a single boolean.

The pattern

A test data builder inverts the default. It ships with sensible, valid values for everything, and exposes named methods for the one or two things a given test needs to override.

public class UserTestDataBuilder {
    private UUID id = UUID.randomUUID();
    private String email = "jane.doe@example.com";
    private String firstName = "Jane";
    private String lastName = "Doe";
    private Role role = Role.CUSTOMER;
    private AccountStatus status = AccountStatus.ACTIVE;
    private String sessionToken = "valid-token";
    private Instant tokenIssuedAt = Instant.now();
    // ... every other field, defaulted to something valid

    public static UserTestDataBuilder aUser() {
        return new UserTestDataBuilder();
    }

    public UserTestDataBuilder withExpiredToken() {
        this.sessionToken = "expired-token-abc123";
        this.tokenIssuedAt = Instant.now().minus(Duration.ofDays(30));
        return this;
    }

    public User build() {
        return new User(id, email, firstName, lastName, /* ... */ sessionToken, tokenIssuedAt, /* ... */);
    }
}

And the test collapses to this:

@Test
void expiredTokenIsRejected() {
    User user = aUser().withExpiredToken().build();

    assertThat(sessionService.isValid(user)).isFalse();
}

Everything except the token is defaulted. The reader does not scan fourteen positional arguments looking for the relevant one, they read withExpiredToken() and move on. When User gains a preferredLanguage field next sprint, it gets a default inside the builder once, and every existing test keeps compiling, untouched.

The honest trade-off

This is not free. Someone has to write the builder class, and someone has to keep its defaults sensible as the domain object evolves. That is a second place User lives, and it can drift out of sync with real constraints if nobody updates it when validation rules change.

There is a subtler cost too. A "just valid enough" default can silently satisfy a constraint the test author never thought about. If AccountStatus.ACTIVE is the builder's default and a bug only reproduces for AccountStatus.PENDING_VERIFICATION, the builder hides that gap exactly as effectively as a thirty-argument constructor call hides the one field that matters. Defaults reduce noise, they do not replace judgment about what a test should actually cover.

For a domain object with three or four fields, none of this is worth it, a plain constructor is fine. It starts paying for itself once an object crosses somewhere around ten to fifteen fields, or once it shows up in more than a handful of tests.

What you actually gain

Reviewers read intent, not positions. New fields do not break unrelated tests. And the one thing under test is loud, instead of buried in a wall of arguments a reviewer has learned to skim past, which is its own kind of risk: skimmed code is where the real bug in position eleven goes unnoticed.

What do you reach for once your domain objects outgrow a plain constructor call: an Object Mother, a builder like the one above, or a random test-data library like Instancio or EasyRandom? Curious what actually holds up at scale versus what looks good in a blog post.

"🧪 Good Enough Tests Died When AI Started Writing Them"

Kyryl — Tue, 30 Jun 2026 19:16:56 +0000

For years, integration tests got a quiet pass. "Good enough, not perfect" was an acceptable answer, because writing them by hand was expensive and somebody had to ship the feature. That excuse just expired. AI writes these tests now, the authoring cost collapsed, and the bar moves from good enough to exact.

Before the how, the where.

This is about the middle of the pyramid

Three layers, and this post is only about one of them.

Unit tests sit at the bottom. Fast, pure, no infrastructure. Not the topic here.
Integration tests sit in the middle. Your code against real infrastructure and mocked externals. This is the layer everyone gets wrong.
End-to-end tests sit at the top. A thin layer that hits the real vendor sandbox and proves the whole thing actually works.

Almost nobody does the middle layer properly. Teams fall into one of two traps. They mock everything, so the suite stays green while production breaks, because the mocks drifted and the tests only proved their own assumptions. Or they skip the middle entirely and lean on a handful of e2e tests to somehow cover the gap. A disciplined integration layer is rare.

The rule: split by ownership

The fix is not "mock or real". It is one question asked per dependency: do I own this?

Ownership decides fidelity. If you own it, run it for real. If you do not, mock it at the wire. That single cut resolves almost every "should I mock this" argument.

Infra you own: run it for real, at the prod version

Your database, your message broker, your cache, your sibling services. Run them in containers that match production. Not H2 standing in for Postgres. Not an embedded broker. The real engine.

Two ways to get there. Testcontainers spins real containers from inside the test:

@Container
static PostgreSQLContainer<?> db =
    new PostgreSQLContainer<>("postgres:16.3");

@Container
static KafkaContainer kafka =
    new KafkaContainer("apache/kafka:3.8.0");

Or a docker-compose that brings the whole stack up once and lets the suite run against it:

services:
  postgres:
    image: postgres:16.3          # match prod exactly
  kafka:
    image: apache/kafka:3.8.0     # KRaft, no ZooKeeper
    environment:
      KAFKA_PROCESS_ROLES: broker,controller

Both are valid. Testcontainers gives you per-test lifecycle and zero shared state. Compose gives you one warm stack and faster local loops. Pick per project.

The part people skip is the version. Matching the engine is not enough, you have to match the version. Production runs Kafka in KRaft mode, and the test suite still runs Kafka plus ZooKeeper from a template somebody copied in 2021. That drift used to be tolerable. It is not anymore. The behavior, the configs, the failure modes differ. Pin the test image to what production runs, and bump it when production bumps.

The third-party API you do not own: WireMock the wire

For the external HTTP API you do not control, mock it at the wire. WireMock is the tool (MockServer works too). It stands up a fake HTTP server, so you stub the response and verify the call:

stubFor(post("/charges")
    .willReturn(okJson("{ \"id\": \"ch_1\" }")));

// your real client runs against the fake server

verify(postRequestedFor(urlEqualTo("/charges"))
    .withRequestBody(matchingJsonPath("$.amount")));

The critical word is wire. Stub the wire, not your Java client. The moment you mock your own client class, you mock away serialization, the retry policy, timeouts, and error mapping. That is exactly the code most likely to carry the bug. WireMock leaves all of it running and only fakes the server on the other end. And in the AI-era bar, every outbound call gets both a stub and a verify, so a silently-dropped or malformed request fails the test instead of slipping through.

The safety net: a wire mock can lie

A stub is a snapshot. The day the vendor changes their contract, your mock keeps returning the old shape and your green suite is now fiction. This is the real cost of mocking, and pretending otherwise is dishonest.

That is precisely the job of the thin e2e-against-sandbox layer at the top of the pyramid. It runs against the vendor's real sandbox, out of band from the main suite, and catches the drift the mock cannot. Back it with recorded real responses or contract tests so the stubs stay honest.

The honest trade-off

AI collapsed the cost of writing these tests. It did not collapse the cost of running them.

You still pay for Docker in CI and the startup seconds each container costs, which you mitigate with container reuse, singletons, or a compose stack that comes up once. You now owe version upkeep every time production upgrades, because a pinned image that drifts behind prod is its own quiet lie. And the wire mocks still rot, so the e2e-on-sandbox layer is not optional.

The bar is higher because the labor is finally cheap. The runtime and maintenance bill is still real, and you should budget for it instead of pretending the AI made testing free.

Now that AI writes the tests, is "good enough" coverage still an acceptable answer? And has a lying mock or a version mismatch ever shipped a bug past your integration suite?

🗄️ The JPA Enum Default Quietly Corrupts Your Data

Kyryl — Mon, 29 Jun 2026 18:48:13 +0000

You add an enum to an entity, slap @Enumerated on it, and move on. Five seconds. It is the kind of decision nobody writes a design doc for.

Then six months later a row comes back as SHIPPED when it was PAID, no exception was thrown, no query failed, and you spend an afternoon learning that the default you never thought about has been silently rewriting history.

Here is the order lifecycle we will use the whole way through:

public enum OrderStatus {
    PENDING,
    PAID,
    SHIPPED,
    DELIVERED
}

Five ways to store it. They are not equivalent, and the gap between them only shows up under change.

@Enumerated(ORDINAL): store the position

This is the default. Leave the annotation bare and JPA stores the enum's ordinal, its index in the declaration order.

@Enumerated(EnumType.ORDINAL)
private OrderStatus status;

PENDING is 0, PAID is 1, SHIPPED is 2, DELIVERED is 3. The column is a tidy little smallint. Everything works.

Until someone needs a new status and adds it where it reads well:

public enum OrderStatus {
    PENDING,
    PAID,
    CANCELLED,   // inserted here
    SHIPPED,
    DELIVERED
}

CANCELLED is now 2. SHIPPED is 3. DELIVERED is 4. Every row written before this change still holds the old integer, so every order that was SHIPPED (2) now reads back as CANCELLED. The database is correct. Your data is wrong. And nothing told you.

If you are stuck with ORDINAL on a legacy schema, pin it with a test that fails the build the moment someone reorders:

@Test
void ordinalsAreFrozen() {
    assertEquals(0, OrderStatus.PENDING.ordinal());
    assertEquals(1, OrderStatus.PAID.ordinal());
    assertEquals(2, OrderStatus.SHIPPED.ordinal());
    assertEquals(3, OrderStatus.DELIVERED.ordinal());
}

New constants may only be appended. The test turns an invisible runtime corruption into a loud compile-time-ish failure. It is a guardrail, not a fix.

@Enumerated(STRING): store the name

Store the constant name instead of its position.

@Enumerated(EnumType.STRING)
private OrderStatus status;

Now the column holds 'PAID'. Reordering the enum is free, because the name does not move when the position does. The column is readable in a raw SELECT, exports document themselves, and a human debugging production can actually tell what a row means.

The cost moves to renames. Rename the constant:

PAID -> SETTLED

and every row still says 'PAID', which no longer matches any constant. Reads blow up or silently drop, depending on your mapping. A rename now requires a data migration:

UPDATE orders SET status = 'SETTLED' WHERE status = 'PAID';

For most schemas this is the right default. Renames are rarer than reorders, and when they happen they are at least visible.

A real Postgres enum type

The two options above are enforced entirely in the JPA layer. The database sees a varchar and will happily accept 'BANANA'. If you want the database itself to guarantee validity, give it a real type:

CREATE TYPE order_status AS ENUM ('PENDING', 'PAID', 'SHIPPED', 'DELIVERED');

CREATE TABLE orders (
    id          bigserial PRIMARY KEY,
    status      order_status NOT NULL
);

Now an invalid status is rejected at insert time, by the database, no matter which application or migration script tries to write it. Pair it with @Enumerated(STRING) on the Java side so the names line up.

One JDBC detail bites everyone the first time: the Postgres driver sends strings as varchar, and Postgres will not implicitly cast varchar to the enum type. Add stringtype=unspecified to the connection URL and the cast resolves:

jdbc:postgresql://localhost:5432/app?stringtype=unspecified

The limit: Postgres only lets you append values to an enum type. ALTER TYPE ... ADD VALUE works, but reordering or dropping a value means recreating the type and rewriting every column that uses it. You traded application-side flexibility for database-side guarantees.

AttributeConverter: decouple the name from the stored value

Both STRING and native enums tie the stored value to the Java identifier. Rename the constant, migrate the data. If you want renames to be free, stop storing the name at all. Store a stable code instead.

public enum OrderStatus {
    PENDING("PND"),
    PAID("PAID"),
    SHIPPED("SHP"),
    DELIVERED("DLV");

    private final String code;

    OrderStatus(String code) { this.code = code; }

    public String getCode() { return code; }

    public static OrderStatus fromCode(String code) {
        for (OrderStatus s : values()) {
            if (s.code.equals(code)) return s;
        }
        throw new IllegalArgumentException("Unknown code: " + code);
    }
}

@Converter(autoApply = true)
public class OrderStatusConverter
        implements AttributeConverter<OrderStatus, String> {

    @Override
    public String convertToDatabaseColumn(OrderStatus status) {
        return status == null ? null : status.getCode();
    }

    @Override
    public OrderStatus convertToEntityAttribute(String code) {
        return code == null ? null : OrderStatus.fromCode(code);
    }
}

The column stores 'PND'. The Java identifier is now free to change:

PENDING -> AWAITING_PAYMENT

The code stays "PND", the database does not move, the rename is a pure refactor your IDE does in one shortcut. The price is one extra class per enum and a layer of indirection: the code in the column no longer reads like the constant, so a raw SELECT shows 'PND' instead of 'PENDING'. You bought rename-freedom with a little readability.

The lookup table

The last option stops treating status as an enum at all. It becomes a foreign key to a reference table.

CREATE TABLE order_status (
    id          int PRIMARY KEY,
    code        varchar(32) UNIQUE NOT NULL,
    label       varchar(64) NOT NULL,
    sort_order  int NOT NULL,
    is_active   boolean NOT NULL DEFAULT true
);

CREATE TABLE orders (
    id          bigserial PRIMARY KEY,
    status_id   int NOT NULL REFERENCES order_status(id)
);

This is the one people reach for too early. It looks like the "grown-up" option, so it gets used as a general way to dodge renames and schema changes. That is the wrong reason. You pay a join on every read, you lose compile-time exhaustiveness (the compiler can no longer warn you about an unhandled switch branch), and you take on the overhead of keeping a relationship in sync.

A lookup table earns all of that only when the value carries editable business data. A display label the product team changes without a deploy. A sort order. A colour for the UI. A feature flag or an SLA attached to the status. Data that lives and changes at runtime.

The honest trade-off

There is no free option here, and the lookup table is where the cost is steepest. Every status read becomes a join. Every switch over status loses the safety net that makes enums worth using in Java. And you now own a tiny CRUD surface for reference data that, in most systems, never actually changes.

Weigh that against what STRING plus a Postgres enum type costs: a one-time migration on the rare day you rename a constant. For the overwhelming majority of status columns, that is the cheaper bill.

My take

Default to @Enumerated(STRING) backed by a native Postgres enum type. You get readable columns, reorder-safety, and the database rejecting garbage at the door.

Upgrade to an AttributeConverter the moment renames need to be free, for example a domain vocabulary that is still settling and gets renamed often.

Reach for a lookup table only when the value is genuinely a record: it has a label, a flag, an SLA, something a human edits at runtime.

That is the whole decision, compressed: if the value is identity only, keep it an enum. If the value is a record, it was never really an enum.

Get that right once and your statuses stay boring, which is the highest compliment you can pay a column.

What do you store status enums as in production, and has a reorder or a rename ever burned you?

🌐 HTTP Got a New Verb, and Your POST /search Was Always a Lie

Kyryl — Sun, 28 Jun 2026 19:36:14 +0000

Every POST /search endpoint you have ever written is a read pretending to be a write.

You did not do it because you wanted to. You did it because the alternatives were worse. Your search has a dozen filters, some of them nested, a few of them arrays, and there is no sane way to stuff all of that into a URL. So you reached for POST, put the filter in the body, and moved on. It works.

But you also lied to every proxy, cache, and retry layer between the client and your server. You told them this request might change state. It does not. It is a safe, idempotent read, and you dressed it up as a mutation because the protocol gave you no better option.

As of late 2025, the protocol gives you a better option. It is called QUERY.

A new HTTP method, which almost never happens

HTTP methods do not change often. Most developers carry a mental list that has not moved in their entire career: GET, POST, PUT, PATCH, DELETE, plus HEAD and OPTIONS if you are being thorough. PATCH was the last meaningful addition, standardized as RFC 5789 in 2010.

QUERY is the next one. The IESG approved "The HTTP QUERY Method" as a Proposed Standard on 2025-11-20, published as RFC 10008. It started life as the IETF draft with the very on-the-nose name draft-ietf-httpbis-safe-method-w-body: a safe method, with a body. That name is the whole idea.

If you are wondering why you are reading about a late-2025 RFC in the middle of 2026: standards land long before tooling does. The draft churned from 2021 to 2025, the RFC is only months old, and servers, proxies, and client libraries are just now starting to react. The spec is the starting gun, not the finish line, which is exactly why the conversation is happening now rather than the day it was published.

One more point of confusion worth clearing up: this is a single new method, QUERY, and it is not the same as SEARCH. WebDAV defined a SEARCH verb back in 2008 (RFC 5323), built around a generic XML body and a pile of WebDAV semantics most people never wanted. The early drafts of this very spec were actually titled "HTTP SEARCH Method," then the working group renamed it to QUERY to escape that WebDAV baggage and to better signal its relationship to the URI's query component. So QUERY is the modern, format-agnostic successor to SEARCH, not a second new verb alongside it.

QUERY is exactly what it sounds like once you frame it right: GET's guarantees with POST's request body. It is safe and idempotent, but it is allowed to carry content, and the content plus its Content-Type defines the query.

The search-endpoint dilemma

To see why this matters, look at the three options you have today for a non-trivial search endpoint. All three are compromises.

Option 1: GET with a giant query string

GET /contacts?select=surname,givenname,email&filter[country]=UA&filter[tags][]=vip&filter[tags][]=lead&sort=-createdAt&limit=10 HTTP/1.1

This is semantically perfect. GET is safe, idempotent, and cacheable, which is exactly what a search is. It works beautifully right up until the query gets complicated.

Then the problems start. URLs have practical length limits, usually somewhere between 2KB and 8KB depending on the browser, proxy, and server in the chain, and a rich filter blows past them faster than you would expect. There is no standard way to represent nested objects or arrays in a query string, so every framework invents its own filter[tags][] dialect. Everything is percent-encoded into noise. And those URLs land in access logs and browser history, filters and all.

Option 2: GET with a request body

You might think: fine, keep the GET semantics, just move the filter into the body. The spec has historically said a GET body has "no defined semantics," and in practice that is a minefield. Some proxies and servers reject the request. Some silently drop the body before your handler ever sees it. Some pass it through. You cannot rely on any of it. This is the one option that is simply not safe to ship.

Option 3: POST /search

So you do what everyone does.

POST /contacts/search HTTP/1.1
Content-Type: application/json

{ "country": "UA", "tags": ["vip", "lead"], "limit": 10 }

This works everywhere. The body holds the full filter with real JSON structure. No URL limits, no encoding mess.

The cost is semantic. POST is defined as neither safe nor idempotent. That has real consequences beyond pedantry:

Retries are off the table. A proxy, gateway, or HTTP client that will happily retry a failed GET will refuse to retry a POST, because retrying a POST might create a second resource. Your read, which is perfectly safe to repeat, is treated as dangerous.
Caching basically does not happen. POST responses are cacheable only under narrow, rarely-implemented conditions. In practice your search results are uncacheable at every layer.
Intermediaries lose the plot. Every proxy, WAF, and observability tool in the path sees a POST and assumes a write. None of them can reason about your read as a read.

You have a safe idempotent operation that the entire HTTP stack treats as a mutation. That is the lie.

How QUERY fixes it

QUERY gives you the POST body without the POST semantics. Here is the canonical shape, straight out of the RFC:

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "surname": "Smith", "givenname": "John", "email": "smith@example.org" }
]

The body can be anything with a media type. Form-encoded, JSON, a GraphQL document, your own filter DSL. The Content-Type tells the server how to parse it, and a 200 OK returns the results in the response body. Because the method is declared safe and idempotent, every caching and retry mechanism that works for GET is allowed to work here too.

The RFC is also strict about error signaling, which makes QUERY endpoints pleasant to integrate against:

Missing Content-Type: 400 Bad Request
Unsupported media type: 415 Unsupported Media Type
Body inconsistent with its declared Content-Type: 400 Bad Request
Syntactically valid query that fails semantically: 422 Unprocessable Content
Cannot produce the format the client asked for in Accept: 406 Not Acceptable

The part people miss: Content-Location

QUERY is more than "POST that promises to behave." The detail that makes it interesting is the Content-Location response header.

A QUERY response can include Content-Location pointing at a URI that represents the results of that operation. The client can then issue a plain GET against that URI to retrieve the same results again. So a single QUERY can hand you back a cacheable, bookmarkable, shareable GET URL for a result set that was too complex to express as a GET in the first place. The expensive structured filter goes over QUERY once; the cheap stable link works as an ordinary GET afterward.

And QUERY responses are genuinely cacheable, with one rule that explains the whole design: the cache key must incorporate the request body, not just the method and URL. Two QUERY requests to the same path with different bodies are different queries with different results. This is also precisely why QUERY had to be a new method rather than a blessing of "GET with a body." The entire HTTP caching model keys on method plus URL. Teaching caches to also key on the body is a real semantic change, and it needed a verb of its own to hang that behavior on safely.

The honest trade-off

Here is the part where I stop selling it.

You should not migrate anything to QUERY tomorrow. The standard is months old, and adoption is the bottleneck. Origin servers, reverse proxies, CDNs, API gateways, browser fetch stacks, and HTTP client libraries largely do not understand QUERY yet. A browser fetch() will let you send an arbitrary method string, but you have no guarantee the proxies and load balancers between you and the origin will pass it through instead of choking on a verb they do not recognize.

This is not hypothetical pessimism, it is just how HTTP adoption works. PATCH was standardized in 2010 and still took years before you could assume a random framework and gateway handled it without special-casing. QUERY is at the very start of that same curve.

So the pragmatic position for production in 2026 is unchanged: POST /search is still the right default. It works on every piece of infrastructure you will ever deploy behind.

What changes is how you think about that endpoint. You now know it is a workaround, not the correct expression of what you are doing. QUERY is the thing to learn now, prototype on internal services where you control the whole path, and reach for the moment your stack and your proxies actually support it. The win it offers is not a feature you are currently missing. It is semantic honesty: a way to finally tell the HTTP stack the truth about an operation that was always a safe, idempotent read.

The takeaway

QUERY is GET's guarantees plus POST's body, and it exists because every backend developer independently arrived at the same hack and the standard finally caught up to it. Your search endpoints were never really writes. Now there is a verb that agrees with you, even if the rest of the internet needs a few years to catch up.

What do you reach for on a heavy search endpoint today: POST /search, a sprawling query string, GraphQL, something else? And once your gateways and clients support it, would you actually switch to QUERY, or is POST /search too entrenched to bother? Real-world setups beat theory here.

🧹 Your Spring Service Does Not Need That Interface

Kyryl — Thu, 25 Jun 2026 21:09:05 +0000

UserService. UserServiceImpl. One interface, one implementation, and there will only ever be one. Open any Spring codebase and you will find dozens of these pairs. Nobody on the team remembers deciding to do it this way. It is just how services are written.

Here is the part most people never learned: the reason this pattern exists stopped being true around Spring Boot 2.0.

Why the interface used to be mandatory

Go back to early Spring and EJB. When you put @Transactional on a bean, Spring did not run your method directly. It wrapped your bean in a proxy, and the proxy opened the transaction, called your method, then committed or rolled back.

The default proxy mechanism was the JDK dynamic proxy. And JDK dynamic proxies have one hard rule: they can only proxy interfaces. The proxy is a synthetic class that implements your interface and delegates to the real object. No interface, no proxy.

So if you wanted @Transactional, @Async, @Cacheable, or any other AOP-driven annotation on a service, you needed that service to implement an interface. It was not a design decision about abstraction or testability. It was a mechanical requirement of the framework. The Impl class was the price of admission.

That is where the muscle memory came from. A whole generation of Spring developers learned "services have interfaces" as a rule, without the context that it was a workaround for a proxy limitation.

The constraint is gone

Spring Boot flipped the default to CGLIB proxies. Since Boot 2.0, proxyTargetClass is true out of the box. CGLIB does not implement an interface, it generates a runtime subclass of your concrete class and overrides each method to add the advice.

That means @Transactional works perfectly on a plain class:

@Service
public class UserService {

    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Transactional(readOnly = true)
    public User findById(Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));
    }

    @Transactional
    public User create(CreateUserRequest request) {
        return userRepository.save(User.from(request));
    }
}

No interface. CGLIB subclasses UserService at startup, the transactional advice still runs, and everything behaves exactly as it did with the interface in place. The framework reason for the interface evaporated, but the habit did not.

Compare that to what the "proper" version used to look like:

public interface UserService {
    User findById(Long id);
    User create(CreateUserRequest request);
}

@Service
public class UserServiceImpl implements UserService {

    private final UserRepository userRepository;

    public UserServiceImpl(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    @Transactional(readOnly = true)
    public User findById(Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));
    }

    @Override
    @Transactional
    public User create(CreateUserRequest request) {
        return userRepository.save(User.from(request));
    }
}

Twice the files. The method signatures written out twice. An @Override on everything. And not a single new behavior to show for it.

"But I need the interface to mock it"

This is the second defense, and it is just as dead as the first.

Mockito has mocked concrete classes for years. It generates a subclass at runtime, the same trick CGLIB uses. You do not need an interface to write a test double:

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {

    @Mock
    UserService userService; // concrete class, mocked fine

    @InjectMocks
    OrderService orderService;

    @Test
    void rejects_order_for_missing_user() {
        when(userService.findById(42L))
            .thenThrow(new UserNotFoundException(42L));

        assertThrows(OrderRejectedException.class,
            () -> orderService.place(42L, cart));
    }
}

The same goes for @MockBean in a slice test. Spring replaces the bean with a mock whether the type is an interface or a class. "Interface for testability" describes a world that ended a long time ago.

The `Impl` suffix is the tell

When the only way to name your implementation is to staple Impl onto the interface name, that is the code telling you the interface is not doing anything. A good abstraction has a name that means something on its own. PaymentProvider and StripePaymentProvider. Cache and RedisCache. The interface describes a role, the implementation describes one concrete way to fill it.

UserService and UserServiceImpl describe the same thing twice. It is one concept wearing two files. And you pay for the split constantly: every "go to definition" lands on the interface, and you click through to the impl to see what the code actually does. Multiply that by every service, every navigation, every new hire trying to read the codebase.

The honest trade-off

This is not "interfaces are bad." That would be a dumb position. Interfaces are one of the most useful tools in the language, and there are clear places where a service interface earns every line:

Genuinely multiple implementations. A PaymentProvider with Stripe and PayPal behind it. A NotificationChannel for email, SMS, and push. The interface is the abstraction over real variants, and a strategy pattern needs it.
A module or published-API boundary. When other modules or services consume your type, the interface is the contract. You expose the interface and hide the implementation so you can change internals without breaking callers.
Ports and adapters / hexagonal. The port is an interface on purpose. It keeps your domain code from depending on infrastructure. The UserRepository interface in your domain, implemented by a JPA adapter in your infrastructure layer, is exactly right.

The distinction is the number of implementations and the existence of a real seam, not the layer the class happens to live in. A service interface at an architectural boundary is doing work. A service interface wrapped around a single CRUD bean in the same package is ceremony.

There is also an asymmetry that settles the default. Extracting an interface later, when a second implementation actually arrives, is a 10-second IDE refactor: right-click, "Extract Interface," done. Carrying a dead interface on every service from day one is a cost you pay forever, on every file and every navigation. Cheap to add when you need it, expensive to maintain when you do not. That asymmetry says: default to the concrete class.

The rule

Start with the concrete class. Put @Transactional right on it. Let CGLIB do its job. The moment you have a second implementation or a real cross-module boundary, extract the interface then, and give it a name that means something. Do not predict the second implementation. In most services it never comes.

What looked like clean architecture was mostly inertia from a constraint that expired eight years ago.

Do you still write an interface for every service, or did you drop the habit? If you kept it, what is the rule that makes it worth the second file for you? Real-world approaches beat theory here.

Your @EventListener Fires Before the Transaction Commits⚙️

Kyryl — Wed, 24 Jun 2026 21:20:49 +0000

Your domain event fires. Your notification service queries the DB for the entity that just got saved. It finds nothing.

You add a log line. It starts working. You remove the log. It breaks again.

That's not a race condition. That's @EventListener.

What's actually happening

Spring's @EventListener fires synchronously, inside the calling thread, before the transaction commits. The DB row exists in Hibernate's session — but it hasn't been flushed and committed yet. Other connections, including the one your listener opens when it calls findById, can't see it.

The log statement "fixes" it because the delay gives Hibernate time to flush. Remove the log, the flush doesn't happen in time, and you're back to an empty Optional.

Here's the broken setup:

@Component
public class OrderEventListener {

    @EventListener // fires MID-TRANSACTION, before commit
    public void onOrderCreated(OrderCreatedEvent event) {
        // Transaction not committed yet.
        // Other DB connections see nothing.
        Order order = orderRepository
                .findById(event.getOrderId())
                .orElseThrow(); // ← throws here, row doesn't exist yet

        notificationService.notifyCustomer(order);
    }
}

The obvious fix and what it costs you

Spring ships @TransactionalEventListener for exactly this. Set phase = TransactionPhase.AFTER_COMMIT and the listener fires after the transaction commits. The row is visible. findById returns the order. Problem solved.

@Component
public class OrderEventListener {

    @TransactionalEventListener(
        phase = TransactionPhase.AFTER_COMMIT
    )
    public void onOrderCreated(OrderCreatedEvent event) {
        // Transaction committed. All connections see the row.
        Order order = orderRepository
                .findById(event.getOrderId())
                .orElseThrow(); // ← works fine

        notificationService.notifyCustomer(order);
    }
}

But the trade-off is real. Your listener is now decoupled from the transaction. If the listener fails — notification service is down, the email throws, the external API times out — the transaction already committed. The event is gone. Nothing retries it. Nothing tells you it was dropped.

@EventListener: stale reads.
@TransactionalEventListener(AFTER_COMMIT): silent data loss on listener failure.

Neither is great.

The edge case that bites in tests

There's a second problem with @TransactionalEventListener that most teams hit in tests or Kafka consumers: if there's no active transaction, the listener silently does nothing.

Call the service from a unit test without @Transactional. Publish a Kafka message that triggers the same service method without a transaction boundary. The listener won't fire. No warning. No exception. The event just disappears.

Fix: fallbackExecution = true.

@TransactionalEventListener(
    phase = TransactionPhase.AFTER_COMMIT,
    fallbackExecution = true  // fires even with no active transaction
)
public void onOrderCreated(OrderCreatedEvent event) {
    // Now works from Kafka consumers, tests, scheduled tasks
    // that don't have an active @Transactional context.
    // Without this: event silently dropped. Nothing tells you.
}

This restores synchronous execution when there's no transaction — which gives you back the mid-transaction timing problem you started with. You're going in circles.

When AFTER_COMMIT is fine and when it isn't

The real question is: what happens if the listener never fires?

If the answer is "stale cache for 60 seconds" or "audit log has a gap" — AFTER_COMMIT is fine. The business isn't broken.

If the answer is "customer didn't get charged", "duplicate order created", or "inventory not decremented" — you need the outbox pattern. Write the event as a row in an outbox table inside the same transaction. A separate process (a scheduler or Debezium reading the WAL) picks it up and publishes it after commit. Now the event delivery is reliable and tied to the transaction at the DB level, not the application level.

The outbox is more infrastructure. But it's the correct choice when losing an event corrupts state.

The trade-off, summarised

Approach	Stale reads	Silent loss on failure	Works outside `@Transactional`
`@EventListener`	Yes	No	Yes
`@TransactionalEventListener(AFTER_COMMIT)`	No	Yes	No (silent drop)
`@TransactionalEventListener(AFTER_COMMIT, fallbackExecution = true)`	Mixed	Yes	Yes
Outbox pattern	No	No	Yes

@EventListener vs @TransactionalEventListener — almost identical names, completely different behavior. Most teams find this difference via a production incident, not the docs.

How do you handle post-commit side effects in your services?

🧩 Your MapStruct Mappers Are Hiding Null Bugs

Kyryl — Wed, 17 Jun 2026 21:54:58 +0000

Someone adds a field to a DTO. The entity already has it. MapStruct compiles fine, the tests pass, the PR merges. Two weeks later the field is null in production and nobody knows why.

The compiler knew. It just wasn't told to care.

MapStruct is the default mapping library on most Java teams I've worked on, and almost nobody touches the config past @Mapper. That default config is exactly what lets the bug above happen. Here are the three things I add to every mapper to make it safe, testable, and predictable.

1. Make the compiler fail on missing mappings

By default, when a target field has no matching source, MapStruct's unmappedTargetPolicy is WARN. A warning in an annotation processor is noise. It scrolls past in the build log and nobody reads it. So the field stays null and you find out from a bug report.

Flip it to ERROR:

@Mapper(
    componentModel = MappingConstants.ComponentModel.SPRING,
    unmappedTargetPolicy = ReportingPolicy.ERROR
)
public interface UserMapper {
    UserDto map(User source);
}

Now the build fails the moment a target field has no source. Add phoneNumber to UserDto without a matching source field, and the compile breaks with the exact field name. You fix it before the code ever runs.

This is the whole point. Without ERROR, completeness is a thing humans have to remember. With it, the compiler enforces it for free. The cost of catching a mistake drops from "production incident plus a debugging session" to "a red build you fix in thirty seconds".

2. One component model, two ways to get the mapper

Declare the component model with the constant, not a string literal:

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface UserMapper {
    UserDto map(User source);
}

That makes the generated mapper a Spring bean, so you inject it like anything else:

@Service
public class UserService {
    private final UserMapper userMapper;

    public UserService(UserMapper userMapper) {
        this.userMapper = userMapper;
    }
}

Good for production. Annoying for unit tests. You don't want to boot a Spring context just to test that one mapper turns a User into a UserDto. So don't. MapStruct generates a plain implementation you can grab directly:

class UserMapperTest {
    private final UserMapper mapper = Mappers.getMapper(UserMapper.class);

    @Test
    void mapsAllFields() {
        User source = new User(1L, "Kyryl", "kyryl@example.com");

        UserDto dto = mapper.map(source);

        assertThat(dto.id()).isEqualTo(1L);
        assertThat(dto.name()).isEqualTo("Kyryl");
    }
}

Mappers.getMapper() returns a real instance with zero context startup. The test runs in milliseconds. Same mapper, two access paths: Spring injection in the app, the factory in tests.

3. Let MapStruct resolve types for you

This is where most hand-written mapping code is wasted. People write loops and null checks and delegation calls that MapStruct will generate if you let it. Three patterns cover almost everything.

Collections

Declare the single-element mapping and the list overload. You don't implement the loop, MapStruct derives it from the element mapping it already has.

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface UserMapper {
    UserDto map(User source);
    List<UserDto> map(List<User> source);
}

The generated map(List<User>) iterates and calls map(User) per element. No for loop in your code, no .stream().map(...).toList() boilerplate.

Enums

Map an enum once with @ValueMappings. The catch nobody handles until it bites them: a new constant added to the source enum later. ANY_REMAINING is the default branch that keeps that from throwing at runtime.

@ValueMappings({
    @ValueMapping(target = "ENABLED",  source = "ACTIVE"),
    @ValueMapping(target = "UNKNOWN",  source = MappingConstants.ANY_REMAINING)
})
StatusDto map(Status source);

Someone adds Status.SUSPENDED next quarter and forgets your mapper exists. Without ANY_REMAINING, MapStruct throws an IllegalArgumentException the first time that value flows through. With it, the value maps to UNKNOWN and you handle it gracefully instead of paging someone.

Composition

Compose mappers with uses. MapStruct picks the right sub-mapper by type, so you never write delegation by hand.

@Mapper(uses = {StatusMapper.class, AddressMapper.class})
public interface OrderMapper {
    OrderDto map(Order source);
}

When Order has a Status field and an Address field, MapStruct sees the types, finds the matching mapper in uses, and calls it. Add a third nested type later, register its mapper in uses, done. No manual wiring.

The honest trade-off

unmappedTargetPolicy = ERROR is not free. Every field you intentionally leave unmapped now needs an explicit @Mapping(target = "auditTimestamp", ignore = true). On a DTO with thirty fields where you only care about ten, that's a wall of ignore = true lines, and you have to maintain them.

That's real overhead and I won't pretend it isn't. My rule of thumb: turn it on the moment a mapper has more than a handful of fields, or sits on a service where DTOs and entities change often. That's exactly where the silent-null bug lives. For a tiny three-field mapper that never changes, the ceremony isn't worth it.

The other cost is that ANY_REMAINING can hide a mapping you genuinely meant to add. It trades a loud runtime crash for a quiet fallback. That's the right call for resilience, but pair it with a test that asserts the constants you care about actually map where you expect.

What you actually gain

Add these up and the mapper stops being a place bugs hide. The compiler enforces completeness. The tests run without a container. The boilerplate that used to be hand-written loops and switch statements is generated from a couple of method signatures.

Define the shape once, let the generator handle the mechanical parts. That's the whole pitch.

What does your @Mapper config look like? Do you enforce ERROR, or has the WARN default ever shipped a null to production on you? Curious whether teams turn this on by default or only after it bites.

Confluence Docs Lie. Tie Your Documentation to Code Instead📘

Kyryl — Sat, 13 Jun 2026 20:23:11 +0000

Every team has that Confluence page. The one that was carefully written to explain what the service does, what the API looks like, what each DB column means. Someone spent real time on it. It was accurate when it was written.

Six months later, it's fiction.

This isn't a discipline problem. I've seen it at teams with strong engineering culture, with good processes, with people who genuinely care about documentation. The Confluence page still goes stale. The root cause is structural, and until you treat it that way, nothing changes.

Why external docs always drift

When documentation lives in a different place than the code, there's no mechanism that forces them to stay in sync. It relies entirely on people remembering to update two separate things every time anything changes. A column gets renamed, an endpoint response adds a field, a Kafka message format evolves — the ticket gets closed, the code gets merged, and the Confluence page stays where it was.

AI writing more of your code makes this worse. More code ships faster now. The documentation debt compounds faster too.

The fix isn't better processes or more reminders in the PR template. It's to stop maintaining documentation as a separate artifact and tie it directly to the code.

Three tools that keep docs honest

Swagger on your REST controllers

If you're using Spring Boot with springdoc-openapi, you already have the infrastructure. You just need to use it properly.

@RestController
@RequestMapping("/api/orders")
@Tag(name = "Orders", description = "Order lifecycle management")
public class OrderController {

    @Operation(
        summary = "Get order by ID",
        description = "Returns a single order. 404 if the order doesn't exist or belongs to a different customer."
    )
    @ApiResponse(responseCode = "200", description = "Order found")
    @ApiResponse(responseCode = "404", description = "Order not found")
    @GetMapping("/{id}")
    public ResponseEntity<OrderDto> getOrder(
        @Parameter(description = "Internal order ID") @PathVariable Long id
    ) {
        return orderService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
}

The Swagger UI becomes a living contract. It's always current because it's generated from the code. Frontend devs, QA, external teams can check it themselves without asking you anything.

If your controllers are getting buried in annotations, the previous post on moving Swagger to interfaces covers that pattern.

PostgreSQL column comments in DDL

PostgreSQL supports COMMENT ON natively. It's been there forever, almost nobody uses it.

CREATE TABLE orders (
    id          BIGSERIAL    PRIMARY KEY,
    customer_id BIGINT       NOT NULL,
    status      VARCHAR(20)  NOT NULL,
    total_cents BIGINT       NOT NULL,
    created_at  TIMESTAMPTZ  NOT NULL DEFAULT now()
);

COMMENT ON TABLE orders IS 'Customer purchase orders. One row per order, regardless of item count.';

COMMENT ON COLUMN orders.status IS
    'Order lifecycle state. Valid values: PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED. '
    'Transitions are enforced in OrderService, not at the DB level.';

COMMENT ON COLUMN orders.total_cents IS
    'Order total in cents. Always positive. Divide by 100 for display. '
    'Never store as decimal — rounding bugs.';

These comments ship with the schema. They live in your migration files. When the column changes, the comment gets updated in the same commit, by the same person, in the same PR review.

You can query them directly:

SELECT
    c.column_name,
    pgd.description
FROM pg_catalog.pg_statio_all_tables AS st
JOIN pg_catalog.pg_description pgd ON pgd.objoid = st.relid
JOIN information_schema.columns c
    ON c.table_name = st.relname
    AND ordinal_position = pgd.objsubid
WHERE c.table_schema = 'public'
  AND c.table_name = 'orders';

And any decent DB client (DBeaver, DataGrip) surfaces them automatically when you hover over a column. No page to open. The schema explains itself.

doc attribute in Avro schemas

If you're using Avro for Kafka messages, the doc field is part of the spec. It's not optional in any meaningful sense if you care about your consumers understanding the contract.

{
  "type": "record",
  "name": "OrderCreatedEvent",
  "namespace": "com.example.events",
  "doc": "Published when a new order is placed. Consumed by inventory-service, billing-service, and notification-service.",
  "fields": [
    {
      "name": "orderId",
      "type": "long",
      "doc": "Internal order ID from the orders table."
    },
    {
      "name": "customerId",
      "type": "long",
      "doc": "References users.id. The customer who placed the order."
    },
    {
      "name": "totalCents",
      "type": "long",
      "doc": "Order total in cents. Always positive. Same semantics as orders.total_cents."
    },
    {
      "name": "status",
      "type": "string",
      "doc": "Initial status at publish time. Always PENDING for this event."
    }
  ]
}

When another team's developer needs to understand what this event carries, they read the schema. If the schema is registered in a Schema Registry (Confluent or otherwise), the docs are browsable there. No Confluence page, no hunting down who owns the topic.

Who else benefits

The obvious beneficiaries are engineers. Less time spent answering "what does this field mean" questions, better context when onboarding, less cognitive overhead when reading unfamiliar code.

But the compounding effect shows up with less technical people.

Give your BA a dump of the database DDL — just the schema files, no actual data. Or give them read-only access to a dev environment DB. With an AI assistant they can load those schemas and start asking questions: what do we store, what are the valid states for this field, how are orders and customers related. They get answers without pinging a developer. The schema is always current because it's in version control.

Same with Swagger. A product manager who can open Swagger UI and see the actual endpoints, parameters, and response shapes during a design discussion is a product manager who isn't blocked waiting for you to write up an email.

Your AI coding assistant also benefits. An LLM reading your schema with doc fields and COMMENT ON COLUMN entries has significantly more context than one reading bare column names. The quality of generated code improves with it.

The honest trade-off

Writing proper Swagger annotations, DDL comments, and Avro doc fields takes time upfront. Real time. When you're under pressure to ship the feature by Friday, adding good COMMENT ON COLUMN entries to the migration doesn't feel like a priority.

It's also harder to enforce than a Confluence page. With Confluence, you can at least point to a URL and say "write it here." With code-tied docs, you need to make it part of the review culture — PRs that add columns without comments don't get merged.

That's a real overhead, and I won't pretend otherwise.

But the alternative is paying that cost continuously. Every time someone joins the team and has to ask what a column means. Every time a BA opens a Jira ticket that could have been answered by looking at the schema. Every time your Confluence page sends someone down the wrong path because nobody updated it after the last refactor.

The upfront investment is a one-time cost per artifact. Stale docs are a recurring cost forever.

Write them once. Keep them with the code. They won't lie.

Do you have a practice for keeping docs in sync with code, or is it still Confluence pages and hope? Curious what's actually working at different team sizes.

DEV Community: Kyryl

"🚩 readOnly = true Is Not a Comment"

What people think readOnly = true does

What it actually does: changes Hibernate's flush mode

The trap: a write inside a read-only transaction

The other half: it can route your read to a replica

The honest trade-off

"🔇 Calling Your Own @Async Method Does Nothing"

Why this.method() Skips the Proxy

Fix 1: Split the Callee Into a Second Bean

Fix 2: Inject the Bean Into Itself

The Honest Trade-off

"🥊 Your Retry Aspect Is Retrying a Dead Transaction"

Why nesting order matters here

Wrong order: transaction outer, retry inner

Right order: retry outer, transaction inner

The honest trade-off

"🔁 Your Prototype Bean Is a Singleton in Disguise"

Fix 1: ApplicationContext.getBean() — it works, but it is ugly

Fix 2: an abstract @Lookup method — cleaner, still Spring-flavored

Fix 3: inject ObjectProvider — the one to actually reach for

The honest trade-off

🧱 Your Test Fixtures Are Lying About What Matters

Why this happens

The pattern

The honest trade-off

What you actually gain

"🧪 Good Enough Tests Died When AI Started Writing Them"

This is about the middle of the pyramid

The rule: split by ownership

Infra you own: run it for real, at the prod version

The third-party API you do not own: WireMock the wire

The safety net: a wire mock can lie

The honest trade-off

🗄️ The JPA Enum Default Quietly Corrupts Your Data

@Enumerated(ORDINAL): store the position

@Enumerated(STRING): store the name

A real Postgres enum type

AttributeConverter: decouple the name from the stored value

The lookup table

The honest trade-off

My take

🌐 HTTP Got a New Verb, and Your POST /search Was Always a Lie

A new HTTP method, which almost never happens

The search-endpoint dilemma

Option 1: GET with a giant query string

Option 2: GET with a request body

Option 3: POST /search

How QUERY fixes it

The part people miss: Content-Location

The honest trade-off

The takeaway

🧹 Your Spring Service Does Not Need That Interface

Why the interface used to be mandatory

The constraint is gone

"But I need the interface to mock it"

The Impl suffix is the tell

The honest trade-off

The rule

Your @EventListener Fires Before the Transaction Commits⚙️

What's actually happening

The obvious fix and what it costs you

The edge case that bites in tests

When AFTER_COMMIT is fine and when it isn't

The trade-off, summarised

🧩 Your MapStruct Mappers Are Hiding Null Bugs

1. Make the compiler fail on missing mappings

2. One component model, two ways to get the mapper

3. Let MapStruct resolve types for you

Collections

Enums

Composition

The honest trade-off

What you actually gain

Confluence Docs Lie. Tie Your Documentation to Code Instead📘

Why external docs always drift

Three tools that keep docs honest

Swagger on your REST controllers

PostgreSQL column comments in DDL

doc attribute in Avro schemas

The `Impl` suffix is the tell