DEV Community: Taras Antoniuk

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

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

Mistake 4: JOIN FETCH with @OneToMany and Pagination

🚫 When NOT to Use JOIN FETCH

📝 Conclusions

Results:

When to Use JOIN FETCH:

Next Steps:

🔗 Useful Resources

🚀 About the Project

👨‍💻 About the Author

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

The Problem That Inspired This Article

The Problem with Non-Paginated Endpoints

Solution: Pagination

Benefits of pagination:

Practical Implementation in Spring Boot

Step 1: Creating Base DTOs for Pagination

Step 2: Updating the Repository

Step 3: Service Layer Implementation

Step 4: REST Controller

4. `@Max` Cannot Reference Properties