DEV Community: Taras Antoniuk

Spring Security Beyond the Login Form: Data Isolation and the 401/403 Contract

Taras Antoniuk — Sun, 20 Sep 2026 12:14:12 +0000

Why This Article Exists

There is a very common kind of application: it lives inside a company network, it is reachable over the VPN, and it has been running like that for years. Accounting systems, internal reporting tools, warehouse apps, admin panels. Sometimes there is a login screen, sometimes there is not. It does not matter much, because the answer to "who can reach this?" is "whoever the network lets in".

And then a day comes when that stops being enough. An accountant needs to close the month from home. An external auditor needs read access for two weeks. A partner wants to pull their own turnover figures. Someone builds a mobile client. The perimeter dissolves — not because anyone decided to remove it, but because the business outgrew it.

At that point the app has to start answering two questions on every single request that the network used to answer once, at the door:

Who are you? — no valid identity means 401.
Are you allowed to do this, to this data? — valid identity, insufficient rights, means 403.

I want to show you how that is done, and I want to be straight about the stage it is done on.

What follows is a demonstration project: a financial accounting system on Java 21 and Spring Boot 3.5. It is deployed and publicly reachable. There are no real customers and no real money in it, and every organization, counterparty and payment in the database is fabricated.

The shape of that database is not. Organizations, counterparties, bank accounts, posted and reversed documents over an event-sourced ledger — those are the structures that make authorization genuinely hard. A three-table toy makes it look easy. Security was also retrofitted here the way it usually is in real life: onto an application that already existed and had never been asked who was calling.

That setup buys something a production write-up cannot. On a real system you get to describe a bug once, after it is fixed, with the details filed off. Here I can put the failure back in deliberately, show you the code that produces it, and then show you the fix — on a system I am allowed to break in public. So none of the failures in this article are invented for teaching purposes. Every one of them is modelled on a real bug, from a real project, with real users — most of them from a work project that ran in parallel with this one and wrapped up in May. What I could not do there was show you the code. So I rebuilt them here, on a codebase I am allowed to publish. This time you can follow the whole chain, from the first line to the fix.

One last bit of honesty, this one about timing. I have wanted to write this up since that project ended, and it took until now. Part of that is the ordinary reason things get postponed. The better part is that every time I sat down to explain a piece of this, I found something in the piece still worth fixing. If you have a project you keep meaning to write about, that is my one argument for doing it: explaining your own code to a stranger is a code review you cannot talk your way out of.

The interesting part, as it turns out, is not the authentication code — that is well documented and mostly mechanical. It is everything the perimeter had been quietly covering up.

Full code is available on GitHub.

Target audience: This article is aimed at beginner and mid-level developers who are adding Spring Security to an application that already exists. If you have wired up a login form before but never had to answer "whose rows are these?" — this article is for you.

The Network Was Your Authorization Layer

Here is the thing nobody tells you when you add spring-boot-starter-security.

Inside a VPN, every service method was written under one unstated assumption: whoever is calling has the right to see this. So getAllBankAccounts() returns all bank accounts. findByBankId(bankId) returns every account at that bank. Nobody ever wrote WHERE organization_id = ?, because there was nothing to defend against — everyone on the network was, by definition, a colleague.

Publish that same service behind a login form and every one of those methods becomes an IDOR (Insecure Direct Object Reference). A perfectly valid, correctly authenticated user of organization A now calls a perfectly legitimate endpoint and reads organization B's payment history. No exploit, no clever attack. Just a GET with a valid token.

Adding a login screen does not fix this. It gives every attacker a legitimate identity to attack with.

So the work splits into two very different halves:

Authentication and endpoint rules — largely a configuration problem. A weekend.
Data isolation in the service layer — a design problem that touches every read path in the codebase.

Most guides cover the first half. The second half is where the real bugs live.

The Identity You Issue Decides How Hard Everything Else Is

The app is a REST API with a separate frontend, so sessions were not an option: JWT with short-lived access tokens (15 minutes) and long-lived refresh tokens (7 days). Signing them, validating them, wiring up the filter — that is the well-documented part, and I am going to skip most of it.

One decision here is worth the whole section, because the entire second half of the work leans on it: the caller's organization travels inside the identity. One claim when the token is minted:

if (user.getOrganization() != null) {
    builder.claim("orgId", user.getOrganization().getId());
}

and a principal that is a record rather than a String username:

public record JwtPrincipal(Long userId, String email, UserRole role, Long organizationId) { }

View JwtService.java on GitHub · View JwtPrincipal.java on GitHub

Because tenancy rides along with the identity, any service can ask "which organization is calling?" without a database round trip and without threading a parameter through fifteen method signatures. Pass it as a method parameter instead and you have just created fifteen places to forget it.

The filter that turns a token into that principal is unremarkable, except for what it checks besides the signature — a valid signature is necessary, not sufficient:

String jti = claims.getId();
if (jti != null && tokenBlacklistService.isBlacklisted(jti)) {
    filterChain.doFilter(request, response);   // logged out — stays anonymous
    return;
}

Optional<JwtPrincipal> optionalPrincipal = toPrincipal(claims);
if (optionalPrincipal.isEmpty()) {
    filterChain.doFilter(request, response);   // claims we can no longer read
    return;
}

JwtPrincipal principal = optionalPrincipal.get();
if (userRevocationService.isRevoked(principal.userId())) {
    filterChain.doFilter(request, response);   // deactivated by an admin
    return;
}

One habit worth stealing: the filter never throws. If the token is missing, malformed, expired, blacklisted or belongs to a revoked user, it simply does not authenticate and lets the chain continue. The request then hits the authorization rules as anonymous, and Spring's AuthenticationEntryPoint produces one consistent 401. One code path, one response shape, no leaking of why the token was rejected.

That habit has to cover your own parsing too. The claims are ones you wrote, so they look safe. But Long.parseLong and UserRole.valueOf still throw on a token that was minted before you renamed something, and a throw here lands in the catch-all handler — which is the exact failure the last section of this article is about:

private Optional<JwtPrincipal> toPrincipal(Claims claims) {
    try {
        return Optional.of(new JwtPrincipal(
                Long.parseLong(claims.getSubject()),
                claims.get("email", String.class),
                UserRole.valueOf(claims.get("role", String.class)),
                claims.get("orgId", Long.class)));
    } catch (IllegalArgumentException | NullPointerException | JwtException e) {
        return Optional.empty();
    }
}

View JwtAuthenticationFilter.java on GitHub

A Refresh Token Is Not a Response Field

The natural first implementation returns both tokens in the JSON body. It works, it demos well, and it means any XSS on your frontend hands the attacker seven days of access instead of fifteen minutes.

The refresh token never appears in a response body. It is an HttpOnly cookie, scoped to exactly one path:

private void addRefreshTokenCookie(HttpServletResponse response, String refreshToken) {
    ResponseCookie cookie = ResponseCookie.from(REFRESH_TOKEN_COOKIE, refreshToken)
            .httpOnly(true)
            .secure(true)
            .path("/api/auth/refresh")   // sent to this endpoint and nowhere else
            .maxAge(Duration.ofMillis(jwtService.getRefreshTokenExpiration()))
            .sameSite("Strict")
            .build();
    response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
}

Refresh tokens are stored hashed (SHA-256) and rotated on every use: the old one is marked used and revoked, a new pair is issued. That gives you theft detection for free — if a token that has already been used shows up again, either it was stolen or it was replayed, and in both cases the honest answer is to burn the whole family:

if (refreshToken.isUsed()) {
    refreshTokenRepository.revokeAllByUserId(refreshToken.getUser().getId());
    log.warn("SECURITY: Refresh token reuse detected for userId={}. All tokens revoked.",
            refreshToken.getUser().getId());
    eventPublisher.publishEvent(SecurityAuditEvent.tokenReuseDetected(...));
    throw new InvalidTokenException("Token reuse detected");
}

View AuthController.java on GitHub · View AuthService.java on GitHub

The trap that cost me an evening: cookies plus CORS. The browser will neither store nor send that cookie unless every auth call uses credentials: 'include', and the server sets allowCredentials(true) with an explicit origin list — a wildcard origin is rejected outright. It gets worse if a client tries to be helpful and sends the refresh token in a custom X-Refresh-Token header instead. That header is not on the allowed list, so the preflight fails. The response comes back without an Access-Control-Allow-Origin header, and the browser reports a missing origin error. You then spend an hour debugging CORS configuration for what is really a client sending the wrong thing.

Authorization Rules: First Match Wins

Two filter chains: one for Swagger and health checks, one for everything else. The @Order(1) chain uses securityMatcher to claim the documentation paths, so the main chain never sees them.

The main chain is ordinary Spring Security, with one habit worth adopting — write rules from most specific to least specific, and end with a default that fails closed:

