Then it hits production with real data, and your “load all authors” endpoint fires 301 SQL queries for 300 authors. Latency spikes, the database connection pool drains, and your APM dashboard turns red.

This is the N+1 select problem, and it is the single most common performance disaster in Spring applications. The good news: once you understand why it happens, you have a toolbox of precise fixes. This article walks through relationship mapping, fetch semantics, a live reproduction of N+1, and every practical way to solve it — JOIN FETCH, @EntityGraph, batch fetching, DTO projections, and when to drop down to native SQL.

The domain model

We’ll use three entities throughout. Authors write books; each book has one publisher; authors and tags have a many-to-many relationship.

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

@Entity
@Table(name = "author")
public class Author {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @OneToMany(mappedBy = "author", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Book> books = new ArrayList<>();

    @ManyToMany
    @JoinTable(
        name = "author_tag",
        joinColumns = @JoinColumn(name = "author_id"),
        inverseJoinColumns = @JoinColumn(name = "tag_id"))
    private Set<Tag> tags = new HashSet<>();

    // helper keeps both sides of the relationship in sync
    public void addBook(Book book) {
        books.add(book);
        book.setAuthor(this);
    }

    // getters / setters omitted for brevity
}

@Entity
@Table(name = "book")
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "author_id")
    private Author author;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "publisher_id")
    private Publisher publisher;

    // getters / setters
}

@Entity
@Table(name = "publisher")
public class Publisher {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
}

@Entity
@Table(name = "tag")
public class Tag {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String label;
}

A few mapping rules worth internalizing right now:

• The mappedBy side is the inverse (non-owning) side. The owning side is the one with the foreign key — here, Book owns the author_id column. Setting books on Author without setting book.author will not persist the relationship correctly.
• Always initialize collections (= new ArrayList<>()) to avoid NullPointerException before persist.
• Use a Set for @ManyToMany to avoid duplicate join rows and to sidestep Hibernate's notorious MultipleBagFetchException (more on that later).

Fetch types: LAZY vs EAGER

Every association has a fetch strategy. It determines when the related data is loaded.

| Association | Default fetch | Recommended |
|-------------|---------------|-------------|
| `@OneToMany` | LAZY | LAZY (keep it) |
| `@ManyToMany` | LAZY | LAZY (keep it) |
| `@ManyToOne` | **EAGER** | **LAZY (override it)** |
| `@OneToOne` | **EAGER** | **LAZY (override it)** |

Notice the trap: the *ToOne associations default to EAGER. That means every time you load a Book, Hibernate also loads its Author and Publisher — whether you need them or not. EAGER fetching is the silent partner of the N+1 problem because it removes your ability to choose when joins happen.

Rule of thumb: make every association LAZY, then fetch eagerly per-query when you actually need the data. That’s why both @ManyToOne mappings above explicitly set fetch = FetchType.LAZY.

LAZY works through proxies. When you access book.getAuthor(), Hibernate issues a SELECT at that moment — but only if the persistence context (the Hibernate Session) is still open. Access it after the transaction closes and you get the dreaded:

org.hibernate.LazyInitializationException: could not initialize proxy – no Session

We’ll see how DTO projections and explicit fetching eliminate this.

Reproducing the N+1 problem

Here’s a repository and a service that looks completely innocent.

public interface AuthorRepository extends JpaRepository<Author, Long> {
}

@Service
public class AuthorService {

    private final AuthorRepository authorRepository;

    public AuthorService(AuthorRepository authorRepository) {
        this.authorRepository = authorRepository;
    }

    @Transactional(readOnly = true)
    public List<String> listAuthorsWithBookCount() {
        List<Author> authors = authorRepository.findAll();   // query #1
        return authors.stream()
            .map(a -> a.getName() + " (" + a.getBooks().size() + " books)") // queries 2..N+1
            .toList();
    }
}

Turn on SQL logging so you can see it:

# application.properties
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE

With 300 authors, the log shows:

select a.id, a.name from author a;                       -- 1 query
select b.* from book b where b.author_id = ?;            -- repeated 300 times

1 query to load the authors, then N queries to lazily load each author’s books. That’s N+1. The latency is roughly linear in the number of parent rows, and round-trip overhead dominates. At scale this is catastrophic.

The same thing happens with EAGER @ManyToOne: load 300 books and Hibernate fires a separate SELECT for each distinct author and publisher.

Fix #1: JOIN FETCH in JPQL

The most direct fix is to tell Hibernate to load the association in the same query using a JOIN FETCH.

public interface AuthorRepository extends JpaRepository<Author, Long> {

    @Query("select distinct a from Author a left join fetch a.books")
    List<Author> findAllWithBooks();
}

Now it’s a single SQL statement:

select distinct a.id, a.name, b.id, b.title, b.author_id, b.publisher_id
from author a
left join book b on b.author_id = a.id;

Notes that matter in production:

• Use left join fetch (not inner) if you want authors who have zero books.
• distinct deduplicates the parent rows in the returned List. Since Hibernate 6 the SQL-level DISTINCT is automatically removed when it isn't needed, so this distinct is essentially a JPA-level hint and does not add a costly SELECT DISTINCT to the database query.

The pagination trap. You cannot safely JOIN FETCH a collection and paginate at the same time. If you add Pageable to a query that fetches a @OneToMany, Hibernate logs:

HHH000104: firstResult/maxResults specified with collection fetch; applying in memory