.authorizeHttpRequests(auth -> auth
        .requestMatchers("/api/auth/logout").authenticated()
        .requestMatchers("/api/auth/change-password").authenticated()
        .requestMatchers("/api/auth/**").permitAll()

        .requestMatchers(HttpMethod.GET, "/api/exchange-rates/latest/{date}").permitAll()
        .requestMatchers("/api/admin/**").hasRole("ADMIN")

        // master data: read for everyone authenticated, writes for admins
        .requestMatchers(HttpMethod.POST, "/api/banks/**", "/api/currencies/**",
                "/api/countries/**", "/api/exchange-rates/**").hasRole("ADMIN")
        // ... PUT / PATCH / DELETE likewise

        // operational default
        .requestMatchers(HttpMethod.GET,    "/api/**").authenticated()
        .requestMatchers(HttpMethod.POST,   "/api/**").hasAnyRole("USER", "ADMIN")
        .requestMatchers(HttpMethod.PUT,    "/api/**").hasAnyRole("USER", "ADMIN")
        .requestMatchers(HttpMethod.PATCH,  "/api/**").hasAnyRole("USER", "ADMIN")
        .requestMatchers(HttpMethod.DELETE, "/api/**").hasRole("ADMIN")

        .anyRequest().authenticated()
)

Note that /api/auth/logout is declared before /api/auth/**. Rules are evaluated in order and the first match wins; flip those two lines and logout becomes a public endpoint. This is the single easiest way to open a hole in an otherwise correct configuration, and nothing warns you.

The catch-all .anyRequest().authenticated() at the end means a new controller added six months from now is protected by default. Every rule set should end with the restrictive case, not the permissive one.

View SecurityConfig.java on GitHub

The Half That Actually Matters: Data Isolation

Endpoint rules say this role may call this URL. They say nothing about whose rows come back. A USER with a perfectly valid token calling a perfectly legitimate GET /api/bank-accounts is exactly the scenario the VPN used to make impossible.

Concretely: behind that endpoint the service was a single line — bankAccountRepository.findAllWithRelations() — and that method meant all of them. Log in as a USER of organization 1, click the button that user is supposed to click, and organization 2's accounts come back in the same list. Revert the change and you can reproduce that in this demo today. I have also watched almost exactly this finding land in a real security review.

What makes it dangerous is how ordinary it looks. Nothing in the request is wrong. Nothing in the access log looks wrong. There is no failed login to alert on, no rate limit to trip, no stack trace. The only thing that changed is that the network is no longer the one deciding who "we" means — and no part of the application noticed, because no part of the application was ever told.

The fix is a small component that reads the organization off the principal and turns it into an authorization decision:

@Component
public class OrganizationSecurityContext {

    public Long getActiveOrganizationId() {
        JwtPrincipal principal = getCurrentPrincipal();
        Long organizationId = principal.organizationId();
        if (organizationId == null) {
            throw new AccessDeniedException("No active organization for current user");
        }
        return organizationId;
    }

    public void validateAccess(Long organizationId) {
        if (organizationId == null) {
            throw new AccessDeniedException("Organization id is required");
        }
        JwtPrincipal principal = getCurrentPrincipal();
        if (principal.role() == UserRole.ADMIN) {
            return;
        }
        if (!organizationId.equals(principal.organizationId())) {
            throw new AccessDeniedException("User does not have access to organization " + organizationId);
        }
    }
}

View OrganizationSecurityContext.java on GitHub

Two access patterns cover almost everything:

Reads get filtered. The service resolves a scope and passes it into the query. null means "admin, no filter":

private Long queryOrgScope() {
    return orgContext.isAdmin() ? null : orgContext.getActiveOrganizationId();
}

public List<BankAccountResponseDto> getAllBankAccounts() {
    List<BankAccount> bankAccounts = bankAccountRepository.findAllWithRelations(queryOrgScope());
    return bankAccountMapper.toResponseList(bankAccounts);
}

@Query("SELECT ba FROM BankAccount ba " +
        "LEFT JOIN FETCH ba.bank " +
        "LEFT JOIN FETCH ba.currency " +
        "WHERE (:orgId IS NULL " +
        "   OR ba.holderType = 'COUNTERPARTY' " +
        "   OR (ba.holderType = 'ORGANIZATION' AND ba.holderId = :orgId))")
List<BankAccount> findAllWithRelations(@Param("orgId") Long orgId);

View BankAccountService.java on GitHub · View BankAccountRepository.java on GitHub

Single-entity fetches get validated. You cannot filter a findById, so you load and then check ownership before mapping — and importantly, before the entity reaches a DTO:

public BankAccountResponseDto getBankAccountById(Long id) {
    BankAccount bankAccount = bankAccountRepository.findByIdWithRelations(id)
            .orElseThrow(() -> BankAccountNotFoundException.byId(id));
    validateAccountAccess(bankAccount);
    return bankAccountMapper.toResponse(bankAccount);
}

And this is the test that closes it — the one that fails against every version of this system that shipped behind the VPN:

@Test
void validateAccess_WhenForeignOrganization_ShouldThrow() {
    authenticateAs(UserRole.USER, ORG_ID);

    AccessDeniedException ex = assertThrows(AccessDeniedException.class,
            () -> securityContext.validateAccess(OTHER_ORG_ID));

    assertEquals("User does not have access to organization 2", ex.getMessage());
}

View tests:

Some notes from doing this across nine services:

The filter belongs in the query, not in a Java stream().filter(). Filtering after the fact still pulls the other organization's rows across the wire and into memory, and pagination silently breaks: page 1 of 20 rows returns 3 results.
Not everything should be scoped, and that is a decision worth writing down. Counterparties in this system are a deliberately shared directory — the same supplier is invoiced by several organizations, and duplicating them per organization would fragment payment history. Visibility comes from the documents that reference a counterparty, which are scoped. Exchange rates, banks, currencies and countries are global reference data. Every "global" decision should be a recorded decision, not an oversight that happens to look like one.
Admin bypass needs to be explicit and centralized. One isAdmin() check inside the security context, not if (role == ADMIN) sprinkled through nine services.
Writes need the same treatment as reads, including the "which org does this new row belong to" question. A non-admin does not get to choose:

if (requestDTO.getHolderType() == AccountHolderType.ORGANIZATION) {
    requestDTO.setHolderId(orgContext.resolveOrganizationId(requestDTO.getHolderId()));
}

Error Semantics Are a Contract

Get them wrong and the app develops symptoms that look exactly like a permissions bug. This is my favourite part, because it is the one I did not see coming.

Once your API is public, HTTP status codes stop being cosmetic. They are the protocol your client uses to decide what to do next:

401 — no valid identity. The client should try to refresh, and if that fails, send the user to the login screen.
403 — valid identity, insufficient rights. The client should show a message. Refreshing will not help; logging out and back in will not help.

Spring Security handles the framework-level cases through AuthenticationEntryPoint (401) and AccessDeniedHandler (403). What it does not cover is anything thrown after the filter chain has already let the request through. That is exactly where the interesting denials live.

Bug one: AccessDeniedException from the service layer became a 500. The endpoint rules passed (a USER is allowed to call GET /api/bank-accounts/42), the request reached the controller, and only then did validateAccess throw. By then the security filter chain is long gone. The exception surfaces as an ordinary controller exception and falls through to the catch-all @ExceptionHandler(Exception.class), which maps everything to 500 and helpfully includes the internal message. A cross-organization access attempt was reported as a server error.

Bug two, the expensive one: a missing refresh cookie became a 500. When an access token expired, the frontend called /api/auth/refresh. If the cookie was gone too, Spring raised MissingRequestCookieException — which, again, hit the catch-all and came back as 500. The frontend did not recognize a 500 as "your session ended", so it silently cleared its tokens and kept going. What lands on screen is "insufficient permissions" — on pages that worked a minute ago. I reproduced that here because I had seen it before, somewhere with rather more at stake. There the person reading that message was a real user, mid-task, on screens that had worked all morning. The ticket they filed said "permissions are broken".

Every visible symptom pointed at authorization. The cause was three levels away, in the catch-all exception handler — the one piece of the stack nobody revisits when they add security, because it predates the security layer and looks like it has nothing to do with it.

The fix is boring, which is the point. Handle the security exceptions explicitly, in a @RestControllerAdvice ordered ahead of the generic one:

@RestControllerAdvice
@Order(1)
public class SecurityExceptionHandler {

    /**
     * Handles denials raised inside the service layer (OrganizationSecurityContext).
     * Denials at the filter chain level are handled by CustomAccessDeniedHandler instead.
     */
    @ExceptionHandler(AccessDeniedException.class)
    public ResponseEntity<ErrorResponse> handleAccessDeniedException(
            AccessDeniedException ex, HttpServletRequest request) {
        return buildErrorResponse(HttpStatus.FORBIDDEN, ex.getMessage(), request);
    }

    @ExceptionHandler(InvalidTokenException.class)
    public ResponseEntity<ErrorResponse> handleInvalidTokenException(
            InvalidTokenException ex, HttpServletRequest request) {
        return buildErrorResponse(HttpStatus.UNAUTHORIZED, ex.getMessage(), request);
    }
}