It fetches the entire result set and paginates in Java heap — a memory bomb. For paginated collection fetching, use batch fetching (Fix #3) or two queries: page the IDs first, then fetch the collections for those IDs.

Fix #2: @EntityGraph

JOIN FETCH couples the fetch plan to a hand-written query. @EntityGraph lets you declare which associations to load eagerly while reusing derived query methods.

public interface AuthorRepository extends JpaRepository<Author, Long> {

    @EntityGraph(attributePaths = {"books"})
    @Query("select a from Author a")
    List<Author> findAllWithBooksGraph();

    // works on derived queries too
    @EntityGraph(attributePaths = {"books", "tags"})
    List<Author> findByNameContaining(String fragment);
}

attributePaths accepts nested paths, so you can fetch Book and its Publisher in one shot from the Book repository:

@EntityGraph(attributePaths = {"author", "publisher"})
List<Book> findByTitleContaining(String fragment);

For reuse across many queries, define a named graph on the entity:

@Entity
@NamedEntityGraph(
    name = "Author.withBooks",
    attributeNodes = @NamedAttributeNode("books"))
@Table(name = "author")
public class Author { /* ... */ }

@EntityGraph(value = "Author.withBooks", type = EntityGraph.EntityGraphType.LOAD)
List<Author> findAll();

@EntityGraph generates a LEFT JOIN FETCH under the hood, so it carries the same pagination caveat for collections. Its strength is declarative, query-method-friendly fetch plans.

Fix #3: batch fetching

Sometimes you genuinely want lazy loading but in efficient batches rather than one query per row. Hibernate’s @BatchSize (or the global default) turns N individual SELECTs into ceil(N / batchSize) IN-clause queries.

@OneToMany(mappedBy = "author")
@BatchSize(size = 50)
private List<Book> books = new ArrayList<>();

Or set it globally:

spring.jpa.properties.hibernate.default_batch_fetch_size=50

Now loading 300 authors’ books costs:

select b.* from book b where b.author_id in (?, ?, ?, ... 50 ids ...);  -- 6 queries

300 authors / 50 = 6 queries instead of 300. Batch fetching is the best general-purpose default because it works with pagination (you page the parents normally, then collections load in batches) and requires zero query rewrites. I enable default_batch_fetch_size in nearly every project I touch.

Fix #4: DTO projections

The fastest query is one that selects only the columns you need and never inflates managed entities at all. For read-heavy endpoints, project straight into a DTO.

Constructor expression (JPQL):

public record AuthorSummary(Long id, String name, long bookCount) {}

@Query("""
    select new com.example.dto.AuthorSummary(a.id, a.name, count(b))
    from Author a left join a.books b
    group by a.id, a.name
    """)
List<AuthorSummary> findAuthorSummaries();

This is a single GROUP BY query that returns exactly three columns. No proxies, no LazyInitializationException, no N+1 — and it's safe to paginate because there's no collection fetch.

Interface-based projections are even less code; Spring Data implements them for you:

public interface AuthorView {
    Long getId();
    String getName();
}

List<AuthorView> findByNameContaining(String fragment);

Spring Data inspects the interface getters and generates a query selecting only id and name. For nested data, define a projection-of-projections — but be aware that nested interface projections on associations can themselves re-introduce N+1, so verify with SQL logging.

DTO projections are my default for any endpoint that reads data for display. Reserve managed entities for the cases where you actually mutate state.

Fix #5: native queries (when JPQL isn’t enough)

JPQL covers most needs, but reach for native SQL when you need database-specific features: window functions, CTEs, JSONB operators, full-text search, vendor hints, or a finely tuned execution plan.

@Query(value = """
    select a.id as id, a.name as name, count(b.id) as bookCount
    from author a
    left join book b on b.author_id = a.id
    where a.name ilike :fragment
    group by a.id, a.name
    order by bookCount desc
    limit :limit
    """,
    nativeQuery = true)
List<AuthorSummary> searchTopAuthors(@Param("fragment") String fragment,
                                     @Param("limit") int limit);

For native queries returning DTOs, the column aliases must match the projection property names (or use a @SqlResultSetMapping). Native queries bypass JPQL portability and the persistence context's dirty checking, so use them deliberately — they are an escape hatch, not a default.

Choosing the right tool

| Technique | Best for | Watch out for |
|-----------|----------|---------------|
| `JOIN FETCH` | Loading a specific graph in one query | Cannot paginate collection fetches; `MultipleBagFetchException` |
| `@EntityGraph` | Reusable declarative fetch plans on derived methods | Same pagination caveat as JOIN FETCH |
| `@BatchSize` / `default_batch_fetch_size` | Pagination + lazy collections; general default | Still issues N/batch extra queries |
| DTO projection | Read-only display endpoints | Read-only; no entity mutation |
| Native query | Vendor-specific SQL, complex aggregation | Not portable; bypasses dirty checking |

The MultipleBagFetchException

If you try to JOIN FETCH two List collections at once:

@Query("select a from Author a left join fetch a.books left join fetch a.tags")
List<Author> brokenFetch();

Hibernate throws:

org.hibernate.loader.MultipleBagFetchException: cannot simultaneously fetch multiple bags

A “bag” is an unordered List. Fetching two of them via SQL JOIN produces a cartesian product Hibernate refuses to deduplicate. Two clean fixes:

1. Use Set instead of List for the collections — sets don't trigger the exception.
2. Keep Lists but combine with batch fetching: JOIN FETCH one collection, and let @BatchSize handle the second.

Option 2 is usually best for performance because even a single multi-collection JOIN creates a cartesian explosion (authors × books × tags rows).

Verifying you actually fixed it

Don’t trust your eyes — count queries in tests. Add an assertion library or use Hibernate’s statistics:

spring.jpa.properties.hibernate.generate_statistics=true

@Test
void listingAuthorsUsesASingleQuery() {
    Statistics stats = entityManagerFactory
        .unwrap(SessionFactory.class).getStatistics();
    stats.clear();

    authorService.listAuthorsWithBookCount();

    assertThat(stats.getPrepareStatementCount()).isEqualTo(1);
}

Better still, add the datasource-proxy or p6spy library, or the popular quick-perf / db-util assertions, to fail the build when a method exceeds its query budget. Catching N+1 in CI is far cheaper than catching it in production.

Common pitfalls

• Trusting *ToOne defaults. @ManyToOne and @OneToOne are EAGER by default. Always override to FetchType.LAZY and fetch per-query.
• open-session-in-view masking the problem. Spring Boot enables spring.jpa.open-in-view=true by default. It keeps the session open during view rendering, so lazy loads work — by silently firing N+1 queries during serialization. Set spring.jpa.open-in-view=false and fetch explicitly. The errors you then get are your real fetch bugs surfacing.
• Paginating a collection JOIN FETCH. Triggers in-memory pagination of the entire result set. Use batch fetching or two-step ID-then-fetch instead.
• @OneToMany without mappedBy. Omitting mappedBy makes Hibernate create a redundant join table for a one-to-many. Always map the inverse side with mappedBy.
• Forgetting to sync both sides. Setting only the parent collection (not the child’s @ManyToOne) leaves the FK null. Use helper methods like addBook.
• equals/hashCode on mutable fields or the generated id. Breaks Set membership and can cause duplicate or lost entities. Prefer a business key or a UUID assigned before persist.
• Returning entities straight from controllers. Lazy proxies serialize unpredictably and leak your schema. Map to DTOs at the boundary.

Wrapping up

The N+1 problem isn’t a bug in Hibernate — it’s the cost of letting lazy loading happen implicitly, one row at a time. The cure is to make fetching explicit and intentional:

1. Make all associations LAZY.
2. Turn off open-in-view.
3. Fetch exactly what each query needs via JOIN FETCH, @EntityGraph, or DTO projections.
4. Set a global default_batch_fetch_size as a safety net.
5. Assert query counts in tests so regressions can’t sneak back in.

Do that and your “load all authors” endpoint fires one query instead of 301 — and stays that way.

If this helped you slay an N+1 dragon, follow the devdomain publication for more deep Spring and JPA deep-dives. Got a fetching war story or a trick I missed? Drop it in the comments — I read and reply to every one.

Spring Data JPA Relationships and the N+1 Problem, Solved was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

This article explains why the obvious solution (two-phase commit) fails at scale, the two saga styles, how compensation actually works, the failure-handling vocabulary you need (semantic locks, retriable vs compensatable steps, isolation anomalies), and concrete Spring Boot 3.x code for both choreography and orchestration.

Why two-phase commit fails at scale

Two-phase commit (2PC) is the textbook answer to distributed atomicity. A coordinator asks every participant to prepare (phase 1); if all vote yes, it tells them to commit (phase 2). It genuinely gives you ACID across nodes. It also has properties that make it a poor fit for internet-scale microservices.

• Synchronous coupling and blocking. Between prepare and commit, each participant holds locks on the affected rows. Every service in the transaction must be up, reachable, and fast at the same time. The transaction’s availability becomes the product of every participant’s availability — the opposite of why you split into services.
• The coordinator is a failure point. If the coordinator crashes after participants vote “yes” but before it broadcasts the decision, participants are stuck holding locks, unable to safely commit or abort. This is the classic 2PC blocking problem. Recovery requires a durable coordinator log and careful timeout handling.
• It does not scale with latency. Locks held for the duration of a network round trip kill throughput under contention. A hot row (a popular SKU’s stock count) becomes a global serialization point.
• Heterogeneity. 2PC needs an XA-capable resource manager on every participant. Your payment provider is an HTTP API. Kafka is not an XA resource in any practical sense. A third-party shipping service will never enlist in your transaction. The moment one participant cannot speak XA, 2PC is off the table.

The deeper issue is philosophical. Microservices buy you autonomy — independent deployment, independent scaling, independent failure. 2PC reintroduces a tight temporal coupling that throws that autonomy away. Sagas make the opposite trade: they give up immediate, global isolation in exchange for availability and loose coupling.

What a saga actually is

A saga is a sequence of local transactions. Each local transaction updates a single service’s database and publishes a message (an event or a command) that triggers the next local transaction. There is no global lock and no global commit. Each step commits independently and immediately.

Because there is no rollback across services, a saga handles failure differently from a database. If step 4 fails, you cannot “roll back” steps 1–3 — they already committed. Instead you run compensating transactions: new local transactions that semantically undo the effects of the earlier committed steps, in reverse order.

So a saga has two flavors of step:

• Forward (compensatable) transactions — T1, T2, ..., Tn — the happy path.
• Compensating transactions — C1, C2, ..., Cn-1 — the undo path. Ci semantically reverses Ti.

The guarantee a saga gives you is: either all forward transactions complete, or a subset of forward transactions complete and the corresponding compensations run. That is atomicity, but not isolation. We will come back to the isolation hole, because it is where most people get hurt.

The worked example: Order → Payment → Inventory

Throughout, we use a single scenario. A customer places an order. The system must:

1. Create the order in PENDING state (Order Service).
2. Charge the customer (Payment Service).
3. Reserve stock for the line items (Inventory Service).
4. Mark the order CONFIRMED (Order Service).

If payment fails, we cancel the order. If inventory reservation fails, we refund the payment and cancel the order. Here is the flow with its compensation arrows.

Happy path (forward transactions)
   ───────────────────────────────────────────────►
 ┌─────────┐   ┌─────────┐   ┌───────────┐   ┌─────────┐
 │ ORDER   │   │ PAYMENT │   │ INVENTORY │   │ ORDER   │
 │ create  │──►│ charge  │──►│ reserve   │──►│ confirm │
 │ (T1)    │   │ (T2)    │   │ (T3)      │   │ (T4)    │
 └─────────┘   └─────────┘   └───────────┘   └─────────┘
      ▲             ▲              │
      │             │              │ T3 fails (out of stock)
      │  C1         │  C2          ▼
 ┌─────────┐   ┌─────────┐   ┌───────────┐
 │ ORDER   │◄──│ PAYMENT │◄──│   (no-op: │
 │ cancel  │   │ refund  │   │  nothing  │
 │ (C1)    │   │ (C2)    │   │ reserved) │
 └─────────┘   └─────────┘   └───────────┘
   ◄───────────────────────────────────────
   Compensation path (reverse order)

The key insight: compensations run in reverse order of the forward steps that succeeded. If T3 fails, we compensate T2 (refund) then T1 (cancel order). T3 itself produced no committed effect, so it needs no compensation.

Choreography vs orchestration

There are two ways to coordinate the steps. They are not interchangeable — the choice shapes coupling, observability, and how hard the failure logic is to reason about.

Choreography is decentralized. Each service listens for events and reacts by doing its local work and emitting its own event. There is no central brain. Order Service emits OrderCreated; Payment Service hears it, charges, emits PaymentCompleted; Inventory Service hears that, reserves, emits StockReserved; Order Service hears that and confirms. The "workflow" is an emergent property of who subscribes to what.

Orchestration is centralized. A dedicated orchestrator (a saga execution coordinator) sends explicit commands (ChargePayment, ReserveStock) and waits for replies. The orchestrator holds the state machine: it knows what step we are on, what to do next, and which compensations to fire on failure.

| Dimension | Choreography | Orchestration |
|---|---|---|
| Coordination | Decentralized, event-driven | Central orchestrator with explicit commands |
| Coupling | Looser at runtime, tighter conceptually (everyone knows the event contract) | Services coupled to orchestrator, not to each other |
| Workflow visibility | Implicit, scattered across services | Explicit, in one place — easy to read |
| Adding a step | Risk of cyclic event dependencies; hard to see full flow | Edit the orchestrator state machine |
| Failure/compensation logic | Spread across services, easy to get subtly wrong | Centralized, easier to test exhaustively |
| Single point of failure | None inherent | Orchestrator (mitigated by persisting saga state) |
| Best for | Short sagas (2–4 steps), few participants | Long or complex sagas, many branches |

Rule of thumb: choreography for simple, short flows where the event chain is obvious; orchestration once you have branching, more than ~4 steps, or you need a human to be able to answer “what state is order #4471 in?” without grepping five services.

Choreography with Spring Boot 3.x and Kafka

We use Kafka as the event backbone. The critical correctness concern is the dual-write problem: a service must update its own database and publish an event atomically. If it commits the DB row but crashes before publishing, the saga stalls. The standard fix is the transactional outbox: write the event into an outbox table in the same local transaction as the business change, then a separate relay publishes from the outbox to Kafka.

First, the order entity and the outbox-backed event write. Using Spring’s ApplicationEventPublisher lets us decouple, but the outbox row is what guarantees durability.

@Entity
@Table(name = "orders")
public class Order {
    @Id
    private UUID id;

    @Enumerated(EnumType.STRING)
    private OrderStatus status; // PENDING, CONFIRMED, CANCELLED

    private String customerId;
    private BigDecimal amount;

    @Version
    private long version; // optimistic locking guards concurrent updates

    // getters/setters/constructors omitted for brevity
}

@Entity
@Table(name = "outbox")
public class OutboxEvent {
    @Id
    private UUID id;
    private String aggregateType; // "order"
    private String aggregateId;   // order id
    private String type;          // "OrderCreated"
    @Column(columnDefinition = "jsonb")
    private String payload;
    private Instant createdAt;
    // getters/setters omitted
}

@Service
public class OrderService {

    private final OrderRepository orders;
    private final OutboxRepository outbox;
    private final ObjectMapper mapper;

    public OrderService(OrderRepository orders, OutboxRepository outbox, ObjectMapper mapper) {
        this.orders = orders;
        this.outbox = outbox;
        this.mapper = mapper;
    }

    @Transactional
    public Order placeOrder(String customerId, BigDecimal amount) {
        Order order = new Order(UUID.randomUUID(), OrderStatus.PENDING, customerId, amount);
        orders.save(order);

        // Same transaction as the order insert: no dual-write hole.
        var event = new OrderCreated(order.getId(), customerId, amount);
        outbox.save(new OutboxEvent(
                UUID.randomUUID(), "order", order.getId().toString(),
                "OrderCreated", writeJson(event), Instant.now()));
        return order;
    }

    private String writeJson(Object o) {
        try {
            return mapper.writeValueAsString(o);
        } catch (JsonProcessingException e) {
            throw new IllegalStateException("event serialization failed", e);
        }
    }
}

In production you would typically let Debezium tail the outbox table's transaction log straight into Kafka. If you do not want CDC, a simple polling relay is fine for moderate volumes:

@Component
public class OutboxRelay {

    private final OutboxRepository outbox;
    private final KafkaTemplate<String, String> kafka;

    public OutboxRelay(OutboxRepository outbox, KafkaTemplate<String, String> kafka) {
        this.outbox = outbox;
        this.kafka = kafka;
    }

    @Scheduled(fixedDelay = 500)
    @Transactional
    public void publishPending() {
        List<OutboxEvent> batch = outbox.findTop100ByOrderByCreatedAtAsc();
        for (OutboxEvent e : batch) {
            // topic name derived from aggregate type; key = aggregateId for ordering
            kafka.send(e.getAggregateType() + "-events", e.getAggregateId(), e.getPayload());
            outbox.delete(e);
        }
    }
}

Note the Kafka key is the aggregate id. That preserves per-order ordering on the topic partition, which matters: you do not want PaymentCompleted overtaking OrderCreated for the same order.

Now the Payment Service consumes OrderCreated and reacts. The consumer must be idempotent — Kafka guarantees at-least-once delivery, so the same event can arrive twice.

@Component
public class PaymentEventHandler {

    private final PaymentRepository payments;
    private final ProcessedEventRepository processed;
    private final OutboxRepository outbox;
    private final ObjectMapper mapper;

    // constructor omitted

    @KafkaListener(topics = "order-events", groupId = "payment-service")
    @Transactional
    public void onOrderEvent(ConsumerRecord<String, String> record) throws Exception {
        JsonNode node = mapper.readTree(record.value());
        if (!"OrderCreated".equals(node.get("type").asText())) {
            return; // not our concern
        }
        var event = mapper.treeToValue(node, OrderCreated.class);

        // Idempotency guard: dedupe by event id in the same transaction.
        if (processed.existsById(event.eventId())) {
            return;
        }
        processed.save(new ProcessedEvent(event.eventId(), Instant.now()));

        try {
            payments.save(Payment.charge(event.orderId(), event.amount()));
            emit("PaymentCompleted", new PaymentCompleted(event.orderId(), event.amount()));
        } catch (PaymentDeclinedException ex) {
            // No money moved; emit a failure event to trigger compensation upstream.
            emit("PaymentFailed", new PaymentFailed(event.orderId(), ex.getReason()));
        }
    }

    private void emit(String type, Object payload) {
        outbox.save(new OutboxEvent(UUID.randomUUID(), "payment",
                ((HasOrderId) payload).orderId().toString(), type, writeJson(payload), Instant.now()));
    }
    // writeJson omitted
}

Inventory then listens for PaymentCompleted and tries to reserve stock. On failure it emits StockReservationFailed, which Payment Service consumes to issue a refund (its compensation, C2), and Order Service consumes to cancel the order (C1). Each compensation is itself a local transaction that emits its own event — the compensation chain is just more choreography running backwards.

The danger of choreography is visible here: there is no single place that says “the order saga has these four steps and these three compensations.” A new engineer must trace topic subscriptions across three repos. This is exactly the pain orchestration removes.

Orchestration with an explicit coordinator

In orchestration, the orchestrator owns a persisted state machine. It sends commands and consumes replies. Persisting saga state is non-negotiable: if the orchestrator restarts mid-saga, it must resume from where it left off, not from the start.

@Entity
@Table(name = "order_saga_state")
public class OrderSagaState {
    @Id
    private UUID sagaId;
    private UUID orderId;

    @Enumerated(EnumType.STRING)
    private SagaStep step; // STARTED, PAYMENT_REQUESTED, STOCK_REQUESTED, COMPLETED, COMPENSATING, FAILED

    private boolean paymentCharged; // track what must be compensated
    private boolean stockReserved;

    @Version
    private long version;
    // getters/setters omitted
}

@Service
public class OrderSagaOrchestrator {

    private final OrderSagaStateRepository state;
    private final CommandGateway commands; // thin wrapper over KafkaTemplate for command topics

    public OrderSagaOrchestrator(OrderSagaStateRepository state, CommandGateway commands) {
        this.state = state;
        this.commands = commands;
    }

    @Transactional
    public void start(UUID orderId, BigDecimal amount, String customerId) {
        var saga = new OrderSagaState(UUID.randomUUID(), orderId, SagaStep.PAYMENT_REQUESTED);
        state.save(saga);
        commands.send("payment-commands",
                new ChargePayment(saga.getSagaId(), orderId, customerId, amount));
    }

    @KafkaListener(topics = "payment-replies", groupId = "order-orchestrator")
    @Transactional
    public void onPaymentReply(PaymentReply reply) {
        OrderSagaState saga = state.findById(reply.sagaId()).orElseThrow();
        if (reply.success()) {
            saga.setPaymentCharged(true);
            saga.setStep(SagaStep.STOCK_REQUESTED);
            commands.send("inventory-commands",
                    new ReserveStock(saga.getSagaId(), saga.getOrderId()));
        } else {
            // Payment failed: nothing to compensate yet, just fail the order.
            saga.setStep(SagaStep.FAILED);
            commands.send("order-commands", new CancelOrder(saga.getOrderId()));
        }
    }

    @KafkaListener(topics = "inventory-replies", groupId = "order-orchestrator")
    @Transactional
    public void onInventoryReply(InventoryReply reply) {
        OrderSagaState saga = state.findById(reply.sagaId()).orElseThrow();
        if (reply.success()) {
            saga.setStockReserved(true);
            saga.setStep(SagaStep.COMPLETED);
            commands.send("order-commands", new ConfirmOrder(saga.getOrderId()));
        } else {
            // Stock failed: compensate in reverse order. Refund first, then cancel.
            saga.setStep(SagaStep.COMPENSATING);
            if (saga.isPaymentCharged()) {
                commands.send("payment-commands",
                        new RefundPayment(saga.getSagaId(), saga.getOrderId()));
            }
            commands.send("order-commands", new CancelOrder(saga.getOrderId()));
        }
    }
}

The orchestrator reads top-to-bottom like the business process. Adding a fraud-check step is a localized edit to this class plus one new command/reply pair — you do not touch the event subscriptions of unrelated services. The cost is that the orchestrator is now a component every order flows through; you mitigate its single-point-of-failure risk by running multiple instances against the shared, persisted saga state with optimistic locking (@Version).

For non-trivial systems, do not hand-roll this state machine. Spring Statemachine, Axon Framework’s saga support, Eventuate Tram Sagas, or a workflow engine like Temporal or Camunda give you persistence, retries, and timeouts out of the box. The hand-rolled version above is for understanding what those libraries are doing.

Failure handling: the part that is actually hard

The forward path is easy. The value of the saga pattern is in the failure semantics, and there is real vocabulary here.

Retriable vs compensatable steps

Eventuate’s model (from Chris Richardson’s Microservices Patterns) classifies each step:

• Compensatable transactions — steps that may need to be undone because a later step can fail. (Create order, Charge payment.)
• Pivot transaction — the point of no return. Once it commits, the saga will complete forward; there is no going back. (Often the last step that could fail for a business reason — e.g. Reserve stock if everything after it is guaranteed to succeed.)
• Retriable transactions — steps after the pivot that must eventually succeed and are therefore only ever retried, never compensated. (Confirm order, Send confirmation email.)

Why this matters: you design the saga so that everything that can fail for a business reason happens before the pivot, and everything after the pivot is something you can guarantee by retrying. Send confirmation email must never be allowed to fail the whole order — it is retriable. You do not refund a customer because an SMTP server was briefly down.

Idempotency and retries

Every consumer must be idempotent because messaging is at-least-once. We saw the ProcessedEvent dedupe table above. Compensations must also be idempotent — a refund command might be delivered twice, and you must refund only once. Track compensation state explicitly (the paymentCharged flag), and make the refund a no-op if it has already run.

Compensations themselves can fail (the payment gateway is down during a refund). The rule: compensations must be retried until they succeed, with backoff and a dead-letter queue plus alerting as the last resort. A compensation that gives up leaves the system in an inconsistent state — money taken, order cancelled. This is the worst outcome and warrants a human.

Semantic locks: closing the isolation hole

Here is the uncomfortable truth: sagas are not isolated. While a saga is in flight, its partial, uncommitted-from-a-business-view changes are visible to everyone. A monolithic transaction would hide them until commit. The classic anomalies (from the same literature):

• Lost updates — saga A overwrites a change made by saga B without seeing it.
• Dirty reads — saga B reads data that saga A has changed but later compensates away. B made a decision on data that “never really happened.”
• Fuzzy / non-repeatable reads — different steps of the same saga read the same data and get different answers because another saga modified it in between.

The standard countermeasure is the semantic lock: instead of locking rows at the database level, you mark the affected business entity with an application-level flag indicating an in-progress saga. The Order.status = PENDING is exactly this — it tells the rest of the system "this order is not finished; do not treat it as confirmed." A stock reservation is another semantic lock: the quantity is moved to a RESERVED bucket, visible as unavailable, but not yet SOLD. If the saga compensates, the reservation is released.

@Service
public class InventoryService {

    private final StockRepository stock;

    public InventoryService(StockRepository stock) {
        this.stock = stock;
    }

    @Transactional
    public boolean reserve(UUID orderId, String sku, int qty) {
        // Optimistic-locked read-modify-write avoids lost updates on hot SKUs.
        StockItem item = stock.findBySku(sku).orElseThrow();
        if (item.available() < qty) {
            return false; // triggers StockReservationFailed -> compensation
        }
        // Semantic lock: move to RESERVED, not SOLD. Visible as unavailable to others.
        item.reserve(orderId, qty);
        stock.save(item); // @Version on StockItem throws on concurrent modification -> retry
        return true;
    }

    @Transactional
    public void releaseReservation(UUID orderId, String sku, int qty) {
        // Compensation C3 — idempotent: only release if a reservation exists.
        stock.findBySku(sku).ifPresent(item -> {
            if (item.hasReservation(orderId)) {
                item.release(orderId, qty);
                stock.save(item);
            }
        });
    }
}

Other countermeasures worth knowing: commutative updates (design operations so order does not matter — credit/debit instead of setBalance), pessimistic views (reorder steps so the riskiest comes first, shrinking the window of inconsistency), and re-reads / version checks before compensating to detect intervening changes. None of these gives you true isolation; they reduce the probability and blast radius of anomalies. You must decide, per saga, which anomalies your business can tolerate.

When to use the saga pattern — and when not to

Use a saga when:

• A business operation spans multiple services with separate databases and you need an all-or-nothing business outcome.
• The participants cannot or should not be coupled by 2PC (third-party APIs, message brokers, high-throughput hot rows).
• You can tolerate eventual consistency and brief windows where partial results are visible.

Do not reach for a saga when:

• The data belongs together. If three services are always changing in one transaction, that is a hint your service boundaries are wrong. The cheapest fix is often to merge them into one service with one database and one ordinary @Transactional — no saga needed.
• You need strong isolation / read-your-writes semantics for the in-flight operation. Sagas cannot give you serializability across services.
• The operation is genuinely single-service. Do not build a saga for something a local transaction handles.

Pitfalls checklist

• Dual-write without an outbox. Committing the DB then publishing as two separate operations will eventually drop or duplicate events. Always use a transactional outbox (or CDC) so the event and the state change share one transaction.
• Non-idempotent consumers and compensations. At-least-once delivery means everything runs more than once. Dedupe by event id; make compensations no-ops when already applied.
• Forgetting that compensations can fail. Retry them forever (with backoff) and alert; never silently drop.
• Ignoring isolation anomalies. Audit every saga for dirty reads and lost updates. Add semantic locks (status flags, reservations) deliberately, not by accident.
• Choreography sprawl. Beyond ~4 steps or any branching, the implicit event web becomes unmaintainable and prone to cyclic dependencies. Switch to orchestration.
• No saga timeout. A step’s reply may never come. Set per-step timeouts so a stuck saga triggers compensation instead of hanging forever.
• Treating retriable steps as compensatable. Do not unwind a customer’s whole order because a non-critical post-pivot step (email, analytics) failed. Retry it.

Closing thought

Sagas are not a free upgrade from 2PC — they are a different deal. You trade global atomicity-with-isolation for atomicity-without-isolation, and you pay for it in idempotency code, compensation logic, and careful anomaly analysis. Done well, they let independent services stay independent while still delivering coherent business outcomes. Done carelessly, they leave money charged against cancelled orders. The difference is entirely in how seriously you take the failure path.

If this breakdown helped, follow the devdomain publication for more deep dives into distributed systems and backend architecture. Have you run sagas in production — choreography or orchestration, and what bit you? Drop your war stories in the comments; the messy real-world cases are the best part.

The Saga Pattern: Managing Distributed Transactions Across MicroservicesYou split a monolith into… was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

The fix is a single, consistent error contract enforced in one place. Spring Boot gives you the tools: @ControllerAdvice for centralized handling, @ExceptionHandler for mapping exceptions to responses, and — since Spring 6 / Boot 3 — first-class support for ProblemDetail, the standardized error format defined by RFC 7807 (now RFC 9457). This article builds a complete, production-grade error-handling layer.

The problem with scattered error handling

Without a strategy, error handling spreads across controllers:

// DON'T: error handling tangled into business code
@GetMapping("/orders/{id}")
public ResponseEntity<?> getOrder(@PathVariable Long id) {
    Order o = repo.findById(id).orElse(null);
    if (o == null) {
        return ResponseEntity.status(404)
            .body(Map.of("error", "order not found"));
    }
    return ResponseEntity.ok(o);
}

Every controller reinvents the wheel, formats differ, and cross-cutting concerns (logging, correlation IDs) get copy-pasted. Centralize instead: let controllers throw meaningful exceptions and translate them in one advice.

RFC 7807: a standard error shape

RFC 7807 (“Problem Details for HTTP APIs”) defines a media type, application/problem+json, and a canonical structure:

| Field | Meaning |
|---|---|
| `type` | A URI identifying the problem type (a stable, dereferenceable category) |
| `title` | A short, human-readable summary of the problem type |
| `status` | The HTTP status code |
| `detail` | A human-readable explanation specific to this occurrence |
| `instance` | A URI identifying this specific occurrence |

Plus any extension members you add (e.g. errors, traceId). A compliant response looks like:

{
  "type": "https://api.example.com/problems/order-not-found",
  "title": "Order Not Found",
  "status": 404,
  "detail": "No order exists with id 4711",
  "instance": "/orders/4711",
  "traceId": "0af7651916cd43dd8448eb211c80319c"
}

Spring 6 models this with the org.springframework.http.ProblemDetail class — no third-party library required.

ProblemDetail by hand

ProblemDetail is a plain holder you can build and return directly:

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import java.net.URI;

ProblemDetail pd = ProblemDetail.forStatusAndDetail(
    HttpStatus.NOT_FOUND, "No order exists with id 4711");
pd.setType(URI.create("https://api.example.com/problems/order-not-found"));
pd.setTitle("Order Not Found");
pd.setProperty("traceId", "0af7651916cd43dd8448eb211c80319c"); // extension member

setProperty adds arbitrary extension fields, serialized flat alongside the standard ones.

Turning it on for built-in exceptions

Spring MVC throws a family of internal exceptions (e.g. HttpMessageNotReadableException, MethodArgumentNotValidException, NoResourceFoundException). To make Spring render those as ProblemDetail automatically, enable the property:

spring.mvc.problemdetails.enabled=true

(WebFlux uses spring.webflux.problemdetails.enabled=true.) With this on, framework-level errors already come back as RFC 7807 documents. Your job is to handle your exceptions consistently and enrich the defaults.

Global handling with @RestControllerAdvice

@ControllerAdvice (or @RestControllerAdvice, which adds @ResponseBody) registers exception handlers that apply across all controllers. Combined with ProblemDetail returns, it's the backbone of a clean contract.

Define domain exceptions first:

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) { super(message); }
}