And take the cookie yourself instead of letting the framework reject the request for you:

@PostMapping("/refresh")
public ResponseEntity<AccessTokenResponse> refresh(
        @CookieValue(name = REFRESH_TOKEN_COOKIE, required = false) String refreshToken,
        HttpServletResponse response) {
    if (refreshToken == null || refreshToken.isBlank()) {
        throw new InvalidTokenException("Refresh token is missing");   // → 401, not 400 or 500
    }
    ...
}

View SecurityExceptionHandler.java on GitHub · View AuthController.java on GitHub

The rule I would put on the wall: no framework exception should ever reach your catch-all handler. That handler exists to keep the process alive, not to answer clients. Anything it catches is, by definition, a status code you never designed — and on a public API, an undesigned status code is a bug in someone else's application.

Related, and cheap: turn off stack traces in fallback error responses. The default /error output leaks your package structure and library versions to anyone with curl.

What You Still Need Once There Is No Perimeter

Once identity works, a handful of controls turn a login form into something you can leave facing the internet. None of them are complicated:

Account lockout — 5 failed attempts, 30-minute lock, with the row read via SELECT ... FOR UPDATE so parallel attempts cannot race past the counter.
Rate limiting — Resilience4j, 5 requests per 60 seconds on the auth endpoints, returning 429. This is what stands between you and credential stuffing.
Token blacklist — a JWT is valid until it expires, so logout needs somewhere to record "this jti is dead". Caffeine cache (15-minute TTL, matching the access-token lifetime) in front of a database table, so a restart does not resurrect logged-out tokens.
User revocation — checked in the filter, so deactivating an account takes effect on the next request, not in fifteen minutes.
Security audit events — login success and failure, lockouts, token refresh, token reuse, all published as Spring application events and persisted. The first time you need to answer "when exactly did this account get locked, and from which IP", you will be glad it is a table and not a log file.
Security headers — HSTS, X-Content-Type-Options, frame-ancestors 'none', a restrictive CSP. Four lines in the config.

Common Pitfalls

1. Rule order silently opens holes

.requestMatchers("/api/auth/**").permitAll() placed above the logout rule makes logout public. The first matching rule wins, and nothing warns you — not a startup error, not a log line. Write rules from most specific to least specific and end with .anyRequest().authenticated().

2. Cookies plus CORS look like a CORS bug

The browser drops the refresh cookie unless every auth call uses credentials: 'include' and the server sets allowCredentials(true) with an explicit origin list. Send the token in a custom header instead and the preflight fails with no Access-Control-Allow-Origin, which the browser reports as a missing origin. The config is fine. The client is sending the wrong thing.

3. Filtering in memory instead of in the query

stream().filter(...) after the repository call still moves another organization's rows across the wire, and pagination breaks quietly: page 1 of 20 rows comes back with 3 results. The organization id belongs in the query.

4. Your catch-all handler predates your security layer

@ExceptionHandler(Exception.class) was written before there was anything to deny. After you add security it starts catching AccessDeniedException and MissingRequestCookieException and turning both into 500. Nobody revisits that class when adding security, because it looks unrelated.

5. Parsing your own claims can throw

Long.parseLong(claims.getSubject()) and UserRole.valueOf(...) look safe, because you wrote those claims yourself. Rename an enum constant and every token minted in the last fifteen minutes throws inside the filter — straight into pitfall 4.

The Flow Visualized

Request with Bearer token
    │
    ▼
JwtAuthenticationFilter
    │
    ├── no token / bad signature / expired ───┐
    ├── jti blacklisted (logged out) ─────────┤
    ├── user revoked by an admin ─────────────┤──► never authenticated
    └── claims cannot be parsed ──────────────┘             │
    │                                                       ▼
    ▼ JwtPrincipal(userId, email, role, orgId)   JwtAuthenticationEntryPoint → 401
    │
SecurityFilterChain rules
    │
    ├── role not allowed ──► CustomAccessDeniedHandler → 403
    ▼
Controller → Service
    │
    ├── OrganizationSecurityContext.validateAccess(orgId)
    │        └── foreign organization ──► AccessDeniedException
    │                                         └── SecurityExceptionHandler → 403
    ▼
Repository query filtered by :orgId  ──►  200, this organization's rows only

Key Takeaways

If you are about to take an internal application public, in this order:

Inventory every read path and ask who is allowed to see those rows. This is the long pole, not the login form. Start here, not last.
Put tenancy in the principal, not in method parameters. It travels for free and cannot be forgotten at a call site.
Filter in the query. In-memory filtering breaks pagination and still moves the data.
Write down what is deliberately global — shared directories, reference data. Undocumented exceptions are indistinguishable from bugs during the next review.
Design your 401 vs 403 contract before writing clients, and make sure nothing framework-thrown can bypass it into a 500.
End your authorization rules with the restrictive case, so future endpoints are protected by default.
Test the negative paths. "User from org A gets 403 for org B's account" is the test that actually proves the work; "user can read their own data" passes just as happily on a completely broken system.

The authentication part of this was a weekend. The data isolation was the real project — and it was the only part that would have shown up in a breach report.

Try It Yourself

The system described here is a financial accounting prototype: Java 21, Spring Boot 3.5, PostgreSQL, event-sourced banking documents. The data in it is fabricated, the structure is not. It is deployed, so you can try the 401 / 403 behaviour above instead of taking my word for it:

curl -i https://api.tarasantoniuk.com/api/countries
# HTTP/2 401
# {"status":401,"error":"Unauthorized","message":"Authentication is required to access this resource", ...}

Demo UI: https://finance.tarasantoniuk.com
API: https://api.tarasantoniuk.com
Swagger: https://api.tarasantoniuk.com/swagger-ui/index.html
Source: https://github.com/TarasAntoniuk/finance

Registration is open. A new account is created as a GUEST in the demo organization, so it can read but not write. A 403 on any POST is the endpoint rules working, not a broken demo.

Happy to hear how others handled the service-layer half of this — especially anyone who went the Hibernate filters or row-level security route instead of explicit query parameters.

Resources

About the author:
Java Backend Developer with 19+ years of IT experience, building heavy backend financial applications.

Connect:

If you found this article helpful, please leave a reaction ❤️ and follow for more!

Circuit Breaker + Retry in Spring Boot: A Practical Guide with Resilience4j

Taras Antoniuk — Tue, 10 Mar 2026 13:51:42 +0000

Why This Article Exists

When your microservice calls an external API, things will go wrong. The remote service goes down, your threads pile up, timeouts cascade, and suddenly your perfectly healthy application is choking because of someone else's outage.

This is exactly the problem that the Circuit Breaker pattern solves. And when you combine it with Retry, you get a resilient system that can recover from transient failures while protecting itself from prolonged outages.

When I looked through my public repositories for a good example of calling an external API with proper resilience handling, I couldn't find one. So I built a demo service that wraps the randomuser.me test API — a perfect sandbox for demonstrating how Circuit Breaker and Retry work together in practice. While the API itself is just a test sandbox, the resilience patterns we apply here are exactly what you'd use when integrating with any real external service (payment gateways, third-party data providers, partner APIs, etc.).

Full code is available on GitHub.

Target audience: This article is aimed at beginner and mid-level developers who integrate with external APIs and want to learn how to make those integrations resilient. If you've worked with Spring Boot but never added Circuit Breaker or Retry — this article is for you.

The Setup

The project is a stateless Spring Boot 3.5 proxy service using Java 21. The key components:

RandomUserClient — the HTTP client that talks to the external API
UserService — business logic and validation
UserController — REST endpoints
GlobalExceptionHandler — centralized error handling

The HTTP client uses Spring's modern RestClient (not the deprecated RestTemplate):

@Configuration
public class RestClientConfig {

    @Bean
    public RestClient randomUserRestClient(
            RestClient.Builder builder,
            @Value("${randomuser.base-url}") String baseUrl,
            @Value("${randomuser.connect-timeout}") int connectTimeout,
            @Value("${randomuser.read-timeout}") int readTimeout) {

        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(connectTimeout);
        factory.setReadTimeout(readTimeout);

        return builder
                .baseUrl(baseUrl)
                .requestFactory(factory)
                .build();
    }
}

With timeouts configured in application.properties:

randomuser.base-url=https://randomuser.me
randomuser.connect-timeout=2000
randomuser.read-timeout=3000

View RestClientConfig.java on GitHub

Adding Resilience4j

We use the BOM (Bill of Materials) for version consistency:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.resilience4j</groupId>
            <artifactId>resilience4j-bom</artifactId>
            <version>2.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.github.resilience4j</groupId>
        <artifactId>resilience4j-spring-boot3</artifactId>
    </dependency>
</dependencies>

View pom.xml on GitHub

The Circuit Breaker + Retry Combination

Here's the core question: in what order should Circuit Breaker and Retry wrap each other?

The correct answer is: Circuit Breaker wraps Retry.

Request → CircuitBreaker → Retry → Retry → Retry → HTTP call