public class BusinessRuleException extends RuntimeException {
    private final String code;
    public BusinessRuleException(String code, String message) {
        super(message);
        this.code = code;
    }
    public String getCode() { return code; }
}

Now the central advice:

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.net.URI;
import java.time.Instant;

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
    private static final String BASE = "https://api.example.com/problems/";

    @ExceptionHandler(ResourceNotFoundException.class)
    public ProblemDetail handleNotFound(ResourceNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setType(URI.create(BASE + "resource-not-found"));
        pd.setTitle("Resource Not Found");
        pd.setProperty("timestamp", Instant.now());
        return pd;
    }

    @ExceptionHandler(BusinessRuleException.class)
    public ProblemDetail handleBusinessRule(BusinessRuleException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
        pd.setType(URI.create(BASE + "business-rule-violation"));
        pd.setTitle("Business Rule Violation");
        pd.setProperty("code", ex.getCode());
        return pd;
    }

    // Catch-all: never leak stack traces to clients
    @ExceptionHandler(Exception.class)
    public ProblemDetail handleUnexpected(Exception ex) {
        log.error("Unhandled exception", ex); // log full detail server-side
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.INTERNAL_SERVER_ERROR,
            "An unexpected error occurred. Please contact support.");
        pd.setType(URI.create(BASE + "internal-error"));
        pd.setTitle("Internal Server Error");
        return pd;
    }
}

Two principles already baked in: never expose internal exception messages or stack traces to clients (the catch-all returns a generic detail while logging the real cause), and map each exception type to a meaningful status.

Handling validation errors properly

Bean Validation (jakarta.validation) is where consistent error responses pay off most, because clients need field-level detail to fix their input.

Annotate your request DTO:

import jakarta.validation.constraints.*;

public record CreateUserRequest(
    @NotBlank String username,
    @Email String email,
    @Min(18) int age,
    @Size(min = 8) String password
) {}

Trigger validation with @Valid:

@PostMapping("/users")
public ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest req) {
    // if invalid, MethodArgumentNotValidException is thrown before this runs
    return ResponseEntity.ok(service.create(req));
}

When validation fails, Spring throws MethodArgumentNotValidException. To emit a clean RFC 7807 response with per-field errors, extend ResponseEntityExceptionHandler — it already handles the Spring MVC exceptions and lets you customize them, returning ProblemDetail bodies:

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
import java.net.URI;
import java.util.ArrayList;
import java.util.List;

@RestControllerAdvice
public class ValidationExceptionHandler extends ResponseEntityExceptionHandler {

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex,
            HttpHeaders headers,
            HttpStatusCode status,
            WebRequest request) {

        List<FieldError> errors = new ArrayList<>();
        ex.getBindingResult().getFieldErrors().forEach(fe ->
            errors.add(new FieldError(fe.getField(), fe.getDefaultMessage())));
        ex.getBindingResult().getGlobalErrors().forEach(ge ->
            errors.add(new FieldError(ge.getObjectName(), ge.getDefaultMessage())));

        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            org.springframework.http.HttpStatus.BAD_REQUEST,
            "Request validation failed");
        pd.setType(URI.create("https://api.example.com/problems/validation-error"));
        pd.setTitle("Validation Error");
        pd.setProperty("errors", errors);

        return ResponseEntity.badRequest().body(pd);
    }

    public record FieldError(String field, String message) {}
}

Resulting payload:

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    { "field": "email", "message": "must be a well-formed email address" },
    { "field": "age", "message": "must be greater than or equal to 18" }
  ]
}

Handling constraint violations on path/query params

@Valid on a body throws MethodArgumentNotValidException. But validating method parameters directly (e.g. @RequestParam @Min(1) int page with @Validated on the controller) throws jakarta.validation.ConstraintViolationException instead — a different exception. Handle it too:

import jakarta.validation.ConstraintViolationException;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ExceptionHandler(ConstraintViolationException.class)
public ProblemDetail handleConstraintViolation(ConstraintViolationException ex) {
    var errors = ex.getConstraintViolations().stream()
        .map(v -> new FieldError(v.getPropertyPath().toString(), v.getMessage()))
        .toList();
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(
        org.springframework.http.HttpStatus.BAD_REQUEST, "Constraint violation");
    pd.setProperty("errors", errors);
    return pd;
}

ErrorResponseException and ProblemDetail-aware exceptions

Spring 6 introduced ErrorResponse and ErrorResponseException, which carry their own ProblemDetail. You can make domain exceptions self-describing by implementing ErrorResponse, so they render correctly even without a dedicated handler:

import org.springframework.http.HttpStatus;
import org.springframework.web.ErrorResponseException;
import org.springframework.http.ProblemDetail;
import java.net.URI;

public class OrderNotFoundException extends ErrorResponseException {
    public OrderNotFoundException(Long id) {
        super(HttpStatus.NOT_FOUND, problem(id), null);
    }
    private static ProblemDetail problem(Long id) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, "No order exists with id " + id);
        pd.setType(URI.create("https://api.example.com/problems/order-not-found"));
        pd.setTitle("Order Not Found");
        return pd;
    }
}

Throwing this from a controller produces a correct application/problem+json response with no handler at all — Spring recognizes ErrorResponse and renders it.

Enriching every response: instance URI and trace IDs

Clients and support teams need to correlate an error to a log line. Add the request path as instance and a trace ID as an extension. A small helper on the advice keeps it DRY:

import org.springframework.web.context.request.ServletWebRequest;
import org.springframework.web.context.request.WebRequest;
import java.net.URI;

private void enrich(ProblemDetail pd, WebRequest request) {
    if (request instanceof ServletWebRequest swr) {
        pd.setInstance(URI.create(swr.getRequest().getRequestURI()));
    }
    // From MDC / tracing context (e.g. Micrometer Tracing populates this)
    String traceId = org.slf4j.MDC.get("traceId");
    if (traceId != null) pd.setProperty("traceId", traceId);
}

Call enrich(pd, request) at the end of each handler (add WebRequest request to the handler signatures). Now every error is traceable.

Scoping advice and ordering multiple handlers

@RestControllerAdvice applies globally by default, but you can scope it — useful in modular applications where different packages need different error contracts (e.g. a public API vs an internal admin API):

// Only applies to controllers in the public API package
@RestControllerAdvice(basePackages = "com.example.api.public_")
public class PublicApiExceptionHandler { ... }

// Only applies to controllers annotated with @AdminApi
@RestControllerAdvice(annotations = AdminApi.class)
public class AdminApiExceptionHandler { ... }

When more than one advice can handle the same exception type, Spring resolves by @Order (lower value wins) and by handler specificity — a handler for ResourceNotFoundException beats one for RuntimeException. Keep this predictable: prefer a single advice per concern, and only layer them when you have a genuine reason (a fallback advice with @Order(Ordered.LOWEST_PRECEDENCE) catching Exception is a common, legitimate pattern).

How handler method resolution works

When an exception escapes a controller, Spring’s ExceptionHandlerExceptionResolver walks the advice beans and looks for the most specific @ExceptionHandler whose declared types match the thrown exception (or a cause, when configured). Matching considers the exception hierarchy, so a handler for a superclass catches subclasses unless a more specific handler exists. This is why a catch-all @ExceptionHandler(Exception.class) reliably acts as a backstop: it matches everything, but loses to any narrower handler.

exception thrown in controller
        |
        v
ExceptionHandlerExceptionResolver
        |
        v
find most specific @ExceptionHandler across @ControllerAdvice beans
        |
        +-- match found  -> invoke handler -> render ProblemDetail
        |
        +-- no match     -> propagate to container -> default error page / 500

Content negotiation and the problem+json media type

When you return a ProblemDetail, Spring serializes it as application/problem+json (for JSON) or application/problem+xml (for XML), per the RFC. Clients that inspect the Content-Type can branch on it to detect an error envelope without parsing the body first. This is one of the quiet advantages of the standard: the media type itself signals "this is a problem document," which generic HTTP clients and gateways can act on.

If you instead return a hand-rolled Map or custom DTO, you lose that signal and the standard structure, and every consumer must special-case your shape. Returning ProblemDetail is therefore not just cleaner code — it's a more interoperable contract.

Testing your error contract

Error handling is exactly the kind of code that rots silently, so test it. A @WebMvcTest slice exercises the advice without booting the full context:

import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.web.servlet.MockMvc;
import org.junit.jupiter.api.Test;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(OrderController.class)
class OrderErrorContractTest {

    @Autowired MockMvc mvc;

    @Test
    void missingOrder_returnsProblemDetail() throws Exception {
        mvc.perform(get("/orders/4711"))
           .andExpect(status().isNotFound())
           .andExpect(content().contentType("application/problem+json"))
           .andExpect(jsonPath("$.title").value("Order Not Found"))
           .andExpect(jsonPath("$.status").value(404))
           .andExpect(jsonPath("$.type").exists());
    }
}

Asserting on Content-Type and the standard fields locks down the contract so a future refactor can't quietly change the error shape your clients depend on.

A summary of the mapping strategy

| Exception | HTTP status | Where handled |
|---|---|---|
| `ResourceNotFoundException` (yours) | 404 | `@ExceptionHandler` |
| `BusinessRuleException` (yours) | 422 | `@ExceptionHandler` |
| `MethodArgumentNotValidException` | 400 | Override in `ResponseEntityExceptionHandler` |
| `ConstraintViolationException` | 400 | `@ExceptionHandler` |
| `HttpMessageNotReadableException` | 400 | Built-in (problemdetails enabled) |
| `AccessDeniedException` | 403 | Security layer / advice |
| Anything else | 500 | Catch-all `@ExceptionHandler(Exception.class)` |

Common pitfalls

• Leaking internals: returning ex.getMessage() from a generic 500 can expose SQL, file paths, or class names. The catch-all must return a generic message and log the real cause.
• Two handlers for the same exception: if both a plain @RestControllerAdvice and a ResponseEntityExceptionHandler subclass handle the same type, ordering is ambiguous. Keep one source of truth; use @Order on advices if you must layer them.
• Forgetting @Valid: validation annotations on a DTO do nothing without @Valid (body) or @Validated (params) at the call site.
• Confusing the two validation exceptions: body validation throws MethodArgumentNotValidException; param validation throws ConstraintViolationException. Handle both.
• Not enabling spring.mvc.problemdetails.enabled: without it, built-in framework errors won't be RFC 7807 by default.
• Returning the wrong status for business errors: 422 (Unprocessable Entity) often fits domain-rule failures better than 400 (malformed request). Choose intentionally.
• Self-invocation / exceptions thrown outside the dispatcher: @ControllerAdvice only catches exceptions propagating out of controller handling. Errors in filters or async threads need separate handling.
• Inconsistent type URIs: keep them stable and documented; clients may branch on type, so changing it is a breaking change.

Best practices

• One @RestControllerAdvice per concern (e.g. domain errors, validation), each focused and small.
• Use ProblemDetail everywhere so the contract is uniform and standards-compliant (application/problem+json).
• Make type URIs stable and resolvable to documentation; treat them as part of your API contract.
• Always include instance and a traceId for correlation.
• Map exceptions to semantic status codes; never default everything to 400 or 500.
• Validate at the edge with Bean Validation and surface field-level errors as an errors extension array.
• Log full detail server-side; return only safe, actionable detail to clients.
• Cover the catch-all so an unexpected exception never escapes as a stack trace.

Conclusion

Consistent error handling is a contract, not an afterthought. Spring Boot 3 makes that contract cheap to honor: @RestControllerAdvice centralizes mapping, @ExceptionHandler ties exceptions to responses, and built-in ProblemDetail gives you RFC 7807 / 9457 compliance without a library. Enable spring.mvc.problemdetails.enabled, extend ResponseEntityExceptionHandler for validation, enrich every response with an instance URI and traceId, and guard against leaks with a generic catch-all. The result is an API where every error — from a missing resource to an invalid field to a catastrophic 500 — speaks the same predictable language.

If this helped you standardize your API’s errors, follow devdomain for more Spring Boot deep dives, and drop a comment with the ugliest error payload you’ve had to consume. Misery loves company.

Spring Boot Error Handling: @ControllerAdvice and ProblemDetail (RFC 7807)Most APIs leak. was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

Then the file grows to 12 million rows. The loop runs out of heap. A network blip on row 8,000,000 kills the process — and you have no idea which rows committed, so you can’t safely re-run it. There’s no progress reporting, no retry, no parallelism, and certainly no way to resume from where it died.

This is exactly the problem Spring Batch was built to solve. It provides a battle-tested framework for chunk-oriented processing with transactions, restartability, skip/retry policies, and partitioned parallelism — the unglamorous machinery that turns a fragile script into a reliable production job. This article builds a complete, real example and covers the production concerns that matter.

The core model

Spring Batch organizes work into a hierarchy:

• A Job is the whole unit of work (e.g. "import customers").
• A Job has one or more Steps, run in sequence (or conditionally).
• A chunk-oriented Step is built from three collaborators:
• ItemReader — reads one item at a time from a source (file, DB, queue).
• ItemProcessor — transforms/validates/filters one item (optional).
• ItemWriter — writes items in batches (a chunk) to a destination.
• The JobRepository persists execution metadata to the database, which is what makes restart and monitoring possible.
• A JobLauncher starts a job with a set of JobParameters.

The key insight is chunk-oriented processing: read N items one by one, process each, then hand the whole chunk of N to the writer inside a single transaction. Commit, repeat. This bounds memory to one chunk and gives you natural transactional boundaries.

Project setup

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-batch</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

Spring Batch needs its metadata tables (BATCH_JOB_INSTANCE, BATCH_STEP_EXECUTION, etc.). Spring Boot creates them automatically:

spring.batch.jdbc.initialize-schema=always
# Don't run jobs automatically on context startup; we'll launch explicitly
spring.batch.job.enabled=false

In Spring Boot 3 / Spring Batch 5, @EnableBatchProcessing is no longer required — auto-configuration wires the JobRepository, JobLauncher, and a JDBC transactionManager for you. (Adding @EnableBatchProcessing actually disables that auto-config, so leave it off unless you need to customize.)

A complete worked example

The job: read a large CSV of raw customer records, validate and normalize them, and persist valid ones to the database.

The domain

public record CustomerCsv(String firstName, String lastName, String email, String country) {}

@Entity
@Table(name = "customer")
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String firstName;
    private String lastName;
    private String email;
    private String countryCode;
    // getters / setters
}