Why? Because you want Retry to exhaust all its attempts first, and only then should the Circuit Breaker record the final outcome (success or failure). If it were the other way around, every individual retry attempt would count as a separate failure for the Circuit Breaker — which would trip it open far too quickly.

The Aspect Order Trap

Here's where it gets non-obvious. In Spring, annotations on a method don't have a guaranteed execution order. The order of @CircuitBreaker and @Retry on your method does not determine which one is the outer decorator.

You must configure this explicitly through properties:

# Higher order number = outer decorator
# CircuitBreaker(1) → Retry(2) → actual method call
resilience4j.circuitbreaker.circuitBreakerAspectOrder=1
resilience4j.retry.retryAspectOrder=2

The rule: the aspect with the higher aspectOrder value executes as the outer decorator. So CircuitBreaker with order 1 wraps Retry with order 2, meaning Retry is closer to the method — exactly what we want.

⚠️ Without explicit ordering, the behavior is undefined and may change between JVM restarts. Always configure this in properties.

The Client Implementation

@Component
public class RandomUserClient {

    private final RestClient restClient;
    private static final Logger log = LoggerFactory.getLogger(RandomUserClient.class);

    public RandomUserClient(RestClient restClient) {
        this.restClient = restClient;
    }

    @Retry(name = "randomUserApi")
    @CircuitBreaker(name = "randomUserApi", fallbackMethod = "getUsersFallback")
    public UserResponseDto getUsers(int count) {
        try {
            return restClient.get()
                    .uri("/api/?results={count}", count)
                    .retrieve()
                    .body(UserResponseDto.class);
        } catch (HttpServerErrorException ex) {
            log.error("External API server error: {}", ex.getMessage());
            throw new ExternalApiException(502, "External API server error");
        } catch (ResourceAccessException ex) {
            log.warn("External API is unavailable: {}", ex.getMessage());
            throw new ExternalApiException(503, "External API is unavailable");
        }
    }

    private UserResponseDto getUsersFallback(int count, Exception ex) {
        log.warn("Circuit breaker fallback triggered: {}", ex.getMessage());
        throw new ExternalApiUnavailableException(
                "Random User API is currently unavailable");
    }
}

View RandomUserClient.java on GitHub

A few things to notice:

1. The fallback method signature must match. It takes the same parameters as the original method plus an Exception parameter. Getting this wrong produces a cryptic NoSuchMethodException at runtime.

2. The fallback throws, not returns. Returning a default/empty response would silently degrade the user experience. Instead, we throw ExternalApiUnavailableException, which the GlobalExceptionHandler maps to HTTP 503. This makes it explicit to the client that the service is degraded.

3. HttpClientErrorException is notably absent from the catch block. This is intentional — keep reading.

The 4xx vs 5xx Retry Problem

Here's a critical design decision: should you retry on 4xx (client) errors?

No. A 4xx error means the request itself is invalid. Retrying it will produce the same result every time. You should only retry on:

5xx errors (HttpServerErrorException) — the server had a transient problem
Network errors (ResourceAccessException) — timeout, connection refused, etc.

We configure this explicitly in properties:

# Retry only on server errors and network issues
resilience4j.retry.instances.randomUserApi.retry-exceptions=\
  org.springframework.web.client.HttpServerErrorException,\
  org.springframework.web.client.ResourceAccessException,\
  com.tarasantoniuk.random_user_api.feature.user.exception.ExternalApiException

# Never retry on client errors
resilience4j.retry.instances.randomUserApi.ignore-exceptions=\
  org.springframework.web.client.HttpClientErrorException

By letting HttpClientErrorException propagate uncaught through the client method (no catch block for it), it bypasses both Retry and Circuit Breaker and goes straight to the GlobalExceptionHandler. The Circuit Breaker won't count a 4xx as a failure, and Retry won't waste time on an unrecoverable error.

View full application.properties on GitHub

Full Circuit Breaker Configuration

# Sliding window: last 10 calls
resilience4j.circuitbreaker.instances.randomUserApi.sliding-window-size=10

# Open circuit when 50% of calls fail
resilience4j.circuitbreaker.instances.randomUserApi.failure-rate-threshold=50

# Stay open for 30 seconds before transitioning to half-open
resilience4j.circuitbreaker.instances.randomUserApi.wait-duration-in-open-state=30s

# Allow 3 test calls in half-open state
resilience4j.circuitbreaker.instances.randomUserApi.permitted-number-of-calls-in-half-open-state=3

And the Retry configuration:

resilience4j.retry.instances.randomUserApi.max-attempts=3
resilience4j.retry.instances.randomUserApi.wait-duration=1s

This means: on a transient failure, Retry will attempt up to 3 calls with 1-second intervals. If all 3 fail, that counts as one failure for the Circuit Breaker. After 5 out of 10 such failures (50%), the circuit opens and all subsequent calls go straight to the fallback for 30 seconds.

Monitoring with Spring Boot Actuator

You'll want to observe the circuit breaker state in production. Add the Actuator dependency and configure it:

management.health.circuitbreakers.enabled=true
management.endpoint.health.show-details=always
resilience4j.circuitbreaker.instances.randomUserApi.register-health-indicator=true

Now GET /actuator/health includes the circuit breaker state:

{
  "components": {
    "circuitBreakers": {
      "status": "UP",
      "details": {
        "randomUserApi": {
          "status": "UP",
          "details": {
            "failureRate": "-1.0%",
            "state": "CLOSED"
          }
        }
      }
    }
  }
}

When the circuit opens, the state changes to OPEN and the overall health status reflects the degradation.

Exception Hierarchy and Global Error Handling

The exception design is deliberate:

ExternalApiException — wraps 5xx errors from the external API, carries the HTTP status code
ExternalApiUnavailableException — thrown by the Circuit Breaker fallback when the circuit is open
HttpClientErrorException — Spring's built-in exception for 4xx, propagated as-is

The GlobalExceptionHandler maps each to the appropriate HTTP response:

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ExternalApiException.class)
    public ResponseEntity<ErrorResponse> handleExternalApiException(ExternalApiException ex) {
        HttpStatus status = HttpStatus.resolve(ex.getStatusCode());
        if (status == null) {
            status = HttpStatus.BAD_GATEWAY;  // safe default for unknown codes
        }
        return ResponseEntity.status(status)
                .body(new ErrorResponse(status.value(), "External API error"));
    }

    @ExceptionHandler(ExternalApiUnavailableException.class)
    public ResponseEntity<ErrorResponse> handleExternalApiUnavailable(
            ExternalApiUnavailableException ex) {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .body(new ErrorResponse(503, "External API is currently unavailable"));
    }

    @ExceptionHandler(HttpClientErrorException.class)
    public ResponseEntity<ErrorResponse> handleHttpClientError(
            HttpClientErrorException ex) {
        return ResponseEntity.status(ex.getStatusCode())
                .body(new ErrorResponse(
                        ex.getStatusCode().value(), "External API client error"));
    }
}

Note the use of HttpStatus.resolve() instead of HttpStatus.valueOf(). The difference? valueOf() throws an IllegalArgumentException on non-standard status codes (like 999), while resolve() safely returns null — which we handle with a fallback to BAD_GATEWAY.

View GlobalExceptionHandler.java on GitHub

Testing the Resilience Layer

Testing the service layer with Mockito — we verify that the client is called for valid inputs and that validation rejects invalid ones:

@ExtendWith(MockitoExtension.class)
class UserServiceTest {

    @Mock
    private RandomUserClient randomUserClient;

    @Test
    void getUsers_validCount_delegatesToClient() {
        UserService service = new UserService(randomUserClient, 5000);
        UserResponseDto expected = new UserResponseDto(List.of(), null);
        when(randomUserClient.getUsers(10)).thenReturn(expected);

        UserResponseDto result = service.getUsers(10);

        assertEquals(expected, result);
        verify(randomUserClient).getUsers(10);
    }

    @Test
    void getUsers_countExceedsMax_throwsIllegalArgument() {
        UserService service = new UserService(randomUserClient, 5000);

        assertThrows(IllegalArgumentException.class,
                () -> service.getUsers(5001));

        verifyNoInteractions(randomUserClient);
    }
}

The controller tests use @WebMvcTest with MockMvc to verify the full HTTP error mapping chain:

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private UserService userService;

    @Test
    void getUsers_serviceUnavailable_returns503() throws Exception {
        when(userService.getUsers(50))
                .thenThrow(new ExternalApiUnavailableException("API unavailable"));

        mockMvc.perform(get("/api/users"))
                .andExpect(status().isServiceUnavailable())
                .andExpect(jsonPath("$.message")
                        .value("External API is currently unavailable"));
    }
}

View tests:

Common Pitfalls

1. AOP Proxy Bypass

@CircuitBreaker, @Retry, @Cacheable, and @Async are all AOP-based. If you call an annotated method from within the same class, the proxy is bypassed and the annotations are silently ignored. That's why @Retry and @CircuitBreaker live on RandomUserClient, not on UserService — the service calls the client through a Spring proxy.

2. Aspect Order Is Not Annotation Order

I initially assumed that writing @Retry before @CircuitBreaker on the method would make Retry the outer decorator. It doesn't. The annotation order on the method is irrelevant. You must configure aspectOrder properties.

3. Fallback Signature Mismatch

The fallback method must have the exact same parameters as the original method, plus one Exception (or Throwable) parameter at the end. Missing or extra parameters cause a runtime error — not a compile-time one.

4. `@Max` Cannot Reference Properties

I wanted to use @Max for validation with a configurable maximum value from properties. This doesn't work because annotation values must be compile-time constants. The solution: use @Min(1) with @Validated at the controller level for the lower bound, and a manual check with @Value-injected maxCount at the service level for the upper bound.

The Flow Visualized

Client Request
    │
    ▼
UserController (validation: @Min(1))
    │
    ▼
UserService (business validation: count ≤ maxCount)
    │
    ▼
RandomUserClient
    │
    ├── CircuitBreaker [CLOSED] ──► Retry (up to 3 attempts)
    │                                    │
    │                                    ├── Success → return response
    │                                    ├── 5xx/timeout → retry...
    │                                    └── All retries exhausted → CB records failure
    │
    ├── CircuitBreaker [OPEN] ──► fallback → ExternalApiUnavailableException → 503
    │
    └── CircuitBreaker [HALF-OPEN] ──► allow 3 test calls
                                           │
                                           ├── Enough succeed → CLOSED
                                           └── Still failing → OPEN

Key Takeaways

Circuit Breaker should wrap Retry, not the other way around. Configure this with aspectOrder properties — never rely on annotation placement.
Don't retry 4xx errors. Use retry-exceptions and ignore-exceptions to be explicit about what's retryable.
Fallbacks should fail loudly. Throwing an exception in the fallback (rather than returning empty data) keeps behavior transparent to the caller.
Use HttpStatus.resolve() over HttpStatus.valueOf() to avoid crashes on non-standard status codes.
Monitor your circuit breakers via Actuator health endpoints — a circuit stuck in OPEN state is something you want to know about.
Be aware of AOP proxy limitations. Resilience4j annotations only work when the method is invoked through a Spring proxy (i.e., from another bean).

Resources

About the author:
Java Backend Developer with 19+ years of IT experience, building heavy backend financial applications.

Connect:

If you found this article helpful, please leave a reaction ❤️ and follow for more!

How JOIN FETCH Reduced Database Load by 94%: A Real-World Case Study

Taras Antoniuk — Mon, 15 Dec 2025 20:47:42 +0000

🎯 Introduction

The N+1 problem is one of the most common causes of high database load in Spring Boot applications. In this article, I'll show you how to systematically solve this problem using a real-world financial system project.

🔍 What is the N+1 Problem?

The N+1 problem occurs when an ORM generates additional SELECT queries to load related entities.

Example of the Problem

@Entity
public class ExternalExchangeRate {
    @ManyToOne(fetch = FetchType.LAZY)
    private Currency currencyFrom;

    @ManyToOne(fetch = FetchType.LAZY)
    private Currency currencyTo;
}

💡 View ExternalExchangeRate code →

When executing:

List<ExternalExchangeRate> rates = repository.findByExchangeDateAndCurrencyFromId(date, currencyFromId);
for (ExternalExchangeRate rate : rates) {
    System.out.println(rate.getCurrencyFrom().getCode()); // N queries!
    System.out.println(rate.getCurrencyTo().getCode());   // N more queries!
}

Result: 1 + N*2 queries to the database

For example, if we have 15 currency rates for a day:

1 SELECT for rates
15 SELECT for currencyFrom
15 SELECT for currencyTo
Total: 31 queries! 😱

🔬 Detecting the N+1 Problem

Configuration for Development Mode

# application-dev.properties
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.properties.hibernate.generate_statistics=true
spring.jpa.properties.hibernate.use_sql_comments=true
logging.level.org.hibernate.SQL=DEBUG

💡 View application-dev.properties →

Debug Endpoint for Monitoring

@RestController
@RequestMapping("/api/debug")
public class DebugController {

    @Autowired
    private EntityManagerFactory emf;

    @GetMapping("/hibernate-stats")
    public Map<String, Object> getHibernateStats() {
        Statistics stats = emf.unwrap(SessionFactory.class)
                              .getStatistics();

        return Map.of(
            "queriesExecuted", stats.getQueryExecutionCount(),
            "prepareStatementCount", stats.getPrepareStatementCount(),
            "entitiesLoaded", stats.getEntityLoadCount(),
            "entitiesFetched", stats.getEntityFetchCount()
        );
    }
}

💡 View DebugController code →

Measurements BEFORE Optimization

GET /api/external-exchange-rates/latest?date=2024-11-24&currencyFromId=2

Result:
- Time: 48ms
- prepareStatementCount: 33  ← Real SQL statements executed!
- queriesExecuted: 2  ← HQL/JPQL query types
- entitiesLoaded: 131
- entitiesFetched: 31  ← Additional lazy fetches!

💡 Understanding the metrics:

queriesExecuted = HQL/JPQL query types (2 types of queries)

prepareStatementCount = Actual JDBC statement executions (33 SQL queries!)

entitiesFetched = Lazy entity fetches (31 Currency entities loaded separately)

SQL log showed:

-- 1 query for exchange rates
SELECT * FROM external_exchange_rates 
WHERE exchange_date = '2024-11-24' 
AND currency_from_id = 2;

-- 31 additional queries for currencies!
SELECT * FROM currencies WHERE id = 1;
SELECT * FROM currencies WHERE id = 3;
SELECT * FROM currencies WHERE id = 4;
-- ... 28 more queries

✅ When JOIN FETCH Works Perfectly

Flat Data Structure (@ManyToOne)

JOIN FETCH is ideal for flat data structures where an entity has variables that reference only one entity from another table.

Perfect use case example:

@Entity
public class ExternalExchangeRate {
    @Id
    private Long id;

    // Each rate references ONE currency FROM
    @ManyToOne(fetch = FetchType.LAZY)
    private Currency currencyFrom;

    // Each rate references ONE currency TO
    @ManyToOne(fetch = FetchType.LAZY)
    private Currency currencyTo;

    private BigDecimal rate;
}

Why this works perfectly:

1 ExternalExchangeRate → 1 Currency (from)
1 ExternalExchangeRate → 1 Currency (to)
No multiple relationships (@OneToMany)
Pagination works correctly ✅
COUNT query is accurate ✅

⚠️ When JOIN FETCH Is NOT Suitable

Table Parts and Collections (@OneToMany)

JOIN FETCH is NOT an optimal solution when an entity has a variable that references a collection of data (e.g., document line items).

Problematic example:

@Entity
public class Invoice {
    @Id
    private Long id;

    @ManyToOne
    private Customer customer;

    // ⚠️ PROBLEM: Collection of items!
    @OneToMany(mappedBy = "invoice")
    private List<InvoiceItem> items;  // Could be 1, 10, 100+ items!
}

The Problem with Pagination

❌ Wrong approach:

@Query("SELECT DISTINCT i FROM Invoice i " +
       "LEFT JOIN FETCH i.items")  // ⚠️ PROBLEM!
Page<Invoice> findAll(Pageable pageable);

Why this doesn't work:

Cartesian product - 1 Invoice with 10 items → 10 rows in result
Pagination breaks - Page size 20 might return only 2 invoices!
COUNT incorrect - Counts rows after JOIN, not invoices

⚠️ Hibernate Warning

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

This means Hibernate will load all data and apply pagination in memory - losing all benefits!

🔄 Alternatives for Collections

For collections with @OneToMany:

@EntityGraph - Better Hibernate understanding
Two separate queries - Full control
DTO Projection - When details not needed
Batch Fetching - Optimizes multiple queries

📝 Note: I'll cover @EntityGraph in detail in my next article with a real document + line items example.

📊 Comparison Table

Feature	JOIN FETCH (@ManyToOne)	JOIN FETCH (@OneToMany)
Pagination	✅ Works perfectly	❌ Breaks
COUNT accuracy	✅ Correct	❌ Counts rows
Number of queries	✅ 1-2 queries	⚠️ All in memory
Predictability	✅ Stable	❌ Data dependent
Recommendation	✅ Use it	❌ Avoid it

💡 Solution: JOIN FETCH for Flat Structures

Step 1: Creating Optimized Repository Methods