The reader

FlatFileItemReader streams the file line by line — it never loads the whole file into memory.

import org.springframework.batch.item.file.FlatFileItemReader;
import org.springframework.batch.item.file.builder.FlatFileItemReaderBuilder;
import org.springframework.core.io.FileSystemResource;

@Bean
@StepScope
public FlatFileItemReader<CustomerCsv> customerReader(
        @Value("#{jobParameters['inputFile']}") String inputFile) {
    return new FlatFileItemReaderBuilder<CustomerCsv>()
        .name("customerReader")
        .resource(new FileSystemResource(inputFile))
        .linesToSkip(1)                       // header row
        .delimited()
        .names("firstName", "lastName", "email", "country")
        .targetType(CustomerCsv.class)
        .build();
}

@StepScope is important: it lets the reader receive a late-bound jobParameters value (the file path) and gives each execution its own reader instance.

The processor

The processor validates and normalizes. Returning null from a processor filters the item — it is silently dropped and never reaches the writer.

import org.springframework.batch.item.ItemProcessor;
import org.springframework.stereotype.Component;

@Component
public class CustomerProcessor implements ItemProcessor<CustomerCsv, Customer> {

    private static final java.util.regex.Pattern EMAIL =
        java.util.regex.Pattern.compile("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$");

    @Override
    public Customer process(CustomerCsv in) {
        if (in.email() == null || !EMAIL.matcher(in.email().trim()).matches()) {
            return null; // filter out invalid rows
        }
        Customer c = new Customer();
        c.setFirstName(in.firstName().trim());
        c.setLastName(in.lastName().trim());
        c.setEmail(in.email().trim().toLowerCase());
        c.setCountryCode(normalizeCountry(in.country()));
        return c;
    }

    private String normalizeCountry(String raw) {
        if (raw == null) return "XX";
        return raw.trim().toUpperCase().substring(0, Math.min(2, raw.trim().length()));
    }
}

The writer

JpaItemWriter persists a whole chunk in one transaction.

import org.springframework.batch.item.data.JpaItemWriter;
import org.springframework.batch.item.data.builder.JpaItemWriterBuilder;
import jakarta.persistence.EntityManagerFactory;

@Bean
public JpaItemWriter<Customer> customerWriter(EntityManagerFactory emf) {
    return new JpaItemWriterBuilder<Customer>()
        .entityManagerFactory(emf)
        .build();
}

For Raw throughput, JdbcBatchItemWriter with a parameterized INSERT is faster because it bypasses the persistence context:

@Bean
public JdbcBatchItemWriter<Customer> jdbcCustomerWriter(DataSource dataSource) {
    return new JdbcBatchItemWriterBuilder<Customer>()
        .dataSource(dataSource)
        .sql("""
            insert into customer (first_name, last_name, email, country_code)
            values (:firstName, :lastName, :email, :countryCode)
            """)
        .beanMapped()
        .build();
}

Wiring the Step and Job

In Spring Batch 5 you build steps and jobs with builders that take the JobRepository and a transaction manager.

import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CustomerImportJobConfig {

    @Bean
    public Step importStep(JobRepository jobRepository,
                           PlatformTransactionManager txManager,
                           FlatFileItemReader<CustomerCsv> customerReader,
                           CustomerProcessor processor,
                           JpaItemWriter<Customer> customerWriter) {
        return new StepBuilder("importStep", jobRepository)
            .<CustomerCsv, Customer>chunk(1000, txManager)
            .reader(customerReader)
            .processor(processor)
            .writer(customerWriter)
            .build();
    }

    @Bean
    public Job importCustomersJob(JobRepository jobRepository, Step importStep) {
        return new JobBuilder("importCustomersJob", jobRepository)
            .start(importStep)
            .build();
    }
}

chunk(1000, txManager) means: read up to 1,000 items, process them, write all 1,000, and commit — then start the next chunk. Pick a chunk size that balances transaction overhead against memory and lock duration. 500–2,000 is a sensible starting range; benchmark for your workload.

Launching the job

import org.springframework.batch.core.*;
import org.springframework.batch.core.launch.JobLauncher;

@Component
public class CustomerImportRunner {

    private final JobLauncher jobLauncher;
    private final Job importCustomersJob;

    public CustomerImportRunner(JobLauncher jobLauncher, Job importCustomersJob) {
        this.jobLauncher = jobLauncher;
        this.importCustomersJob = importCustomersJob;
    }

    public void run(String inputFile) throws Exception {
        JobParameters params = new JobParametersBuilder()
            .addString("inputFile", inputFile)
            .addLong("run.timestamp", System.currentTimeMillis()) // makes the instance unique
            .toJobParameters();
        jobLauncher.run(importCustomersJob, params);
    }
}

Restartability

This is Spring Batch’s superpower. Because the JobRepository persists step execution state — including the read count — a job that failed can be re-launched with the same identifying job parameters and it resumes from the last committed chunk rather than starting over.

A few rules govern this:

• A JobInstance is identified by job name + identifying job parameters. Re-running with the same identifying parameters continues that instance; changing them creates a new instance.
• That’s why above we add a run.timestamp — a unique parameter makes each launch a fresh instance. For a restartable job you'd instead keep parameters identical (e.g. just inputFile) so a failed run can resume.
• A COMPLEQED instance cannot be re-run with the same parameters (you'd get JobInstanceAlreadyCompleteException). Only FAILED/STOPPED instances restart.
• Readers like FlatFileItemReader are restartable: they persist the line offset in the ExecutionContext and skip already-read lines on restart.

You can also mark a step non-restartable or allow a completed step to re-run with .allowStartIfComplete(true).

Fault tolerance: skip and retry

In the real world some records are simply bad and some failures are transient. A fault-tolerant step lets you handle both without aborting the whole job.

@Bean
public Step faultTolerantStep(JobRepository jobRepository,
                              PlatformTransactionManager txManager,
                              FlatFileItemReader<CustomerCsv> reader,
                              CustomerProcessor processor,
                              JpaItemWriter<Customer> writer) {
    return new StepBuilder("faultTolerantStep", jobRepository)
        .<CustomerCsv, Customer>chunk(1000, txManager)
        .reader(reader)
        .processor(processor)
        .writer(writer)
        .faultTolerant()
        // retry transient failures up to 3 times
        .retryLimit(3)
        .retry(org.springframework.dao.TransientDataAccessException.class)
        // skip bad records, up to 50 of them, then fail the job
        .skipLimit(50)
        .skip(org.springframework.batch.item.file.FlatFileParseException.class)
        .skip(jakarta.validation.ConstraintViolationException.class)
        .listener(skipListener())
        .build();
}

• Retry re-attempts an operation that threw a transient exception (a deadlock, a momentary connection drop). Use it only for errors that might succeed on a second try.
• Skip discards an individual bad item (a malformed CSV line, a validation failure) and continues, up to skipLimit. Exceed the limit and the job fails — that's a safety valve against silently dropping a corrupt file.
• Capture skips so they aren’t lost:

@Bean
public org.springframework.batch.core.SkipListener<CustomerCsv, Customer> skipListener() {
    return new org.springframework.batch.core.SkipListener<>() {
        @Override
        public void onSkipInRead(Throwable t) {
            // log/persist the unparseable line for later inspection
        }
        @Override
        public void onSkipInProcess(CustomerCsv item, Throwable t) {
            // record rejected item to a dead-letter table
        }
        @Override
        public void onSkipInWrite(Customer item, Throwable t) {
            // record write failure
        }
    };
}

Important caveat: when a fault-tolerant chunk hits an error during write, Spring Batch rolls back the chunk and re-processes it item by item to isolate the offender. This means your ItemProcessor must be idempotent — it may be called more than once for the same item.

Partitioning for scale

A single thread reading and writing in chunks is reliable but sequential. For millions of rows you want parallelism. Partitioning splits the input into ranges and runs a separate worker step per partition, each with its own reader/writer, in parallel across a thread pool.

import org.springframework.batch.core.partition.support.Partitioner;
import org.springframework.batch.item.ExecutionContext;
import java.util.HashMap;
import java.util.Map;

public class IdRangePartitioner implements Partitioner {

    private final long minId;
    private final long maxId;

    public IdRangePartitioner(long minId, long maxId) {
        this.minId = minId;
        this.maxId = maxId;
    }

    @Override
    public Map<String, ExecutionContext> partition(int gridSize) {
        Map<String, ExecutionContext> partitions = new HashMap<>();
        long range = (maxId - minId) / gridSize + 1;
        long start = minId;
        for (int i = 0; i < gridSize; i++) {
            ExecutionContext ctx = new ExecutionContext();
            long end = Math.min(start + range - 1, maxId);
            ctx.putLong("minId", start);
            ctx.putLong("maxId", end);
            partitions.put("partition" + i, ctx);
            start = end + 1;
        }
        return partitions;
    }
}

Wire a manager step that distributes partitions to a worker step running on a task executor:

@Bean
public Step partitionedStep(JobRepository jobRepository,
                            Step workerStep) {
    return new StepBuilder("partitionedStep", jobRepository)
        .partitioner(workerStep.getName(),
                     new IdRangePartitioner(1, 12_000_000))
        .step(workerStep)
        .gridSize(8)
        .taskExecutor(new org.springframework.core.task.SimpleAsyncTaskExecutor())
        .build();
}

The worker step’s reader uses the partition’s minId/maxId from the step ExecutionContext (inject via @Value("#{stepExecutionContext['minId']}") on a @StepScope bean). For a DB source, a JdbcPagingItemReader with a where id between :minId and :maxId clause keeps each partition's reads bounded and indexed.

Spring Batch also supports remote partitioning (workers on separate JVMs, coordinated via a message queue) for horizontal scale beyond one machine. Local partitioning across threads is the simplest big win.

Listeners and the ExecutionContext

Real jobs need hooks for logging, metrics, cleanup, and passing data between steps. Spring Batch provides listeners at every level.

import org.springframework.batch.core.JobExecution;
import org.springframework.batch.core.JobExecutionListener;

public class ImportJobListener implements JobExecutionListener {

    @Override
    public void beforeJob(JobExecution jobExecution) {
        // record start time, validate inputs, send a "started" notification
    }

    @Override
    public void afterJob(JobExecution jobExecution) {
        long written = jobExecution.getStepExecutions().stream()
            .mapToLong(se -> se.getWriteCount()).sum();
        long skipped = jobExecution.getStepExecutions().stream()
            .mapToLong(se -> se.getSkipCount()).sum();
        // emit metrics, alert if skipped is high, archive the input file
    }
}

Attach it with .listener(new ImportJobListener()) on the JobBuilder. There are matching StepExecutionListener, ChunkListener, and ItemReadListener interfaces for finer-grained hooks.

To pass data between steps — say, a step that computes an ID range and a later step that consumes it — write to the job ExecutionContext (shared across the job), not the step context (scoped to one step). The execution context is persisted by the JobRepository, so its contents also survive a restart, which is exactly what makes resumable multi-step jobs possible.

Composing multiple steps

Jobs rarely have one step. You might stage raw data, validate it, then load it. The JobBuilder flow API sequences and branches steps:

@Bean
public Job pipelineJob(JobRepository repo, Step stageStep,
                       Step validateStep, Step loadStep, Step cleanupStep) {
    return new JobBuilder("pipelineJob", repo)
        .start(stageStep)
        .next(validateStep)
        .on("FAILED").to(cleanupStep)          // branch on exit status
        .from(validateStep).on("*").to(loadStep)
        .end()
        .build();
}

If a step fails, the persisted state lets you restart the whole job and it resumes at the failed step — completed steps are skipped (unless marked allowStartIfComplete). This makes long ETL pipelines robust: a failure in the load step doesn't force you to re-stage gigabytes of data.

Tuning and monitoring

| Lever | Effect | Guidance |
|-------|--------|----------|
| Chunk size | Transaction frequency vs memory | Start 500–2,000; benchmark |
| Partition grid size | Parallelism | Match to CPU cores / DB connection pool |
| `JdbcBatchItemWriter` | Throughput | Faster than JPA for pure inserts |
| Connection pool size | Concurrency ceiling | Pool ≥ grid size + headroom |
| `default_batch_fetch_size` | Reader efficiency | Reduce N+1 if reader touches associations |

Monitor via the BATCH_STEP_EXECUTION table (read/write/skip/commit counts) or expose Micrometer metrics — Spring Batch publishes spring.batch.job and spring.batch.step timers automatically when Actuator is present.

Common pitfalls

• Loading everything into memory. Use streaming readers (FlatFileItemReader, JdbcCursorItemReader, JdbcPagingItemReader), never findAll() into a List.
• Non-idempotent processors. Fault-tolerant retries re-invoke process(). Side effects must be safe to repeat.
• Reusing identifying job parameters on a completed job. Causes JobInstanceAlreadyCompleteException. Add a unique parameter for genuinely new runs; keep them identical only when you intend to restart.
• Skipping silently. A high skipLimit with no SkipListener quietly discards data. Always record skipped items to a dead-letter store and alert on volume.
• Huge chunk inside a single transaction. A 100,000-item chunk holds locks and a giant transaction; a failure rolls back everything. Keep chunks modest.
• @EnableBatchProcessing in Boot 3. It disables the auto-configuration you actually want. Omit it unless customizing.
• spring.batch.job.enabled=true running jobs on every startup. Disable auto-run and launch explicitly so you control parameters and timing.
• Partitioning without enough DB connections. Eight parallel workers need eight connections; size the pool accordingly or workers will block.

Wrapping up

Spring Batch is not the flashiest part of the Spring ecosystem, but it’s one of the most valuable. It turns “read a file and insert rows” into a job that streams within bounded memory, commits in transactional chunks, resumes after failure, skips bad records into a dead-letter store, retries transient errors, and scales out across partitions.

Build with ItemReader → ItemProcessor → ItemWriter, choose a sane chunk size, make your processor idempotent, add fault tolerance deliberately, and partition when you need throughput. Your 12-million-row import becomes boring — which, for a batch job, is exactly what you want.

If this leveled up your batch game, follow the devdomain publication for more deep Spring engineering. What’s the largest job you’ve run, and how did you tune it? Share your numbers in the comments.

Spring Batch: Processing Millions of Records ReliablyIt always starts simple. was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hexagonal Architecture — Alistair Cockburn’s “Ports and Adapters” — is a direct answer to this decay. The core idea is almost embarrassingly simple: your business logic sits in the middle and depends on nothing. Everything else — the web, the database, the message broker — plugs into it through interfaces the business logic defines. The framework serves the domain, not the other way around.

This article is the practical version. We’ll cover the why, the three layers, what ports and adapters actually are, how to lay out a real Spring Boot 3.x project, which way the dependencies must point, why testing gets dramatically easier, and where the pattern hurts more than it helps.

The Problem with the Default Layered Architecture

The classic three-tier stack (Controller → Service → Repository) looks clean in a diagram, but the dependency arrows all point downward toward the database:

Controller  ->  Service  ->  Repository  ->  Database

Your domain logic (in the service) depends on the persistence layer. That means:

• Your business rules import org.springframework.data.jpa.* and jakarta.persistence.*.
• You can’t unit-test a service without mocking a repository that returns JPA-managed entities.
• Lazy-loading exceptions, detached entities, and transaction boundaries leak into business code.
• Changing infrastructure (a new database, a switch to Kafka) ripples upward into the domain.

Hexagonal architecture inverts this. The domain defines interfaces; infrastructure implements them. The arrows point inward.

The Core Principle: The Dependency Rule

There is exactly one rule that makes hexagonal architecture work:

Source code dependencies always point inward, toward the domain. The domain depends on nothing external.

The domain doesn’t know about Spring, Hibernate, Jackson, HTTP, or Kafka. It knows about its own interfaces. Infrastructure code depends on the domain, never the reverse.

+-------------------------------+
                  |      Inbound Adapters          |
                  |  (REST, CLI, Kafka consumer)   |
                  +---------------+---------------+
                                  |  calls
                                  v
   +------------------------------------------------------------+
   |                  APPLICATION LAYER                          |
   |   Use cases / input ports (interfaces)                      |
   |   Orchestration, transactions, no business invariants       |
   |                                                             |
   |   +------------------------------------------------+        |
   |   |               DOMAIN LAYER                      |        |
   |   |  Entities, Value Objects, Domain Services       |        |
   |   |  Pure Java. Business invariants. No framework.  |        |
   |   +------------------------------------------------+        |
   |                                                             |
   |   Output ports (interfaces): LoadOrderPort, SaveOrderPort   |
   +------------------------------------+------------------------+
                                        ^  implements
                                        |
                  +---------------------+-----------------+
                  |        Outbound Adapters               |
                  |  (JPA repo, REST client, Kafka prod.)  |
                  +----------------------------------------+

The Three Layers

1. Domain Layer — the pure core

This is the heart. Entities, value objects, and domain services that encode business rules. Zero framework dependencies. No @Entity, no @Component, no Lombok-on-JPA. Plain Java that you could compile without Spring on the classpath.

package com.shop.ordering.domain;

import java.util.List;
import java.util.UUID;

public class Order {

    private final OrderId id;
    private final CustomerId customerId;
    private final List<OrderLine> lines;
    private OrderStatus status;

    public Order(OrderId id, CustomerId customerId, List<OrderLine> lines) {
        if (lines == null || lines.isEmpty()) {
            throw new IllegalArgumentException("An order must have at least one line");
        }
        this.id = id;
        this.customerId = customerId;
        this.lines = List.copyOf(lines);
        this.status = OrderStatus.DRAFT;
    }

    public void place() {
        if (status != OrderStatus.DRAFT) {
            throw new IllegalStateException("Only draft orders can be placed");
        }
        this.status = OrderStatus.PLACED;
    }

    public Money total() {
        return lines.stream()
                .map(OrderLine::subtotal)
                .reduce(Money.ZERO, Money::add);
    }

    public OrderId id() { return id; }
    public OrderStatus status() { return status; }
}

Value objects are a natural fit for Java records:

package com.shop.ordering.domain;

import java.math.BigDecimal;

public record Money(BigDecimal amount, String currency) {

    public static final Money ZERO = new Money(BigDecimal.ZERO, "EUR");

    public Money {
        if (amount.signum() < 0) {
            throw new IllegalArgumentException("Money cannot be negative");
        }
    }

    public Money add(Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException("Currency mismatch");
        }
      2 return new Money(amount.add(other.amount), currency);
    }
}

Notice: this code is testable in microseconds, with no Spring context, no database, no mocks.

2. Application Layer — orchestration and ports

The application layer defines use cases as input ports (interfaces) and implements them in service classes. It orchestrates the domain, manages transactions, and talks to the outside world only through output ports — interfaces it owns.

Input port (driving side — what the app can do):

package com.shop.ordering.application.port.in;

public interface PlaceOrderUseCase {
    OrderId placeOrder(PlaceOrderCommand command);
}

Output ports (driven side — what the app needs):

package com.shop.ordering.application.port.out;

import com.shop.ordering.domain.Order;
import com.shop.ordering.domain.OrderId;
import java.util.Optional;

public interface LoadOrderPort {
    Optional<Order> load(OrderId id);
}

public interface SaveOrderPort {
    void save(Order order);
}

Application service — the only place Spring lightly touches the core (it’s fine for @Service/@Transactional to live here; this layer is allowed to know about orchestration concerns):

package com.shop.ordering.application.service;

import com.shop.ordering.application.port.in.*;
import com.shop.ordering.application.port.out.*;
import com.shop.ordering.domain.*;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class PlaceOrderService implements PlaceOrderUseCase {

    private final SaveOrderPort saveOrderPort;
    private final LoadCustomerPort loadCustomerPort;

    public PlaceOrderService(SaveOrderPort saveOrderPort, LoadCustomerPort loadCustomerPort) {
        this.saveOrderPort = saveOrderPort;
        this.loadCustomerPort = loadCustomerPort;
    }

    @Override
    @Transactional
    public OrderId placeOrder(PlaceOrderCommand command) {
        Customer customer = loadCustomerPort.load(command.customerId())
                .orElseThrow(() -> new CustomerNotFoundException(command.customerId()));

        Order order = new Order(OrderId.newId(), customer.id(), command.toLines());
        customer.assertCanPlaceOrder(order);   // domain invariant
        order.place();

        saveOrderPort.save(order);
        return order.id();
    }
}

A purist note: some teams keep @Service/@Transactional out of the application service too, declaring beans via @Configuration and managing transactions in the adapter. That's more decoupled but more ceremony. For most teams, allowing Spring stereotypes in the application layer (but never the domain layer) is a pragmatic, defensible line.

3. Infrastructure Layer — adapters

Adapters are the concrete glue. There are two kinds:

• Inbound (driving) adapters call input ports. REST controllers, message consumers, CLI handlers, scheduled jobs.
• Outbound (driven) adapters implement output ports. JPA repositories, HTTP clients, Kafka producers.

Inbound REST adapter:

package com.shop.ordering.infrastructure.web;

import com.shop.ordering.application.port.in.*;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/orders")
class OrderController {

    private final PlaceOrderUseCase placeOrderUseCase;

    OrderController(PlaceOrderUseCase placeOrderUseCase) {
        this.placeOrderUseCase = placeOrderUseCase;
    }

    @PostMapping
    ResponseEntity<PlaceOrderResponse> place(@RequestBody PlaceOrderRequest request) {
        OrderId id = placeOrderUseCase.placeOrder(request.toCommand());
        return ResponseEntity
                .created(URI.create("/api/orders/" + id.value()))
                .body(new PlaceOrderResponse(id.value()));
    }
}

The controller depends on the use case interface, not the service implementation. The PlaceOrderRequest/PlaceOrderResponse are web DTOs that never leak into the domain — the mapping happens at the boundary.

Outbound JPA adapter — this is where the JPA entity lives, and it is not the domain Order:

package com.shop.ordering.infrastructure.persistence;

import com.shop.ordering.application.port.out.*;
import com.shop.ordering.domain.*;
import org.springframework.stereotype.Component;

@Component
class OrderPersistenceAdapter implements SaveOrderPort, LoadOrderPort {

    private final OrderJpaRepository repository;
    private final OrderMapper mapper;

    OrderPersistenceAdapter(OrderJpaRepository repository, OrderMapper mapper) {
        this.repository = repository;
        this.mapper = mapper;
    }

    @Override
    public void save(Order order) {
        repository.save(mapper.toJpaEntity(order));
    }

    @Override
    public Optional<Order> load(OrderId id) {
        return repository.findById(id.value()).map(mapper::toDomain);
    }
}

@Entity
@Table(name = "orders")
class OrderJpaEntity {
    @Id private UUID id;
    private UUID customerId;
    @Enumerated(EnumType.STRING) private String status;
    @OneToMany(cascade = CascadeType.ALL, mappedBy = "order")
    private List<OrderLineJpaEntity> lines;
    // getters/setters, no-arg constructor for Hibernate
}

interface OrderJpaRepository extends JpaRepository<OrderJpaEntity, UUID> {}

The mapper translates between the persistence model and the domain model. Yes, this is more code. The payoff: Hibernate’s lazy-loading, dirty-checking, and cascade semantics never touch your business rules.

Recommended Project Structure

Organize by feature first, then by layer. This keeps a bounded context’s code together and makes the dependency direction visible in the package tree.

com.shop.ordering
├── domain                 // pure business model
│   ├── Order.java
│   ├── OrderLine.java
│   ├── Money.java
│   └── OrderStatus.java
├── application
│   ├── port
│   │   ├── in             // input ports (use cases)
│   │   │   ├── PlaceOrderUseCase.java
│   │   │   └── PlaceOrderCommand.java
│   │   └── out            // output ports
│   │       ├── SaveOrderPort.java
│   │       └── LoadOrderPort.java
│   └── service
│       └── PlaceOrderService.java
└── infrastructure
    ├── web                // inbound adapter
    │   ├── OrderController.java
    │   └── PlaceOrderRequest.java
    └── persistence        // outbound adapter
        ├── OrderPersistenceAdapter.java
        ├── OrderJpaEntity.java
        ├── OrderJpaRepository.java
        └── OrderMapper.java

You can enforce the dependency rule with ArchUnit so it doesn’t erode:

@AnalyzeClasses(packages = "com.shop.ordering")
class ArchitectureTest {

    @ArchTest
    static final ArchRule domain_depends_on_nothing =
        noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("..application..", "..infrastructure..",
                                "org.springframework..", "jakarta.persistence..");
}

Why Dependency Direction Is the Whole Point

The magic that makes the database depend on the domain (and not vice versa) is dependency inversion. The application layer declares SaveOrderPort. The persistence adapter implements it. At compile time, the adapter package imports the application package; the application package imports nothing from the adapter. Spring's IoC container wires the implementation in at runtime.

| Concern | Classic layered | Hexagonal |
|---|---|---|
| Domain knows about DB | Yes (JPA entity = domain) | No |
| Swap Postgres → Mongo | Touches services + entities | New adapter only |
| Unit-test business rule | Needs DB or mock repo | Plain JUnit, no Spring |
| Framework lock-in | High | Isolated to adapters |
| Onboarding clarity | "Where's the rule?" | Always in domain |
| Initial boilerplate | Low | Higher (mappers, ports) |

Testing Benefits — the Real Payoff

This is where hexagonal earns its keep.

Domain tests are pure, fast, framework-free:

@Test
void placing_a_draft_order_marks_it_placed() {
    Order order = new Order(OrderId.newId(), CustomerId.newId(),
            List.of(new OrderLine("SKU-1", 2, new Money(BigDecimal.TEN, "EUR"))));

    order.place();

    assertThat(order.status()).isEqualTo(OrderStatus.PLACED);
}

Application/use-case tests use trivial in-memory fakes of the output ports — no Mockito ceremony, no database:

@Test
void placing_order_persists_it() {
    var saveAdapter = new InMemoryOrderStore();          // implements SaveOrderPort
    var customers   = new InMemoryCustomerStore(existing); // implements LoadCustomerPort
    var service     = new PlaceOrderService(saveAdapter, customers);

    OrderId id = service.placeOrder(validCommand());

    assertThat(saveAdapter.find(id)).isPresent();
}

Adapter tests are integration tests scoped to the boundary: @DataJpaTest with Testcontainers for the persistence adapter, @WebMvcTest for the controller. Each test layer has a clear, narrow target. You stop spinning up the full Spring context just to verify a calculation.

When NOT to Use Hexagonal Architecture

Hexagonal is not free, and treating it as a default for everything is a mistake.

• CRUD-heavy apps with no real domain. If your “business logic” is save and findAll, the ports, adapters, and mappers are pure overhead. A thin Controller → JpaRepository stack is honest and faster to ship.
• Small or short-lived services. A throwaway internal tool or a prototype doesn’t need this rigor.
• Tiny teams under deadline pressure who won’t maintain the discipline — half-applied hexagonal (some ports, some direct JPA leakage) is worse than consistent simplicity.

The pattern shines when there are rich business rules, long expected lifespan, multiple integrations, and a need to test logic in isolation. Order management, pricing, billing, fraud, lending — yes. A reference-data lookup service — probably not.

Common Pitfalls

• The anemic domain. If Order is just getters/setters and all logic lives in PlaceOrderService, you've built layered architecture with extra steps. Push invariants into the entities.
• Letting JPA entities be the domain model. The single most common shortcut, and it quietly couples your core to Hibernate. Keep the mapper.
• Leaky DTOs. Don’t let @RequestBody Jackson objects or JPA entities cross into the domain. Map at the boundary, every time.
• Over-porting. You don’t need a port for every method. Group cohesive operations; a use case can be a single-method interface, and an output port can cover a small set of related operations.
• Putting business logic in adapters. A REST controller deciding “if status is X, do Y” is a smell. The decision belongs in the domain or application service.
• Ports owned by the wrong side. Output ports must be defined in the application layer (the consumer), not in the infrastructure layer. If the adapter defines the interface, you’ve lost dependency inversion.

A Concrete End-to-End Flow

Putting it together, a “place order” request flows like this:

HTTP POST /api/orders
   -> OrderController            (inbound adapter, maps JSON -> command)
   -> PlaceOrderUseCase          (input port)
   -> PlaceOrderService          (application: orchestrates, @Transactional)
        -> loadCustomerPort.load (output port -> JPA adapter -> DB)
        -> new Order(...)        (domain: enforces invariants)
        -> order.place()         (domain: state transition)
        -> saveOrderPort.save    (output port -> JPA adapter -> DB)
   <- OrderId
   <- 201 Created

At no point does the domain import Spring, JPA, or HTTP. The framework lives entirely at the edges. That’s the whole game: a core you can reason about, test, and evolve without the infrastructure dictating terms.

Closing Thoughts

Hexagonal architecture is a discipline, not a library. Spring Boot makes it pleasant — constructor injection wires your ports to adapters with almost no ceremony — but the value comes from the boundaries you enforce: a pure domain, ports owned by the application, adapters that translate at the edge. Done well, you get business logic that reads like the business, tests that run in milliseconds, and infrastructure you can replace without fear. Done as cargo-cult ceremony on a CRUD app, you get mappers nobody asked for. Choose deliberately.

If this was useful, follow devdomain for more deep-dives on architecture, Java, and Spring. What’s your take — do you keep @Transactional in the application service or push it to the adapter? Drop a comment, I read all of them.

Hexagonal Architecture (Ports and Adapters) in Spring BootMost Spring Boot codebases rot in the… was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

Actuator gives you a set of production-ready HTTP (and JMX) endpoints — health, metrics, environment, thread dumps, and more — plus deep integration with Micrometer, a vendor-neutral metrics facade. Pair that with a Prometheus scrape endpoint and you have a stack that powers dashboards, alerting, and Kubernetes probes without writing a custom monitoring framework.

This article walks the full path: enabling Actuator safely, designing health/liveness/readiness probes, instrumenting your own metrics with Micrometer, exposing them to Prometheus, writing custom health indicators, and — critically — locking the whole thing down so you don’t accidentally publish your config to the internet.

Getting Actuator on the classpath

Two dependencies do most of the work. Actuator itself, and the Micrometer Prometheus registry.

<!-- pom.xml -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
    <scope>runtime</scope>
</dependency>

With just these on the classpath, Actuator auto-configures its endpoints, and the presence of the Prometheus registry auto-configures a /actuator/prometheus endpoint that emits metrics in Prometheus exposition format. You write zero glue code.

Endpoints: what’s exposed and what isn’t

Actuator ships dozens of endpoints. By default, over HTTP, only health is exposed. Everything else is registered but not reachable over the web until you opt in. This default is deliberate — endpoints like env, heapdump, and threaddump leak sensitive information.

You control exposure with two property families:

# application.properties

# Which endpoints are enabled (default: all enabled except shutdown)
management.endpoint.shutdown.enabled=false

# Which enabled endpoints are exposed over HTTP
management.endpoints.web.exposure.include=health,info,metrics,prometheus,loggers
# Or explicitly hide some even if included
management.endpoints.web.exposure.exclude=env,beans

A frequent source of confusion: enabled and exposed are different switches. An endpoint must be enabled (it exists as a bean) and exposed (reachable over the chosen technology, web or JMX). Disabling beats exposing — a disabled endpoint cannot be exposed.

Here are the endpoints you’ll touch most:

Endpoint Path Purpose Safe to expose publicly? health /actuator/health Liveness/readiness, dependency status Yes (with show-details care) info /actuator/info Build/git/app metadata Usually metrics /actuator/metrics Browse individual meters No prometheus /actuator/prometheus Scrape target for Prometheus No (internal network only) loggers /actuator/loggers View/change log levels at runtime No env /actuator/env Full environment + properties Never threaddump /actuator/threaddump JVM thread dump No heapdump /actuator/heapdump Downloads a heap dump Never

Moving Actuator to its own port

A common production pattern is to serve management endpoints on a separate port that is only reachable inside the cluster, never via the public ingress:

management.server.port=8081
management.server.address=127.0.0.1

Now your app serves business traffic on 8080 and Actuator on 8081, which you bind to localhost or an internal interface and never route externally.

Health, liveness, and readiness

/actuator/health aggregates the status of every HealthIndicator on the classpath. Spring Boot auto-configures many: db, diskSpace, redis, mongo, rabbit, and so on. The aggregate status is the worst of its parts — one DOWN indicator makes the whole endpoint report DOWN and return HTTP 503.

{
  "status": "UP",
  "components": {
    "db": { "status": "UP", "details": { "database": "PostgreSQL" } },
    "diskSpace": { "status": "UP" }
  }
}

By default, health shows only the top-level status. To see component details — extremely useful for debugging — set:

# never | when-authorized | always
management.endpoint.health.show-details=when-authorized
management.endpoint.health.show-components=when-authorized

when-authorized shows full details only to authenticated users with the right role, which is the sane production setting. always is fine on an internal-only management port.

Liveness vs readiness probes

Kubernetes asks two different questions, and conflating them causes cascading restarts:

• Liveness: “Is this process broken beyond recovery?” If it fails, the orchestrator kills and restarts the pod.
• Readiness: “Can this instance serve traffic right now?” If it fails, the orchestrator removes it from the load balancer but lets it keep running.

A database outage should fail readiness (stop sending traffic until the DB recovers), not liveness (don’t restart the pod — that won’t fix the database). Getting this wrong turns a transient dependency blip into a restart storm.

Spring Boot has first-class support. Enable the probes:

management.endpoint.health.probes.enabled=true
management.health.livenessstate.enabled=true
management.health.readinessstate.enabled=true

This exposes /actuator/health/liveness and /actuator/health/readiness. Your Kubernetes manifest then points at them:

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8081
  initialDelaySeconds: 10
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8081
  periodSeconds: 5

You can drive these states programmatically. For example, when a background warm-up finishes, mark the app ready; if an unrecoverable state is detected, mark it broken:

import org.springframework.boot.availability.AvailabilityChangeEvent;
import org.springframework.boot.availability.LivenessState;
import org.springframework.boot.availability.ReadinessState;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Component;

@Component
public class WarmupSignaller {

    private final ApplicationEventPublisher publisher;

    public WarmupSignaller(ApplicationEventPublisher publisher) {
        this.publisher = publisher;
    }

    public void warmupComplete() {
        AvailabilityChangeEvent.publish(publisher, this, ReadinessState.ACCEPTING_TRAFFIC);
    }