@Repository
public interface ExternalExchangeRateRepository 
        extends JpaRepository<ExternalExchangeRate, Long> {

    /**
     * Find latest rates by date and currency from with currencies loaded.
     * Uses JOIN FETCH to prevent N+1 queries.
     */
    @Query("SELECT e FROM ExternalExchangeRate e " +
           "LEFT JOIN FETCH e.currencyFrom " +
           "LEFT JOIN FETCH e.currencyTo " +
           "WHERE e.exchangeDate = :date " +
           "AND e.currencyFrom.id = :currencyFromId")
    List<ExternalExchangeRate> findLatestRatesByCurrencyFromWithCurrencies(
            @Param("date") LocalDate date,
            @Param("currencyFromId") Long currencyFromId);

    /**
     * Find all exchange rates with currencies loaded in a single query.
     */
    @Query(value = "SELECT DISTINCT e FROM ExternalExchangeRate e " +
           "LEFT JOIN FETCH e.currencyFrom " +
           "LEFT JOIN FETCH e.currencyTo " +
           "ORDER BY e.exchangeDate DESC, e.id DESC",
           countQuery = "SELECT COUNT(e) FROM ExternalExchangeRate e")
    Page<ExternalExchangeRate> findAllWithCurrencies(Pageable pageable);
}

💡 View Repository code →

🔑 Key Points:

DISTINCT - avoids duplicates with JOIN
LEFT JOIN FETCH - loads related entities in one query
countQuery - separate COUNT for pagination (without JOIN)
WithCurrencies suffix - clear method naming

Step 2: Updating the Service

@Service
@Transactional(readOnly = true)
public class ExternalExchangeRateService {

    public List<ExternalExchangeRateResponseDTO> getLatestRatesByDateAndCurrencyFrom(
            LocalDate date, Long currencyFromId) {

        // Using optimized method
        List<ExternalExchangeRate> rates = repository
                .findLatestRatesByCurrencyFromWithCurrencies(date, currencyFromId);

        // No N+1 here, all data is loaded! ✅
        return exchangeRateMapper.toResponseDTOList(rates);
    }
}

💡 View Service →

Step 3: Updating Tests

@Test
void getLatestRatesByDateAndCurrencyFrom_WhenExists_ShouldReturnRates() {
    // Given
    LocalDate date = LocalDate.of(2024, 11, 24);
    Long currencyFromId = 2L;

    // Updated to new method!
    when(exchangeRateRepository.findLatestRatesByCurrencyFromWithCurrencies(date, currencyFromId))
            .thenReturn(List.of(rate1, rate2));

    // When
    List<ExternalExchangeRateResponseDTO> result =
            exchangeRateService.getLatestRatesByDateAndCurrencyFrom(date, currencyFromId);

    // Then
    assertNotNull(result);
    assertEquals(2, result.size());
}

💡 View Tests →

🚀 Optimization Results

Performance Metrics:

Metric	Before	After	Improvement
Response Time	48ms	37ms	23% faster ⚡
SQL Queries	33	2	94% reduction 🎯
Prepare Time	~413μs	~61μs	85% faster ⚡
Execution Time	~15ms	~14ms	Similar
Scalability	O(n*2)	O(1)	Linear → Constant 🚀

🎉 Key Achievement:

✅ N+1 Problem: SOLVED
SQL queries don't depend on record count
For 1000 records: 2001 queries → 2 queries

🤔 Why Only 23% Response Time Improvement?

You might ask: "94% fewer queries but only 23% faster response time?"

The answer:

Small dataset - Only 15 records in our test case
Fast local database - PostgreSQL on localhost responds in ~0.5-1ms per query
Connection pooling - Spring Boot's default HikariCP reuses connections efficiently
Simple queries - SELECT by ID is very fast with proper indexes

Note: While the application has JDBC batching configured (batch_size=1000), it only affects INSERT/UPDATE operations, not SELECT queries.

Real impact shows at scale:

10 records:    11 queries →  2 queries  (similar time)
100 records:  201 queries →  2 queries  (23% faster)
1000 records: 2001 queries → 2 queries  (90%+ faster!) 🚀

💡 Key Insight: The real win is predictable performance regardless of data size! Performance doesn't degrade as data grows.

Measurements AFTER Optimization

GET /api/external-exchange-rates/latest?date=2024-11-24&currencyFromId=2

Result:
- Time: 37ms (23% faster! ⚡)
- prepareStatementCount: 2 (94% less! 🎯)
- queriesExecuted: 1 (only 1 query type now!)
- entitiesFetched: 0 (no additional fetches! ✅)

💡 Key metric: prepareStatementCount dropped from 33 → 2 (94% reduction!)

SQL log:

-- Only 1 query with JOIN! 🎉
SELECT DISTINCT 
    eer.id, eer.exchange_date, eer.rate, eer.source,
    cf.id, cf.code, cf.name, cf.symbol,
    ct.id, ct.code, ct.name, ct.symbol
FROM external_exchange_rates eer
LEFT JOIN currencies cf ON cf.id = eer.currency_from_id
LEFT JOIN currencies ct ON ct.id = eer.currency_to_id
WHERE eer.exchange_date = '2024-11-24'
AND eer.currency_from_id = 2;

🔧 Systematic Optimization of the Entire Project

I optimized 7 core modules with similar approach:

1. ExternalExchangeRate (2 relations)

@Query("SELECT e FROM ExternalExchangeRate e " +
       "LEFT JOIN FETCH e.currencyFrom " +
       "LEFT JOIN FETCH e.currencyTo")

2. Bank (2 relations)

@Query("SELECT b FROM Bank b " +
       "LEFT JOIN FETCH b.country " +
       "LEFT JOIN FETCH b.counterparty")

💡 View Bank module →

3. BankAccount (2 relations)

@Query("SELECT ba FROM BankAccount ba " +
       "LEFT JOIN FETCH ba.bank " +
       "LEFT JOIN FETCH ba.currency")

4. Country (1 relation)

@Query("SELECT c FROM Country c " +
       "LEFT JOIN FETCH c.currency")

💡 View Country entity →

Plus: Counterparty, Organization, and AccountingPolicy ✅

🎯 Best Practices

1. Naming Convention

// Clearly indicate what the method does
findAllWithCurrencies()
findByIdWithRelations()
findLatestRatesByCurrencyFromWithCurrencies()

2. Separate Methods for Different Scenarios

// For reading - with JOIN FETCH ✅
@Query("SELECT b FROM Bank b LEFT JOIN FETCH b.country")
List<Bank> findAllWithCountry();

// For duplicate checks - WITHOUT JOIN (faster!) ⚡
boolean existsBySwiftCode(String swiftCode);

3. DISTINCT for Multiple JOINs

@Query("SELECT DISTINCT e FROM Entity e " +
       "LEFT JOIN FETCH e.relation1 " +
       "LEFT JOIN FETCH e.relation2")

4. Separate countQuery for Pagination

@Query(
    value = "SELECT e FROM Entity e LEFT JOIN FETCH e.relation",
    countQuery = "SELECT COUNT(e) FROM Entity e"  // Without JOIN!
)
Page<Entity> findAllWithRelation(Pageable pageable);

❌ Common Mistakes

Mistake 1: Forgetting DISTINCT

// WITHOUT DISTINCT - may have duplicates! ⚠️
@Query("SELECT e FROM Entity e LEFT JOIN FETCH e.collection")

Mistake 2: JOIN in countQuery

// Slow COUNT due to JOIN! 🐌
countQuery = "SELECT COUNT(e) FROM Entity e LEFT JOIN e.relation"

Mistake 3: Not Updating Tests

// Old method no longer exists! ❌
when(repository.findAll()).thenReturn(list);

Mistake 4: JOIN FETCH with @OneToMany and Pagination

// Breaks pagination! 💥
@Query("SELECT i FROM Invoice i LEFT JOIN FETCH i.items")
Page<Invoice> findAll(Pageable pageable);

🚫 When NOT to Use JOIN FETCH

❌ Collections with pagination
❌ Document table parts
❌ @OneToMany with many records
❌ Duplicate checks
❌ Count queries
❌ Delete operations
❌ Exists checks

📝 Conclusions

Results:

✅ 7 modules optimized

✅ 48 methods with JOIN FETCH

✅ 94% reduction in SQL queries (33 → 2)

✅ 23% improvement in response time (48ms → 37ms)

✅ Scalability: O(n*2) → O(1)

When to Use JOIN FETCH:

✅ Perfect for:

Flat structures (@ManyToOne)
Fixed number of relationships
Pagination without collections
Predictable data sizes

❌ Avoid for:

Collections (@OneToMany) with pagination
Document table parts
Unpredictable data sizes

Next Steps:

📊 Monitor production metrics
💾 Consider caching for frequent queries
🔍 Explore @EntityGraph for collections (next article!)
⚡ Optimize batch operations

🔗 Useful Resources

🚀 About the Project

Financial Accounting System

Tech Stack: Java 21, Spring Boot 3.5.5, PostgreSQL, Docker
Architecture: Event Sourcing
Features: ECB exchange rate sync, CI/CD pipeline, SSL
Swagger API: https://api.tarasantoniuk.com/swagger-ui/index.html

📖 View Project on GitHub →

Coming Next: "Optimizing N+1 for Collections with @EntityGraph" 🔜

This article was created based on real production experience with 19+ years in enterprise development. 👨‍💻

💬 Questions? Drop them in the comments!

⭐ Found it helpful? Give the repo a star!