    public void fatalError() {
        AvailabilityChangeEvent.publish(publisher, this, LivenessState.BROKEN);
    }
}

Writing a custom health indicator

The built-in indicators cover infrastructure, but you’ll often need to express business health — “can we reach the payment gateway?” Implement HealthIndicator (or the reactive ReactiveHealthIndicator):

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;

@Component
public class PaymentGatewayHealthIndicator implements HealthIndicator {

    private final RestClient restClient;

    public PaymentGatewayHealthIndicator(RestClient.Builder builder) {
        this.restClient = builder.baseUrl("https://payments.example.com").build();
    }

    @Override
    public Health health() {
        try {
            long start = System.nanoTime();
            restClient.get().uri("/ping").retrieve().toBodilessEntity();
            long ms = (System.nanoTime() - start) / 1_000_000;
            return Health.up()
                    .withDetail("latencyMs", ms)
                    .build();
        } catch (Exception ex) {
            return Health.down(ex)
                    .withDetail("hint", "payment gateway unreachable")
                    .build();
        }
    }
}

The bean name (paymentGateway, derived from the class minus the HealthIndicator suffix) becomes the component key in the health response.

Don’t let one indicator sink readiness blindly

By default a custom HealthIndicator is grouped into the overall health but not into the readiness group. If a non-critical dependency being down shouldn't pull you out of the load balancer, keep it out of readiness. If it should, add it explicitly to a health group:

management.endpoint.health.group.readiness.include=readinessState,db,paymentGateway
management.endpoint.health.group.liveness.include=livenessState

Health groups let you compose exactly which indicators contribute to which probe. This is one of the most underused, highest-leverage Actuator features.

Micrometer: the metrics facade

Micrometer is to metrics what SLF4J is to logging — a vendor-neutral API with pluggable backends (Prometheus, Datadog, CloudWatch, OTLP, and more). You instrument against Micrometer’s MeterRegistry; the registry on the classpath decides the wire format.

The four meter types you’ll use:

• Counter — monotonically increasing count (requests served, errors).
• Gauge — an instantaneous value that can go up or down (queue depth, cache size).
• Timer — count + total time + max of short-duration events (request latency).
• DistributionSummary — like a timer but for non-time values (payload sizes).

Counters and timers

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.stereotype.Service;

@Service
public class OrderService {

    private final Counter ordersPlaced;
    private final Timer checkoutTimer;

    public OrderService(MeterRegistry registry) {
        this.ordersPlaced = Counter.builder("orders.placed")
                .description("Total orders successfully placed")
                .tag("channel", "web")
                .register(registry);
        this.checkoutTimer = Timer.builder("orders.checkout.duration")
                .description("Time to complete checkout")
                .publishPercentiles(0.5, 0.95, 0.99)
                .register(registry);
    }

    public Order checkout(Cart cart) {
        return checkoutTimer.record(() -> {
            Order order = process(cart);
            ordersPlaced.increment();
            return order;
        });
    }

    private Order process(Cart cart) { /* ... */ return new Order(); }
}

publishPercentiles computes client-side percentiles. If you want aggregatable percentiles across instances, use publishPercentileHistogram() instead, which emits histogram buckets that Prometheus can aggregate with histogram_quantile(). Client-side percentiles cannot be averaged across pods; histogram buckets can.

Gauges

Gauges observe a value via a function. Hold a strong reference to the object you’re measuring — Micrometer keeps only a weak reference, and if your object is garbage collected the gauge reports NaN.

import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import java.util.concurrent.BlockingQueue;

public class QueueMetrics {
    public QueueMetrics(MeterRegistry registry, BlockingQueue<?> queue) {
        Gauge.builder("worker.queue.depth", queue, BlockingQueue::size)
             .description("Pending work items")
             .register(registry);
    }
}

Annotation-based timing

For method-level timing without boilerplate, use @Timed. It requires a TimedAspect bean:

import io.micrometer.core.aop.TimedAspect;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MetricsConfig {
    @Bean
    TimedAspect timedAspect(MeterRegistry registry) {
        return new TimedAspect(registry);
    }
}

import io.micrometer.core.annotation.Timed;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ReportController {

    @Timed(value = "reports.generate", percentiles = {0.95, 0.99})
    @GetMapping("/reports/monthly")
    public Report monthly() { /* ... */ return new Report(); }
}

Tags, cardinality, and the trap that kills Prometheus

Tags (Prometheus calls them labels) are dimensions you slice metrics by — status, endpoint, region. Every unique combination of tag values creates a new time series. High-cardinality tags are the single most common way teams blow up their metrics backend.

Never use unbounded values as tags: user IDs, order IDs, full URLs with path variables, email addresses, request bodies. A counter tagged with userId becomes millions of time series and will OOM your Prometheus.

// BAD: cardinality explosion
Counter.builder("api.calls").tag("userId", userId).register(registry);

// GOOD: bounded set of values
Counter.builder("api.calls").tag("plan", user.plan().name()).register(registry);

Spring already templatizes HTTP metrics — /orders/42 and /orders/99 both report under uri="/orders/{id}", keeping cardinality bounded.

Common tags for every metric

Stamp every metric with environment metadata so dashboards can filter across services. Use a MeterRegistryCustomizer:

import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.boot.actuate.autoconfigure.metrics.MeterRegistryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CommonSagsConfig {
    @Bean
    MeterRegistryCustomizer<MeterRegistry> commonTags(
            @org.springframework.beans.factory.annotation.Value("${spring.application.name}") String app) {
        return registry -> registry.config().commonTags(
                "application", app,
                "region", System.getenv().getOrDefault("REGION", "local"));
    }
}

Exposing to Prometheus

With the registry on the classpath and prometheus exposed, scraping is just configuration on the Prometheus side:

# prometheus.yml
scrape_configs:
  - job_name: "orders-service"
    metrics_path: /actuator/prometheus
    scrape_interval: 15s
    static_configs:
      - targets: ["orders-service:8081"]

A sample of the exposition output:

# HELP orders_placed_total Total orders successfully placed
# TYPE orders_placed_total counter
orders_placed_total{application="orders",channel="web",region="eu"} 4821.0

# HELP orders_checkout_duration_seconds
# TYPE orders_checkout_duration_seconds summary
orders_checkout_duration_seconds{quantile="0.95"} 0.182
orders_checkout_duration_seconds_count 4821.0
orders_checkout_duration_seconds_sum 712.4

Spring Boot app                Prometheus               Grafana
 ┌────────────────┐   scrape    ┌────────────┐  query   ┌──────────┐
 │ /actuator/     │ <────────── │ TSDB       │ <─────── │ dashboards│
 │   prometheus   │   15s pull  │ + alerting │  PromQL  │ + alerts  │
 └────────────────┘             └────────────┘          └──────────┘

Note the pull model: Prometheus scrapes you. Your app does not push. This means a dead app simply stops appearing — Prometheus’s up metric goes to 0, which you alert on.

Securing Actuator with Spring Security

If Spring Security is on the classpath, you must explicitly authorize Actuator endpoints or they’ll be locked behind your default rules. Use EndpointRequest matchers rather than hardcoding paths — they respect a custom management.endpoints.web.base-path:

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.boot.actuate.health.HealthEndpoint;
import org.springframework.boot.actuate.info.InfoEndpoint;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(EndpointRequest.to(HealthEndpoint.class, InfoEndpoint.class)).permitAll()
                .anyRequest().hasRole("ACTUATOR_ADMIN"))
            .httpBasic(org.springframework.security.config.Customizer.withDefaults());
        return http.build();
    }
}

This permits health and info for everyone (probes need them) while requiring the ACTUATOR_ADMIN role for everything else. Combine with show-details=when-authorized and full health details appear only to admins.

The info endpoint and build metadata

Wire build and git info into /actuator/info so you can verify exactly which commit is running:

management.info.env.enabled=true
management.info.git.mode=full
info.app.team=payments

Add the Spring Boot Maven plugin’s build-info goal and the git-commit-id-maven-plugin, and /actuator/info will report version, build time, and commit hash — invaluable during incident triage.

Common pitfalls

• Exposing everything. management.endpoints.web.exposure.include=* plus no security plus a public ingress is a data breach. Always scope exposure and bind management to an internal port.
• Liveness/readiness confusion. Failing liveness on a DB outage restarts healthy pods. Map dependency failures to readiness.
• Cardinality explosions. Tagging metrics with IDs, raw URIs, or user data. Keep tag value sets small and bounded.
• Weakly-referenced gauges. Forgetting to hold a reference to the gauged object; it gets GC’d and reports NaN.
• Client-side percentiles you try to average. Use publishPercentileHistogram() when you need cross-instance percentiles via histogram_quantile().
• show-details=always in public deployments. Leaks dependency topology, JDBC URLs, and validation messages.
• Forgetting the TimedAspect bean. @Timed silently does nothing without it.
• Slow custom health indicators. Probes run frequently; a 5-second gateway check on every scrape can hammer a dependency. Add timeouts and consider caching.

Wrapping up

Actuator plus Micrometer plus Prometheus is the default observability stack for Spring Boot for good reason: a couple of dependencies give you health probes that Kubernetes understands, a metrics facade that doesn’t lock you to a vendor, and a scrape endpoint that drops straight into Prometheus and Grafana. The work that remains is design work — choosing the right probes, instrumenting the metrics that matter, keeping cardinality sane, and locking the endpoints down. Do that, and your service stops being a black box.

If this helped, follow devdomain for more deep Spring dives, and drop a comment with the metrics you wish Spring exposed out of the box — I read every one.

Spring Boot Actuator: Production-Grade Observability with Micrometer and PrometheusThe moment your… was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

This is the lost update problem, and it’s the reason concurrency control exists. JPA gives you two strategies to deal with it: optimistic locking, which assumes conflicts are rare and detects them after the fact, and pessimistic locking, which assumes conflicts are likely and prevents them up front by locking rows in the database. Picking the wrong one — or worse, neither — leads to corrupted data, deadlocks, or throughput that falls off a cliff.

Let’s go deep on both, with real Spring Boot 3.x code, retry logic, and the trade-offs that actually matter in production.

The lost update, demonstrated

Without locking, two concurrent transactions read the same row, each modifies it, and the second commit silently overwrites the first.

T1: read account(balance=100)
T2: read account(balance=100)
T1: balance = 100 - 30  -> write 70
T2: balance = 100 - 50  -> write 50   <-- T1's withdrawal is gone

The final balance is 50, but two withdrawals totaling 80 happened. The database is internally consistent and completely wrong. Neither READ COMMITTED nor even REPEATABLE READ saves you here in the general case — you need an explicit locking strategy.

Optimistic locking with @Version

Optimistic locking adds a version column. Every update increments it, and every update is guarded by a WHERE version = ? clause. If someone changed the row since you read it, the version no longer matches, zero rows update, and JPA throws.

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Version;

@Entity
public class Account {

    @Id
    private Long id;

    private java.math.BigDecimal balance;

    @Version
    private long version; // managed entirely by JPA — never set it yourself

    // getters/setters
}

When you load this account at version 7 and modify it, Hibernate generates:

UPDATE account SET balance = ?, version = 8 WHERE id = ? AND version = 7

If another transaction already bumped it to 8, the WHERE matches nothing, Hibernate sees rowcount = 0, and throws OptimisticLockException (Spring wraps it as ObjectOptimisticLockingFailureException).

The @Version field can be a long/int/Integer/Long, a short, or a java.time.Instant/Timestamp. Prefer a numeric version — timestamps have clock-resolution problems and can collide under high concurrency.

Handling the conflict: retry

An OptimisticLockException isn't a bug, it's information: "someone beat you to it." The correct response is usually to re-read and retry. Spring Retry makes this clean:

import org.springframework.dao.OptimisticLockingFailureException;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class AccountService {

    private final AccountRepository repo;

    public AccountService(AccountRepository repo) {
        this.repo = repo;
    }

    @Retryable(
        retryFor = OptimisticLockingFailureException.class,
        maxAttempts = 4,
        backoff = @Backoff(delay = 50, multiplier = 2.0))
    @Transactional
    public void withdraw(Long id, java.math.BigDecimal amount) {
        Account a = repo.findById(id).orElseThrow();
        if (a.getBalance().compareTo(amount) < 0) {
            throw new InsufficientFundsException(id);
        }
        a.setBalance(a.getBalance().subtract(amount));
        // dirty checking flushes the versioned UPDATE at commit
    }
}

Critical detail: the retry must start a fresh transaction and re-read the entity. @Retryable on a method whose @Transactional boundary is the method itself works because each attempt is a new method invocation → new transaction → fresh persistence context. If you retry inside one transaction with a stale entity, you'll just fail again forever.

Note on proxies: @Retryable and @Transactional are AOP proxies. Calling withdraw from within the same bean bypasses the proxy. Call across beans, or self-inject the proxy.

Forcing a version bump on a parent

Sometimes you modify a child entity but want to detect concurrent changes against the parent aggregate (classic DDD aggregate-root protection). Use an explicit lock mode:

import jakarta.persistence.LockModeType;

@Transactional
public void addLineItem(Long orderId, LineItem item) {
    Order order = em.find(Order.class, orderId,
            LockModeType.OPTIMISTIC_FORCE_INCREMENT);
    order.getItems().add(item);
    // Order.version is incremented even though only the collection changed.
}

OPTIMISTIC checks the version at flush; OPTIMISTIC_FORCE_INCREMENT always bumps it, serializing logical changes to the aggregate.

Pessimistic locking

Pessimistic locking takes the opposite bet: conflicts are likely, so lock the row in the database before reading it. Other transactions that want the same lock block (or fail fast) until you commit. This is SELECT ... FOR UPDATE territory.

import jakarta.persistence.LockModeType;
import org.springframework.data.jpa.repository.Lock;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

public interface AccountRepository extends JpaRepository<Account, Long> {

    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("select a from Account a where a.id = :id")
    Optional<Account> findByIdForUpdate(@Param("id") Long id);
}

@Transactional
public void transfer(Long from, Long to, java.math.BigDecimal amount) {
    // Lock both rows up front. Other transfers touching these accounts block.
    Account src = repo.findByIdForUpdate(from).orElseThrow();
    Account dst = repo.findByIdForUpdate(to).orElseThrow();

    src.setBalance(src.getBalance().subtract(amount));
    dst.setBalance(dst.getBalance().add(amount));
}

Hibernate emits SELECT ... FOR UPDATE, holding row locks until the transaction commits. No other transaction can modify (or, depending on mode, read-for-update) those rows in the meantime — the lost update is impossible by construction.

Pessimistic lock modes

LockModeType SQL Semantics PESSIMISTIC_READ SELECT ... FOR SHARE (DB-dependent) Shared lock: others can read but not write PESSIMISTIC_WRITE SELECT ... FOR UPDATE Exclusive lock: others cannot read-for-update or write PESSIMISTIC_FORCE_INCREMENT FOR UPDATE + version bump Exclusive lock and increments @Version

PESSIMISTIC_WRITE is what you reach for 95% of the time. PESSIMISTIC_READ is rarely supported cleanly across databases (many map it to the same exclusive lock).

Lock timeouts: don’t block forever

A blocked transaction holding connections is a recipe for thread-pool exhaustion. Bound the wait:

import jakarta.persistence.LockModeType;
import jakarta.persistence.Map;
import org.hibernate.LockOptions;

java.util.Map<String, Object> hints = new java.util.HashMap<>();
hints.put("jakarta.persistence.lock.timeout", 3000); // milliseconds

Account a = em.find(Account.class, id, LockModeType.PESSIMISTIC_WRITE, hints);

If the lock can’t be acquired within the timeout, you get LockTimeoutException (or PessimisticLockException) instead of hanging. Support varies by database; PostgreSQL honors it via lock_timeout, and you can also use NOWAIT/SKIP LOCKED semantics through provider hints for queue-style workloads.

Deadlocks

Pessimistic locking introduces a hazard optimistic locking doesn’t: deadlocks. Two transactions each hold a lock the other wants.

T1: lock account A      T2: lock account B
T1: wants account B     T2: wants account A   --> deadlock

The database detects this and kills one transaction (DeadlockLoserDataAccessException in Spring). Two defenses:

1. Always acquire locks in a consistent order. In the transfer above, lock accounts sorted by ID, never in the arbitrary from→to order:

@Transactional
public void transfer(Long from, Long to, java.math.BigDecimal amount) {
    Long first = Math.min(from, to);
    Long second = Math.max(from, to);
    Account a1 = repo.findByIdForUpdate(first).orElseThrow();
    Account a2 = repo.findByIdForUpdate(second).orElseThrow();
    // ... resolve which is source/dest, then update
}

1. Retry on deadlock, exactly like optimistic conflicts, since a deadlock victim’s transaction is rolled back and can safely re-run.

Where the version check actually happens

A subtle but important point: with plain @Version, Hibernate only checks the version on entities it dirties. If you load an entity, read it, and never modify it, no UPDATE is generated and no version check occurs — Hibernate had nothing to flush. That's usually fine, but it means "I read it, so I'm protected against concurrent changes" is false. Reading is not locking.

If you genuinely need to assert “nothing changed under me” even on a read-only access, request an explicit optimistic lock:

Account a = em.find(Account.class, id, LockModeType.OPTIMISTIC);
// At flush, Hibernate verifies a.version still matches the DB,
// even though you only read the entity.

LockModeType.OPTIMISTIC schedules a SELECT ... WHERE version = ? check at flush time. If the row's version moved, you get an OptimisticLockException even though you never wrote to the entity. This matters for read-then-decide flows where the decision must be based on data that's still current at commit.

Optimistic locking across detached entities

The reason optimistic locking fits stateless web applications is that the version travels with the data. When you serialize an entity (or a DTO carrying its version) to a client, edit it over minutes, and post it back, the version comes along. On merge, Hibernate compares the incoming version against the database:

@Transactional
public Order saveEdited(OrderDto dto) {
    Order order = new Order();
    order.setId(dto.id());
    order.setVersion(dto.version()); // the version the client started from
    order.setShippingAddress(dto.address());

    // merge compares dto.version() against the current DB row.
    // If someone else saved in the meantime, OptimisticLockException.
    return repo.save(order); // save() -> merge() for a detached entity
}

This is impossible with pessimistic locking — a database row lock cannot survive across HTTP requests, because it dies with the transaction that took it. Any “lock while the user edits” requirement must be solved with optimistic versioning (or an application-level lease), never with FOR UPDATE.

Choosing between them

Dimension Optimistic Pessimistic Assumption Conflicts rare Conflicts common When detected At flush/commit At read DB cost None until commit Holds row locks for the txn Scalability High (no blocking) Lower (blocking, lock contention) Failure mode OptimisticLockException → retry Blocking, timeout, deadlock Cross-request safe Yes (version stored) No (locks die with the txn) Best for Web apps, REST, long think-time Short hot-row transactions, queues

Default to optimistic. It scales, it doesn’t hold database locks, and it works across stateless HTTP requests (a user can sit on an edit form for 10 minutes; the version travels in the payload and the conflict is caught on submit). Reach for pessimistic locking only when:

• Contention on the same rows is genuinely high and retries would storm.
• The work is short and inside a single transaction (you can’t hold a DB lock across user think-time anyway).
• You’re implementing a job queue and want FOR UPDATE SKIP LOCKED to hand out distinct rows to workers.

A useful hybrid: keep @Version on every entity as a cheap safety net, and add pessimistic locks only on the specific hot paths that need them.

Queue patterns: SKIP LOCKED

A specialized but increasingly common use of pessimistic locking is building a job queue directly on a relational table. Multiple workers poll the same table, and you want each worker to grab a different unclaimed row without blocking on its peers. Plain FOR UPDATE would make workers queue behind each other; FOR UPDATE SKIP LOCKED tells the database to skip rows another transaction already locked and return the next available ones.

@Query(value = """
        SELECT * FROM job
        WHERE status = 'PENDING'
        ORDER BY created_at
        LIMIT :batch
        FOR UPDATE SKIP LOCKED
        """, nativeQuery = true)
List<Job> claimBatch(@Param("batch") int batch);

@Transactional
public void process() {
    List<Job> jobs = repo.claimBatch(10); // each worker gets distinct rows
    for (Job j : jobs) {
        j.setStatus("RUNNING");
        // ... do the work; commit releases the locks and persists status
    }
}

SKIP LOCKED is supported by PostgreSQL, MySQL 8+, and Oracle. It gives you concurrent, contention-free work distribution without a dedicated message broker for modest volumes — a genuinely useful pattern that's pure pessimistic locking applied well. The trade-off is that you're now running a queue on your primary database; once throughput grows, a purpose-built broker is the better tool.

Common pitfalls

• Setting the @Version field manually. It's owned by the provider. Touching it breaks the optimism check. Treat it as read-only.
• Retrying without re-reading. Catching OptimisticLockException and retrying with the same stale, detached entity fails forever. Each retry needs a new transaction and a fresh load.
• Self-invocation defeating @Retryable/@Transactional. Calling the annotated method from the same class bypasses the Spring proxy — no retry, no transaction. Call across beans.
• Holding pessimistic locks across user interaction. A FOR UPDATE lock lives only inside one transaction. You cannot lock a row while a user fills out a form. Use optimistic locking for that.
• Ignoring lock ordering → deadlocks. Any code path that locks more than one row must lock in a deterministic global order.
• No lock timeout. Unbounded FOR UPDATE waits exhaust the connection pool under load. Always set jakarta.persistence.lock.timeout.
• Assuming PESSIMISTIC_READ is portable. Many databases promote it to an exclusive lock. Test against your actual DB.
• Optimistic version not propagated to the client. For stateless edit flows the version must round-trip to the browser and back; otherwise you can’t detect the conflict you designed for.
• Catching the wrong exception. Hibernate throws OptimisticLockException; Spring repositories surface ObjectOptimisticLockingFailureException (a subtype of OptimisticLockingFailureException). Catch the Spring type in service code.

Wrapping up

Concurrency control isn’t optional the moment two requests can touch the same row. Optimistic locking with @Version is the right default for almost every web application: it's lock-free, scales beautifully, survives stateless requests, and turns conflicts into a clean retry. Pessimistic locking is the heavier instrument — reserve it for short, hot-row transactions where contention is real, and respect its hazards: timeouts and deadlocks.

The best systems use both: @Version everywhere as a safety net, PESSIMISTIC_WRITE surgically where the data tells you to. Measure your conflict rates, and let the numbers — not the demo — decide.

Found this useful? Follow devdomain for more deep dives on JPA, Hibernate, and Spring Boot in production. Have a deadlock horror story or a retry pattern you swear by? Tell me in the comments.

Optimistic vs Pessimistic Locking in JPATwo users open the same order. was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

This article skips the philosophy and gets practical. We’ll build the tactical patterns — entities, value objects, aggregates, repositories, domain services — in real Java 21 / Spring Boot 3.x code, then zoom out to the strategic side: bounded contexts, the ubiquitous language, and anti-corruption layers. We’ll be honest about when DDD is overkill, and the traps that turn “DDD” into expensive ceremony.

The Real Problem DDD Solves

Software complexity comes in two flavors. Technical complexity (concurrency, caching, scaling) we have good tools for. Domain complexity — the tangle of rules about how a loan gets approved, when an order can be cancelled, how a subscription prorates — is what actually sinks most enterprise projects.

The failure mode is familiar: the code and the conversation drift apart. The business says “fulfillment,” the code says OrderProcessorServiceImpl. A rule that "a shipment can't leave without a customs declaration for cross-border orders" is buried in a 600-line service behind three boolean flags. DDD's core bet is that if the code speaks the same language as the domain experts, and is organized around domain concepts rather than technical layers, you can keep the complexity from compounding.

The Ubiquitous Language

Everything in DDD starts here. The ubiquitous language is a shared, precise vocabulary used by developers and domain experts alike — in conversation, in documentation, and in the code itself. If the underwriters say “policy,” “premium,” and “endorsement,” then your classes are Policy, Premium, and Endorsement — not InsuranceRecord, Cost, and Amendment.

This sounds trivial. It is not. The language is built through conversation with domain experts and refined constantly. When a developer renames endorsement to update because it's "simpler," they've introduced a translation gap that every future conversation has to pay for.

The language is bounded — it’s only consistent within a context. “Customer” in the Sales context (a lead with a pipeline stage) is a different thing from “Customer” in the Billing context (an account with payment terms). That observation leads directly to bounded contexts, which we’ll get to.

Tactical Patterns

Value Objects

A value object has no identity — it’s defined entirely by its attributes. Two Money instances of €10 are interchangeable. Value objects should be immutable and self-validating. Java records are made for this:

public record Money(BigDecimal amount, Currency currency) {

    public Money {
        Objects.requireNonNull(amount);
        Objects.requireNonNull(currency);
        if (amount.scale() > currency.getDefaultFractionDigits()) {
            throw new IllegalArgumentException("Too many decimal places for " + currency);
        }
    }

    public Money add(Money other) {
        requireSameCurrency(other);
        return new Money(amount.add(other.amount), currency);
    }

    public Money multiply(int qty) {
        return new Money(amount.multiply(BigDecimal.valueOf(qty)), currency);
    }

    private void requireSameCurrency(Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException("Currency mismatch: " + currency + " vs " + other.currency);
        }
    }
}

Value objects are where a huge amount of domain logic should live but usually doesn’t. An EmailAddress, a PhoneNumber, a DateRange, a Quantity — each can validate itself and expose meaningful operations, replacing a swamp of primitive Strings and ints. This is the antidote to primitive obsession.

public record DateRange(LocalDate start, LocalDate end) {
    public DateRange {
        if (end.isBefore(start)) {
            throw new IllegalArgumentException("end before start");
        }
    }
    public boolean overlaps(DateRange other) {
        return !start.isAfter(other.end) && !other.start.isAfter(end);
    }
    public long days() { return ChronoUnit.DAYS.between(start, end); }
}

Entities

An entity has identity that persists through changes of state. A Customer whose email changes is still the same customer. Entities are identified by an ID, not by their attributes, and equality is based on that ID:

public class Customer {

    private final CustomerId id;        // identity
    private CustomerName name;          // value object
    private EmailAddress email;         // value object
    private CustomerStatus status;

    public Customer(CustomerId id, CustomerName name, EmailAddress email) {
        this.id = Objects.requireNonNull(id);
        this.name = Objects.requireNonNull(name);
        this.email = Objects.requireNonNull(email);
        this.status = CustomerStatus.ACTIVE;
    }

    public void changeEmail(EmailAddress newEmail) {
        if (status == CustomerStatus.CLOSED) {
            throw new IllegalStateException("Cannot change email on a closed account");
        }
        this.email = newEmail;
    }

    @Override public boolean equals(Object o) {
        return o instanceof Customer c && id.equals(c.id);
    }
    @Override public int hashCode() { return id.hashCode(); }
}

The strongly-typed CustomerId (a record wrapping a UUID) is deliberate — it makes transfer(fromId, toId) impossible to call with the arguments swapped, a class of bug raw UUID parameters invite.

Aggregates — the most important and most misunderstood pattern

An aggregate is a cluster of entities and value objects treated as a single unit for data changes. It has one aggregate root — the only member outside code is allowed to hold a reference to. All modifications go through the root, which enforces the aggregate’s invariants.

Consider an Order with OrderLines. The rule "an order's total cannot exceed the customer's credit limit" is an invariant that spans lines. The root enforces it:

public class Order {                          // aggregate root

    private final OrderId id;
    private final CustomerId customerId;
    private final List<OrderLine> lines = new ArrayList<>();
    private OrderStatus status = OrderStatus.DRAFT;

    public Order(OrderId id, CustomerId customerId) {
        this.id = id;
        this.customerId = customerId;
    }

    public void addLine(ProductId product, Money unitPrice, int quantity) {
        if (status != OrderStatus.DRAFT) {
            throw new IllegalStateException("Cannot modify a placed order");
        }
        lines.add(new OrderLine(product, unitPrice, quantity));
    }

    public void place(CreditLimit limit) {
        if (lines.isEmpty()) throw new IllegalStateException("Empty order");
        if (total().isGreaterThan(limit.available())) {
            throw new CreditLimitExceededException(id, total());
        }
        this.status = OrderStatus.PLACED;
    }

    public Money total() {
        return lines.stream().map(OrderLine::subtotal)
                    .reduce(Money.zero(), Money::add);
    }

    // No public getter exposing the mutable list:
    public List<OrderLine> lines() { return List.copyOf(lines); }
}

Two rules of thumb that prevent most aggregate mistakes:

1. Reference other aggregates by ID, not by object. Order holds a CustomerId, not a Customer. This keeps aggregates small, transaction boundaries clean, and prevents loading half the database.
2. One transaction = one aggregate. A single use case should modify one aggregate. Need to update two? Use eventual consistency (a domain event) rather than spanning both in one transaction.

Entity Value Object Aggregate Has identity? Yes No Root does Mutable? Yes (controlled) No Via root only Equality by ID Attributes Root ID Lifespan Tracked Replaced wholesale Tracked as a unit Java fit Class record Class (root) + members

Repositories

A repository provides collection-like access to aggregates. Crucially, one repository per aggregate root — you do not get a repository for OrderLine, because lines only exist within an order. The repository interface belongs to the domain; its implementation lives in infrastructure.

// domain layer — the contract, in domain terms
public interface OrderRepository {
    Optional<Order> findById(OrderId id);
    void save(Order order);
    List<Order> findPlacedOrdersFor(CustomerId customerId);
}

// infrastructure layer — Spring Data JPA backed implementation
@Repository
class JpaOrderRepository implements OrderRepository {

    private final SpringDataOrderRepository jpa;
    private final OrderMapper mapper;

    JpaOrderRepository(SpringDataOrderRepository jpa, OrderMapper mapper) {
        this.jpa = jpa; this.mapper = mapper;
    }

    @Override public Optional<Order> findById(OrderId id) {
        return jpa.findById(id.value()).map(mapper::toDomain);
    }
    @Override public void save(Order order) {
        jpa.save(mapper.toEntity(order));
    }
    @Override public List<Order> findPlacedOrdersFor(CustomerId c) {
        return jpa.findByCustomerIdAndStatus(c.value(), "PLACED")
                  .stream().map(mapper::toDomain).toList();
    }
}

Yes, you can let a JPA entity be the domain object and skip the mapper — Spring Data makes it tempting. But the moment Hibernate’s lazy loading, dirty checking, or @Version semantics dictate how you model behavior, the domain is no longer in charge. For rich domains, keep them separate.

Domain Services

Some logic doesn’t belong to any single entity or Value object. A funds transfer involves two accounts; a “find the best shipping rate” decision spans carriers and rules. That’s a domain service — stateless, named in the ubiquitous language, operating on domain objects:

public class MoneyTransferService {   // domain service, pure, no @Service needed

    public void transfer(Account from, Account to, Money amount) {
        from.withdraw(amount);   // entities still enforce their own invariants
        to.deposit(amount);
    }
}

Don’t confuse a domain service (business logic that doesn’t fit one entity, framework-free) with an application service (Spring @Service that orchestrates a use case, handles transactions, and calls repositories). The application service is the conductor; the domain service is one of the instruments.

@Service
public class TransferFundsApplicationService {

    private final AccountRepository accounts;
    private final MoneyTransferService transferService;

    // constructor omitted

    @Transactional
    public void execute(TransferCommand cmd) {
        Account from = accounts.findById(cmd.from()).orElseThrow();
        Account to   = accounts.findById(cmd.to()).orElseThrow();
        transferService.transfer(from, to, cmd.amount());
        accounts.save(from);
        accounts.save(to);
    }
}

Domain Events

When something significant happens in the domain, raise an event. It decouples side effects and is the mechanism for keeping aggregates eventually consistent. Spring’s ApplicationEventPublisher works well, and Spring Data's AbstractAggregateRoot publishes events on save:

public record OrderPlaced(OrderId orderId, CustomerId customerId, Money total, Instant occurredAt) {}

@Component
class OrderPlacedListener {
    @EventListener
    @Async
    void on(OrderPlaced event) {
        // send confirmation email, update read model, notify warehouse...
    }
}

Strategic Design

Tactical patterns make a single model clean. Strategic design keeps you from trying to build one model for the whole company — which always fails.

Bounded Contexts

A bounded context is an explicit boundary within which a model and its ubiquitous language are consistent. “Product” in the Catalog context (name, images, description) is a different model from “Product” in the Inventory context (SKU, stock level, location). Forcing them into one shared Product class produces a god object that nobody owns and everybody fights over.

┌──────────────────┐   OrderPlaced   ┌────────────────────┐
   │  SALES context    │ ──────event───▶ │  FULFILLMENT       │
   │  Order, Customer  │                 │  Shipment, Picking │
   │  (pipeline view)  │                 │  (logistics view)  │
   └──────────────────┘                 └────────────────────┘
            │                                      │
      2     │  CustomerRegistered                   │
            ▼                                      ▼
   ┌──────────────────┐                 ┌────────────────────┐
   │  BILLING context  │                 │  INVENTORY         │
   │  Account, Invoice │                 │  StockItem         │
   └──────────────────┘                 └────────────────────┘

In Spring, a bounded context typically maps to a module (Gradle subproject or Maven module), and often — but not always — to a microservice. The context map documents how they relate: shared kernel, customer/supplier, conformist, or (the one you’ll reach for most) an anti-corruption layer.

Anti-Corruption Layer (ACL)

When your context integrates with a legacy system or a third-party API whose model is messy or just different, you build an anti-corruption layer: a translation boundary that converts the foreign model into your ubiquitous language, so the outside mess never leaks into your domain.

// Your domain speaks "Customer". The legacy CRM speaks "CUST_REC".
public interface CustomerLookup {                 // port, in your language
    Optional<Customer> findByEmail(EmailAddress email);
}

@Component
class LegacyCrmAdapter implements CustomerLookup { // the ACL

    private final LegacyCrmClient client;

    @Override public Optional<Customer> findByEmail(EmailAddress email) {
        CustRec rec = client.lookup(email.value());          // foreign model
        if (rec == null) return Optional.empty();
        return Optional.of(translate(rec));                  // -> your model
    }

    private Customer translate(CustRec rec) {                // the corruption stops here
        return new Customer(
            new CustomerId(UUID.fromString(rec.getGuid())),
            new CustomerName(rec.getFName(), rec.getLName()),
            new EmailAddress(rec.getEmailAddr())
        );
    }
}