🔔 Want more? Follow for the next article on @EntityGraph!

👨‍💻 About the Author

Taras Antoniuk

Java Backend Developer | 19+ years IT experience

📧 bronya2004@gmail.com

🔗 LinkedIn

💻 HackerRank (5⭐ SQL, Java, Collections)

🌐 Production API

How Pagination Saved an API from Crashing: A Practical Case Study

Taras Antoniuk — Mon, 24 Nov 2025 09:10:49 +0000

The Problem That Inspired This Article

Recently, I encountered an interesting situation. I opened a certain web resource (which I won't name) and tried to view a list of data. The page started loading... and loading... and the browser froze.

After restarting the page and opening DevTools, the picture became clear: the API endpoint was returning all records in a single request - tens of thousands of rows in a JSON response over 50 MB in size. The browser simply couldn't handle it.

Testing the request through Postman confirmed my suspicions:

GET /api/items
Response: [
  { "id": 1, "name": "Item 1" },
  { "id": 2, "name": "Item 2" },
  ...
  { "id": 50000, "name": "Item 50000" }
]
// 50 MB JSON, response time: 12 seconds

This incident prompted me to write an article about how to properly solve such problems. Using my open-source project finance as an example, I'll show how to implement pagination to avoid these situations from the start.

Target audience: This article is aimed at beginner and mid-level developers who want to learn how to properly design REST APIs with real-world loads in mind. If you've worked with Spring Boot but never added pagination - this article is for you.

The Problem with Non-Paginated Endpoints

When an API endpoint returns all data in a single request, serious problems arise:

For the server:

High database load
High memory consumption
Slow response (seconds instead of milliseconds)

For the client:

Long loading times
Large network traffic
Possible browser freezing

For the business:

Poor user experience
High infrastructure costs
Scalability issues

Solution: Pagination

Pagination is a technique for splitting large datasets into smaller chunks (pages) that are loaded on demand. Instead of returning all 200,000 records at once, the API returns, for example, 20-50 records per page.

Benefits of pagination:

For the server:

Reduced database load
Less memory for request processing
Faster response

For the client:

Fast data loading
Less network traffic
Better UX (user sees data faster)

For the business:

Lower infrastructure costs
Ability to scale
Better system performance

Practical Implementation in Spring Boot

Let's look at an example of pagination implementation in an accounting system prototype. Full code is available on GitHub.

The financial application has endpoints that can potentially return large amounts of data:

/api/exchange-rates - historical exchange rates (200,000+ records)
/api/counterparties - list of counterparties (can grow to thousands of records)

Let's see how to properly implement pagination for such endpoints.

Step 1: Creating Base DTOs for Pagination

First, we need two data structures that will be reusable for all endpoints:

PageMetadata.java - page metadata:

public class PageMetadata {
    private int currentPage;        // Current page (0-based)
    private int totalPages;         // Total number of pages
    private int pageSize;           // Number of records per page
    private long totalElements;     // Total number of records
    private boolean hasNext;        // Whether there is a next page
    private boolean hasPrevious;    // Whether there is a previous page

    // Constructors, getters, setters, builder
}

PageResponse.java - data wrapper:

public class PageResponse<T> {
    private List<T> content;        // Current page data
    private PageMetadata metadata;  // Pagination metadata

    // Constructors, getters, setters, builder
}

View code on GitHub

Step 2: Updating the Repository

Spring Data JPA already has built-in pagination support through the Pageable interface:

public interface ExchangeRateRepository extends JpaRepository<ExternalExchangeRate, Long> {
    // Spring Data automatically provides the method:
    // Page<ExternalExchangeRate> findAll(Pageable pageable);

    // For custom queries:
    Page<ExternalExchangeRate> findByCurrencyFromIdAndCurrencyToId(
        Long currencyFromId, Long currencyToId, Pageable pageable);
}

View full Repository code

Step 3: Service Layer Implementation

@Service
public class ExternalExchangeRateService {

    private final ExternalExchangeRateRepository repository;
    private final ExternalExchangeRateMapper mapper;

    @Transactional(readOnly = true)
    public PageResponse<ExchangeRateResponseDTO> getAllExchangeRates(
            int page, int size) {

        // Create Pageable with sorting
        Pageable pageable = PageRequest.of(page, size,
            Sort.by(Sort.Direction.DESC, "exchangeDate", "id"));

        // Query database with pagination
        Page<ExternalExchangeRate> ratePage = repository.findAll(pageable);

        // Map entity → DTO
        List<ExchangeRateResponseDTO> dtos = ratePage.getContent()
            .stream()
            .map(mapper::toResponseDTO)
            .toList();

        // Collect metadata
        PageMetadata metadata = PageMetadata.builder()
            .currentPage(ratePage.getNumber())
            .totalPages(ratePage.getTotalPages())
            .pageSize(ratePage.getSize())
            .totalElements(ratePage.getTotalElements())
            .hasNext(ratePage.hasNext())
            .hasPrevious(ratePage.hasPrevious())
            .build();

        // Return result
        return PageResponse.<ExchangeRateResponseDTO>builder()
            .content(dtos)
            .metadata(metadata)
            .build();
    }
}

View full Service code

Step 4: REST Controller

@RestController
@RequestMapping("/api/exchange-rates")
public class ExternalExchangeRateController {

    private final ExternalExchangeRateService service;

    @GetMapping
    @Operation(
        summary = "Get all exchange rates",
        description = """
            Retrieve paginated list of exchange rates, sorted by date (newest first).

            Examples:
            - GET /api/exchange-rates (first page, default settings)
            - GET /api/exchange-rates?page=1 (second page)
            - GET /api/exchange-rates?page=0&size=100 (custom page size)
            """
    )
    public ResponseEntity<PageResponse<ExchangeRateResponseDTO>> getAllExchangeRates(
            @Parameter(description = "Page number (0-based)")
            @RequestParam(defaultValue = "0") int page,

            @Parameter(description = "Items per page")
            @RequestParam(defaultValue = "200") int size,

            @Parameter(description = "Maximum allowed page size")
            @RequestParam(defaultValue = "500") int maxSize) {

        // Protection against abuse
        if (size > maxSize) {
            size = maxSize;
        }

        PageResponse<ExchangeRateResponseDTO> response = 
            service.getAllExchangeRates(page, size);

        return ResponseEntity.ok(response);
    }
}

View full Controller code

Step 5: Database Optimization - Indexes

For efficient pagination with sorting, indexes are required:

@Entity
@Table(
    name = "external_exchange_rates",
    indexes = {
        @Index(name = "idx_exchange_rate_date_id", 
               columnList = "exchange_date, id")
    }
)
public class ExternalExchangeRate extends BaseEntity {
    // entity fields
}

View full Entity code

The composite index (exchange_date, id) provides:

Fast sorting by date
Stable sorting (via ID)
Efficient OFFSET/LIMIT queries

API Results

💡 Live Demo: Want to see the results in practice? Test the API right now through Swagger UI - try different page and size values and see the response speed!

Example of non-paginated endpoint (like that web resource):

GET /api/items
Response Time: 8-12 seconds
Response Size: 45 MB
[
  { "id": 1, "date": "2024-01-01", "rate": 0.92 },
  { "id": 2, "date": "2024-01-02", "rate": 0.93 },
  ...
  { "id": 200000, "date": "2024-11-20", "rate": 0.91 }
]

Example of paginated endpoint:

GET /api/exchange-rates?page=0&size=200
Response Time: 150-300ms
Response Size: 45 KB
{
  "content": [
    { "id": 200000, "date": "2024-11-20", "rate": 0.91 },
    { "id": 199999, "date": "2024-11-19", "rate": 0.90 },
    ...
    { "id": 199800, "date": "2024-05-15", "rate": 0.89 }
  ],
  "metadata": {
    "currentPage": 0,
    "totalPages": 1000,
    "pageSize": 200,
    "totalElements": 200000,
    "hasNext": true,
    "hasPrevious": false
  }
}

Improvement:

⚡ Speed: 40x faster (8-12s → 150-300ms)
📉 Response size: 1000x smaller (45 MB → 45 KB)
💾 Memory: 10x less (~500MB → ~50MB)

Best Practices

1. Reasonable Default Values

// For historical data (exchange rates)
defaultValue = "200"
maxSize = "500"

// For UI-oriented endpoints (counterparties)
defaultValue = "50"
maxSize = "500"

Note: This project uses larger values than standard because it matches the specifics of financial data and system needs. However, for most cases, it's recommended to base on industry standards:

GitHub API: default 30, max 100
Twitter API: default 20, max 200
Stripe API: default 10, max 100

2. Protection Against Abuse

Always set maxSize:

if (size > maxSize) {
    size = maxSize;
}

3. Proper Sorting

// For time series - newest first
Sort.by(Sort.Direction.DESC, "exchangeDate", "id")

// For reference data - alphabetical order
Sort.by(Sort.Direction.ASC, "name", "id")

Always add secondary sorting by id for stability.

4. Consistent Response Structure

Use a single PageResponse<T> structure for all endpoints - frontend developers will appreciate it.

Testing

Full test coverage is critical:

@Test
void getAllExchangeRates_ShouldReturnPagedRates() {
    // Given
    Pageable pageable = PageRequest.of(0, 200);
    Page<ExternalExchangeRate> page = new PageImpl<>(rates, pageable, 1000);

    when(repository.findAll(any(Pageable.class))).thenReturn(page);

    // When
    PageResponse<ExchangeRateResponseDTO> result = service.getAllExchangeRates(0, 200);

    // Then
    assertEquals(200, result.getContent().size());
    assertEquals(0, result.getMetadata().getCurrentPage());
    assertEquals(5, result.getMetadata().getTotalPages());
    assertTrue(result.getMetadata().isHasNext());
}

Tests should verify:

✅ Basic pagination
✅ Metadata (hasNext, hasPrevious)
✅ Empty results
✅ Sorting
✅ MaxSize limits

View tests:

Test results: 99% line coverage, 97% branch coverage

Conclusions

That web resource that froze could have avoided the problem by simply adding pagination. Implementing pagination in Spring Boot is not technically complex, but it's critical for production systems.

Key takeaways:

Always add pagination for endpoints that return collections
Set reasonable defaults (50-200 records)
Limit maxSize to protect against abuse
Add indexes for sorting
Test thoroughly - 99% coverage is a quality standard

Don't wait for your API to crash under load - add pagination at the design stage. Your users (and server) will thank you.

Resources

About the author:

Java Backend Developer with 19+ years of IT experience, building heavy backend financial applications.

Connect:

If you found this article helpful, please leave a reaction ❤️ and follow for more!

JaCoCo for Java Developers: Measuring and Improving Code Coverage

Taras Antoniuk — Mon, 03 Nov 2025 16:15:56 +0000

Testing and Code Coverage Guide

Why Testing Matters

Testing is crucial for software quality. It helps us:

Catch bugs early before they reach production
Refactor code with confidence
Document how code should behave
Maintain code quality over time

But testing alone isn't enough. We also need to know how much of our code is actually tested. That's where code coverage comes in.

What is Code Coverage?

Code coverage measures which parts of your code are executed during tests. It shows:

Line coverage: Percentage of code lines executed
Branch coverage: Percentage of decision branches (if/else) tested

Example: If you have 100 lines of code and tests execute 80 of them, you have 80% line coverage.

Our Testing Approach

We use:

JUnit 5 for writing tests
Testcontainers for integration tests with real database
JaCoCo for measuring code coverage

Coverage standards:

80% line coverage minimum
75% branch coverage minimum

JaCoCo in Action: Real Example

Let's see how we implemented code coverage in this project.

Live Example: You can see the complete implementation in my repository:

https://github.com/TarasAntoniuk/finance-core

Step 1: Add JaCoCo to Maven

In pom.xml, we added the JaCoCo plugin:

<properties>
    <jacoco.version>0.8.12</jacoco.version>
    <jacoco.line.coverage>0.80</jacoco.line.coverage>
    <jacoco.branch.coverage>0.75</jacoco.branch.coverage>
</properties>

<build>
    <plugins>
        <plugin>
            <groupId>org.jacoco</groupId>
            <artifactId>jacoco-maven-plugin</artifactId>
            <version>${jacoco.version}</version>
            <executions>
                <execution>
                    <id>prepare-agent</id>
                    <goals>
                        <goal>prepare-agent</goal>
                    </goals>
                </execution>
                <execution>
                    <id>report</id>
                    <phase>test</phase>
                    <goals>
                        <goal>report</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Step 2: Exclude Non-Business Code

Not all code needs testing. We excluded:

Configuration classes (just Spring setup)
DTOs and entities (simple data holders)
MapStruct generated mappers
Exception classes

<configuration>
    <excludes>
        <exclude>**/*Config.class</exclude>
        <exclude>**/dto/**</exclude>
        <exclude>**/entity/**</exclude>
        <exclude>**/mapper/**</exclude>
        <exclude>**/exception/**</exclude>
    </excludes>
</configuration>

Step 3: Run Tests and View Coverage

# Run tests with coverage
mvn clean test

# Open HTML report
open target/site/jacoco/index.html

The report shows:

Overall coverage percentage
Which classes are well-tested (green)
Which need more tests (red/yellow)
Line-by-line coverage details

Step 4: Add Coverage Badges to GitHub

We created a separate GitHub Actions workflow that:

Runs tests on every push
Generates coverage badges
Commits badges to repository
Displays them in README

Workflow (.github/workflows/test-coverage.yml):

- name: Run tests with coverage
  run: mvn clean test

- name: Generate JaCoCo Badge
  uses: cicirello/jacoco-badge-generator@v2
  with:
    badges-directory: .github/badges

Result in README.md:

![Coverage](.github/badges/jacoco.svg)
![Branches](.github/badges/branches.svg)

Now everyone can see test coverage at a glance! 📊

Step 5: Enforce Coverage in CI (Optional)

We can make the build fail if coverage drops below our standards:

<profile>
    <id>ci</id>
    <build>
        <plugins>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>check-coverage</id>
                        <goals>
                            <goal>check</goal>
                        </goals>
                        <configuration>
                            <rules>
                                <rule>
                                    <limits>
                                        <limit>
                                            <counter>LINE</counter>
                                            <minimum>0.80</minimum>
                                        </limit>
                                    </limits>
                                </rule>
                            </rules>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</profile>

Run with: mvn verify -P ci

Key Takeaways

Test your business logic — that's where bugs hide
Measure coverage — know what's tested and what isn't
Don't chase 100% — focus on meaningful tests, not numbers
Automate — let CI/CD run tests and report coverage
Make it visible — badges help track progress

Testing takes time upfront but saves much more time debugging production issues later.

Quick Commands Reference

# Run tests
mvn test

# View coverage report
open target/site/jacoco/index.html

# Run with coverage enforcement
mvn verify -P ci

Resources:

Document Version: 0.0.2

Last Updated: November 2025

DEV Community: Taras Antoniuk

Spring Security Beyond the Login Form: Data Isolation and the 401/403 Contract

Why This Article Exists

The Network Was Your Authorization Layer

The Identity You Issue Decides How Hard Everything Else Is

A Refresh Token Is Not a Response Field

Authorization Rules: First Match Wins

The Half That Actually Matters: Data Isolation

Error Semantics Are a Contract

What You Still Need Once There Is No Perimeter

Common Pitfalls

1. Rule order silently opens holes

2. Cookies plus CORS look like a CORS bug

3. Filtering in memory instead of in the query

4. Your catch-all handler predates your security layer

5. Parsing your own claims can throw

The Flow Visualized

Key Takeaways

Try It Yourself

Resources

Circuit Breaker + Retry in Spring Boot: A Practical Guide with Resilience4j

Why This Article Exists

The Setup

Adding Resilience4j

The Circuit Breaker + Retry Combination

The Aspect Order Trap

The Client Implementation

The 4xx vs 5xx Retry Problem

Full Circuit Breaker Configuration

Monitoring with Spring Boot Actuator

Exception Hierarchy and Global Error Handling

Testing the Resilience Layer

Common Pitfalls

1. AOP Proxy Bypass

2. Aspect Order Is Not Annotation Order

3. Fallback Signature Mismatch

4. @Max Cannot Reference Properties

The Flow Visualized

Key Takeaways

Resources

How JOIN FETCH Reduced Database Load by 94%: A Real-World Case Study

🎯 Introduction

🔍 What is the N+1 Problem?

Example of the Problem

🔬 Detecting the N+1 Problem

Configuration for Development Mode

Debug Endpoint for Monitoring

Measurements BEFORE Optimization

✅ When JOIN FETCH Works Perfectly

Flat Data Structure (@ManyToOne)

⚠️ When JOIN FETCH Is NOT Suitable

Table Parts and Collections (@OneToMany)

The Problem with Pagination

⚠️ Hibernate Warning

🔄 Alternatives for Collections

📊 Comparison Table

💡 Solution: JOIN FETCH for Flat Structures

Step 1: Creating Optimized Repository Methods

🔑 Key Points:

Step 2: Updating the Service

Step 3: Updating Tests

🚀 Optimization Results

Performance Metrics:

🎉 Key Achievement:

🤔 Why Only 23% Response Time Improvement?

Measurements AFTER Optimization

🔧 Systematic Optimization of the Entire Project

1. ExternalExchangeRate (2 relations)

2. Bank (2 relations)

3. BankAccount (2 relations)

4. Country (1 relation)

🎯 Best Practices

1. Naming Convention

2. Separate Methods for Different Scenarios

3. DISTINCT for Multiple JOINs

4. Separate countQuery for Pagination

❌ Common Mistakes

Mistake 1: Forgetting DISTINCT

Mistake 2: JOIN in countQuery

Mistake 3: Not Updating Tests

4. `@Max` Cannot Reference Properties