The ACL is one of the highest-leverage patterns in DDD: it lets a clean new context coexist with a legacy system without inheriting its sins.

When DDD Is Overkill

DDD has real costs — more code, more abstraction, more upfront modeling and conversation. Skip it when:

• The domain is simple. A CRUD app over a few tables with no interesting rules doesn’t need aggregates. Spring Data over JPA entities is the right amount of architecture.
• Logic is mostly technical, not domain. A file-conversion pipeline or a metrics collector has little “business” to model.
• The team won’t invest in the language. DDD without ongoing domain-expert collaboration is just unusual package names. The strategic value evaporates.
• Short-lived projects. The payoff is long-term maintainability; a three-week prototype won’t live long enough to collect it.

Apply DDD where complexity lives — the core domain that differentiates the business — and use simpler approaches for supporting and generic subdomains (like authentication or PDF generation, which you might buy or build trivially).

Common Pitfalls

• Anemic domain model. Entities with only getters/setters and all logic in services. This is the most common “DDD” anti-pattern — it has the package names but none of the benefits. Behavior belongs with data.
• Aggregates that are too big. Loading a Customer that drags in every order, payment, and address makes transactions slow and contention high. Keep aggregates small; reference by ID.
• One model to rule them all. Refusing to split bounded contexts leads to a shared Customer god class. Embrace duplication across contexts — it's healthier than coupling.
• Tactical patterns without strategic design. Sprinkling value objects everywhere while ignoring context boundaries gets you tidy classes inside one giant tangled model.
• Letting persistence dictate the model. When @Entity, @ManyToOne, and fetch strategies drive your design, JPA is in charge, not the domain.
• DDD on the wrong subdomain. Lavishing modeling effort on a generic subdomain (auth, logging) while neglecting the core domain inverts the value.

Closing Thoughts

DDD is not a framework you install; it’s a way of letting the business shape the software. Start with the ubiquitous language and a clear bounded context. Make your value objects immutable and your aggregates small. Keep the domain free of framework concerns, and wrap legacy integrations in an anti-corruption layer. Apply it where complexity earns it, and stay pragmatic everywhere else. Get this right and your code becomes a model of the business that both engineers and experts can read — which is the entire point.

Enjoyed this? Follow devdomain for more practical architecture and Java deep-dives. How do you draw the line between a domain service and an application service in your projects? Let me know in the comments.

Domain-Driven Design in Practice with Java and SpringDomain-Driven Design has a reputation problem. was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

Spring AOP (Aspect-Oriented Programming) lets you inject cross-cutting behavior — transactions, security, logging, metrics, retries — around your business methods without polluting them. @Transactional, @Cacheable, @Async, @PreAuthorize, and @Retryable are all built on it. Understanding how it works under the hood is the single highest-leverage piece of Spring knowledge, because it explains an entire class of "why didn't my annotation fire?" bugs.

This article covers the proxy mechanism (JDK dynamic proxies vs CGLIB), the @Aspect programming model, pointcut expressions, the notorious self-invocation limitation, and production-ready use cases.

The core idea: behavior wrapped around a join point

A few terms, precisely:

Term Meaning Join point A point in execution where advice can be applied. In Spring AOP, always a method execution. Pointcut An expression selecting which join points match. Advice The code that runs at a matched join point (@Before, @After, @Around, etc.). Aspect A class bundling pointcuts and advice (@Aspect). Weaving Linking aspects into target objects. Spring does this at runtime via proxies. Target The original, un-proxied bean.

The key constraint: Spring AOP only intercepts method calls that go through the proxy. It does not rewrite your bytecode (that’s full AspectJ). It wraps your bean in a proxy object and intercepts calls that arrive from outside through that proxy.

caller --> [ PROXY ] --> advice (around) --> [ TARGET method ]
                              |
                              +--> proceed() invokes the real method

Two proxy strategies: JDK dynamic vs CGLIB

When Spring decides a bean needs AOP, it creates a proxy. There are two mechanisms:

JDK dynamic proxies

Used when the bean implements at least one interface (historically Spring’s default in that case). The proxy is a runtime-generated class that implements the same interfaces and delegates to an InvocationHandler.

• The proxy is type-compatible with the interface, not the concrete class.
• You must inject the interface, not the implementation, or injection fails with a ClassCastException-style error.

CGLIB proxies

Used when there is no interface, or when forced. CGLIB generates a subclass of your target class at runtime and overrides methods to insert advice.

• Works on concrete classes.
• Cannot proxy final classes or final/private/static methods (it can't override them).
• Requires a non-arg constructor reachable by the subclass (modern Spring uses Objenesis to sidestep this in most cases).

Spring Boot defaults to CGLIB (spring.aop.proxy-target-class=true) so behavior is consistent whether or not your bean has an interface. You can flip to JDK proxies with proxy-target-class=false.

+-------------------+-----------------------------+--------------------------+
| Aspect            | JDK Dynamic Proxy           | CGLIB Proxy              |
+-------------------+-----------------------------+--------------------------+
| Requires interface| Yes                         | No                       |
| Proxy is a...     | new class impl. interface   | subclass of target       |
| final classes     | N/A                         | Cannot proxy             |
| final/private mtd | N/A                         | Not intercepted          |
| Inject as         | interface type              | class or interface type  |
+-------------------+-----------------------------+--------------------------+

The practical takeaway: with CGLIB, a final method silently won't be advised — no error, just no transaction/log/retry. That alone explains many "annotation does nothing" reports.

Writing your first aspect

Enable AOP (Spring Boot auto-enables it when spring-boot-starter-aop is on the classpath; otherwise add @EnableAspectJAutoProxy). Then declare an aspect bean:

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class LoggingAspect {

    private static final Logger log = LoggerFactory.getLogger(LoggingAspect.class);

    // Reusable named pointcut: all public methods in the service package
    @Pointcut("execution(public * com.example.app.service..*(..))")
    void serviceMethods() {}

    @Around("serviceMethods()")
    public Object logExecution(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.nanoTime();
        String sig = pjp.getSignature().toShortString();
        try {
            Object result = pjp.proceed(); // invokes the target method
            long ms = (System.nanoTime() - start) / 1_000_000;
            log.info("{} completed in {} ms", sig, ms);
            return result;
        } catch (Throwable ex) {
            log.warn("{} threw {}", sig, ex.getClass().getSimpleName());
            throw ex; // never swallow unless intentional
        }
    }
}

ProceedingJoinPoint.proceed() is the linchpin: nothing downstream runs unless you call it. Forgetting proceed() in an @Around advice silently disables the entire target method — a brutal bug.

The advice types

Advice When it runs Can change result? Can prevent target? @Before Before the method No No (only by throwing) @After After (finally semantics) No No @AfterReturning After normal return Can read return value No @AfterThrowing After an exception No (can rethrow) No @Around Wraps the call Yes (controls proceed) Yes

@Around is the most powerful — it can short-circuit, retry, transform arguments and results — but also the easiest to misuse. Prefer the narrower advice types when they suffice.

@AfterReturning(pointcut = "serviceMethods()", returning = "result")
public void onReturn(Object result) {
    log.debug("returned: {}", result);
}

@AfterThrowing(pointcut = "serviceMethods()", throwing = "ex")
public void onError(Exception ex) {
    log.error("failure", ex);
}

Pointcut expressions: the AspectJ mini-language

Spring uses a subset of AspectJ’s pointcut syntax. The most common designators:

• execution(...) — match by method signature. The workhorse.
• within(...) — match all join points within certain types.
• @annotation(...) — match methods carrying a specific annotation.
• @within(...) — match methods of classes carrying an annotation.
• args(...) / @args(...) — match by argument types/annotations.
• bean(name) — match by Spring bean name (Spring-specific).

execution syntax:

execution(modifiers? return-type declaring-type?.method-name(params) throws?)

Examples:

// any return type, any class, method named save, any args
@Pointcut("execution(* *..save(..))")

// public methods returning String in OrderService
@Pointcut("execution(public String com.example.OrderService.*(..))")

// methods taking a Long as the first arg
@Pointcut("execution(* com.example..*(Long, ..))")

// combine: service methods that are NOT in the audit package
@Pointcut("serviceMethods() && !within(com.example.app.service.audit..*)")

Annotation-driven pointcuts (the practical pattern)

For reusable cross-cutting behavior, define a custom annotation and match on it. This is exactly how Spring’s own @Transactional is wired.

import java.lang.annotation.*;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Timed {
    String value() default "";
}

@Around("@annotation(timed)")
public Object measure(ProceedingJoinPoint pjp, Timed timed) throws Throwable {
    String name = timed.value().isBlank()
        ? pjp.getSignature().toShortString() : timed.value();
    long start = System.nanoTime();
    try {
        return pjp.proceed();
    } finally {
        long ms = (System.nanoTime() - start) / 1_000_000;
        log.info("metric[{}] = {} ms", name, ms);
    }
}

Binding timed as a parameter both filters the pointcut and gives the advice access to the annotation's attributes.

The self-invocation limitation (the #1 gotcha)

Because Spring AOP works through a wrapping proxy, only calls that arrive through the proxy are intercepted. A method calling another method on the same object uses the raw this reference — which is the target, not the proxy. The advice is bypassed.

@Service
public class ReportService {

    @Transactional
    public void generateAll() {
        // BUG: this.generateOne(...) bypasses the proxy.
        // The @Transactional below does NOT start a new transaction.
        generateOne(1L);
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void generateOne(Long id) {
        // ...
    }
}

generateAll calls generateOne via this, so REQUIRES_NEW is ignored. The same trap kills @Async, @Cacheable, @Retryable, and @PreAuthorize when invoked internally.

Fixes

1. Move the annotated method to a separate bean (cleanest). Inject the other bean and call through it.
2. Self-inject the proxy and call through it:

@Service
public class ReportService {

    private final ReportService self; // the proxy

    public ReportService(@Lazy ReportService self) {
        this.self = self; // @Lazy breaks the circular dependency
    }

    @Transactional
    public void generateAll() {
        self.generateOne(1L); // goes through the proxy -> advice applies
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void generateOne(Long id) { ... }
}

1. Use AopContext.currentProxy() (requires @EnableAspectJAutoProxy(exposeProxy = true)):

((ReportService) AopContext.currentProxy()).generateOne(1L);

Option 1 is almost always the right answer. Options 2 and 3 are escape hatches that signal a design that wants splitting.

Aspect ordering

When multiple aspects match the same join point, ordering matters (e.g. you want logging outside the transaction, or retry outside metrics). Control it with @Order or Ordered:

@Aspect
@Component
@Order(1) // lower value = higher priority = outermost
public class RetryAspect { ... }

@Aspect
@Component
@Order(2)
public class MetricsAspect { ... }

The wrapping forms nested layers: Order(1) wraps Order(2) wraps the target. Note that Spring's transaction advice has a default order of Ordered.LOWEST_PRECEDENCE, so your custom aspects typically run outside the transaction unless you say otherwise.

A real, production-grade retry aspect

Cross-cutting retry is a textbook AOP use case. Here is a self-contained implementation (no Resilience4j dependency):

import java.lang.annotation.*;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Retry {
    int maxAttempts() default 3;
    long backoffMs() default 200;
    Class<? extends Throwable>[] on() default { Exception.class };
}

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

@Aspect
@Component
@Order(0) // outermost: retry wraps everything else
public class RetryAspect {

    @Around("@annotation(retry)")
    public Object retry(ProceedingJoinPoint pjp, Retry retry) throws Throwable {
        int attempts = 0;
        Throwable last = null;
        while (attempts < retry.maxAttempts()) {
            attempts++;
            try {
                return pjp.proceed();
            } catch (Throwable ex) {
                if (!isRetryable(ex, retry.on()) || attempts >= retry.maxAttempts()) {
                    throw ex;
                }
                last = ex;
                Thread.sleep(retry.backoffMs() * attempts); // linear backoff
            }
        }
        throw last; // unreachable, but satisfies the compiler
    }

    private boolean isRetryable(Throwable ex, Class<? extends Throwable>[] types) {
        for (Class<? extends Throwable> t : types) {
            if (t.isInstance(ex)) return true;
        }
        return false;
    }
}

Usage:

@Retry(maxAttempts = 4, backoffMs = 250, on = { IOException.class })
public PaymentResult charge(PaymentRequest req) { ... }

Remember: this only fires when charge is called from another bean. Internal self-calls bypass it — the lesson repeats because the bug repeats.

Accessing context inside advice

Advice often needs to inspect the method, its arguments, or its annotations. The JoinPoint API exposes all of it:

@Before("serviceMethods()")
public void audit(org.aspectj.lang.JoinPoint jp) {
    String method = jp.getSignature().getName();          // method name
    Object target = jp.getTarget();                        // the un-proxied bean
    Object[] args = jp.getArgs();                          // actual arguments
    Class<?> type = jp.getSignature().getDeclaringType();  // declaring class
    log.debug("calling {}.{} with {} args", type.getSimpleName(), method, args.length);
}

For @Around, ProceedingJoinPoint extends JoinPoint and adds proceed() plus proceed(Object[] newArgs) — the latter lets you rewrite arguments before the target runs, which is how features like input sanitization or masking aspects work:

@Around("@annotation(MaskPii)")
public Object mask(ProceedingJoinPoint pjp) throws Throwable {
    Object[] args = pjp.getArgs();
    if (args.length > 0 && args[0] instanceof String s) {
        args[0] = s.replaceAll("(?<=.{2}).(?=.*@)", "*"); // crude email mask
    }
    return pjp.proceed(args); // proceed with modified args
}

This power is also a warning: an aspect that silently rewrites arguments or results is hard to debug because the behavior lives outside the method. Use argument rewriting sparingly and document it loudly.

A metrics aspect with Micrometer

A second canonical use case is timing. Rather than littering Timer.Sample calls through your services, capture them in one aspect bound to a custom annotation:

import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class MetricsAspect {

    private final MeterRegistry registry;

    public MetricsAspect(MeterRegistry registry) {
        this.registry = registry;
    }

    @Around("@annotation(Timed)")
    public Object record(ProceedingJoinPoint pjp) throws Throwable {
        Timer.Sample sample = Timer.start(registry);
        String name = pjp.getSignature().toShortString();
        String outcome = "success";
        try {
            return pjp.proceed();
        } catch (Throwable t) {
            outcome = "error";
            throw t;
        } finally {
            sample.stop(registry.timer("method.timed",
                "method", name, "outcome", outcome));
        }
    }
}

The same pattern underpins Spring’s own @Timed support in spring-boot-actuator — it's aspects all the way down.

Spring AOP vs full AspectJ

Spring AOP is proxy-based and limited to Spring beans and method execution. AspectJ (load-time or compile-time weaving) modifies bytecode and can intercept constructors, field access, and private/internal calls — including self-invocation — because there is no proxy involved.

Reach for AspectJ only when you genuinely need those capabilities. For 95% of applications, Spring AOP is simpler, has no build-time weaving step, and is plenty. Enable AspectJ weaving via @EnableLoadTimeWeaving and an agent only when the proxy model truly can't express your need.

Common pitfalls and gotchas

• Self-invocation: internal calls bypass the proxy. The root cause of most “annotation does nothing” issues.
• final methods/classes with CGLIB: silently not advised; CGLIB can't override them.
• private methods are never advised: pointcuts apply to proxied (effectively public/protected) methods only.
• Forgetting proceed() in @Around: the target never runs.
• Swallowing exceptions in advice: rethrow unless you mean to suppress. Catching and not rethrowing changes method semantics invisibly.
• Injecting the concrete class under JDK proxies: causes injection failures; inject the interface or force CGLIB.
• Calling AOP-annotated methods from constructors/@PostConstruct: the proxy may not be fully wired yet.
• Ordering assumptions: without explicit @Order, the relative order of multiple aspects is undefined.
• Performance of broad pointcuts: execution(* *(..)) matches everything and adds overhead to every call. Scope pointcuts tightly.

Best practices

• Prefer custom annotations + @annotation(...) pointcuts over broad execution expressions — they're explicit and self-documenting.
• Use the narrowest advice type that works; reserve @Around for when you must control proceed().
• Keep aspects free of business logic. They are infrastructure.
• Always set @Order when more than one aspect can match.
• Split classes so annotated methods are called externally, sidestepping self-invocation entirely.
• For resilience features, prefer battle-tested libraries (Resilience4j) over hand-rolled aspects in production; build your own only for simple, well-understood concerns.

Conclusion

Spring AOP is “just” a proxy wrapping your bean and intercepting external method calls. Every confusing behavior — the dead @Transactional, the ignored @Async, the unhelpful @Cacheable — traces back to that single fact: if the call doesn't go through the proxy, the advice doesn't run. Master the proxy model, choose CGLIB vs JDK proxies deliberately, write tight annotation-driven pointcuts, and design your beans so cross-cutting methods are always invoked from the outside. Do that, and AOP becomes a precise tool instead of an occasional mystery.

Found this useful? Follow devdomain for more under-the-hood Spring deep dives, and comment with the AOP bug that cost you the most time — I bet it was self-invocation.

Spring AOP Explained: Aspects, Pointcuts, and How Proxies Really WorkYou add @Transactional to a… was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.