Resilience4j for Java: Complete Guide with Examples

What is Resilience4j and why is it needed?

Resilience4j is a lightweight library for Java designed to improve the fault tolerance (resilience) of microservices and distributed systems. It provides a set of ready-made components that help protect your application from cascading failures, overloads, and slow responses from external services (databases, APIs, message queues, etc.).

The main task of the library is to implement fault tolerance patterns such as Circuit Breaker (automatic shutdown of a problematic service), Rate Limiter (limiting request frequency), Retry (retry attempts), Bulkhead (resource isolation), Time Limiter (execution time limit), and Cache (caching results).

The library fits perfectly into the Spring Boot ecosystem but can also be used in any other Java application. Resilience4j is considered a modern replacement for the outdated Hystrix library from Netflix.

Installation (Maven/Gradle)

Resilience4j is a Java library, so it is installed via Maven or Gradle build systems. Unlike Python, the pip install command is not used here.

Maven (pom.xml)

<dependency>\n    <groupId>io.github.resilience4j</groupId>\n    <artifactId>resilience4j-all</artifactId>\n    <version>2.2.0</version>\n</dependency>\n\n<!-- For Spring Boot additionally -->\n<dependency>\n    <groupId>io.github.resilience4j</groupId>\n    <artifactId>resilience4j-spring-boot3</artifactId>\n    <version>2.2.0</version>\n</dependency>

Gradle (build.gradle)

implementation 'io.github.resilience4j:resilience4j-all:2.2.0'\nimplementation 'io.github.resilience4j:resilience4j-spring-boot3:2.2.0'

Quick Start with Code Example

Let's create a simple example of using Circuit Breaker. Suppose we have a method that calls an external API. We want that if the API responds with an error 5 times in a row, subsequent calls instantly return a fallback value without loading the problematic service.

import io.github.resilience4j.circuitbreaker.CircuitBreaker;\nimport io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;\nimport io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry;\nimport java.time.Duration;\nimport java.util.function.Supplier;\n\npublic class QuickStartExample {\n\n    public static void main(String[] args) {\n        // 1. Create Circuit Breaker configuration\n        CircuitBreakerConfig config = CircuitBreakerConfig.custom()\n                .failureRateThreshold(50) // Error threshold in percent\n                .waitDurationInOpenState(Duration.ofMillis(1000)) // Time in open state\n                .slidingWindowSize(5) // Sliding window size for error counting\n                .build();\n\n        // 2. Create registry and Circuit Breaker\n        CircuitBreakerRegistry registry = CircuitBreakerRegistry.of(config);\n        CircuitBreaker circuitBreaker = registry.circuitBreaker("myService");\n\n        // 3. Wrap the risky call\n        Supplier<String> decoratedSupplier = CircuitBreaker\n                .decorateSupplier(circuitBreaker, QuickStartExample::riskyOperation);\n\n        // 4. Execute multiple times\n        for (int i = 0; i < 10; i++) {\n            try {\n                String result = decoratedSupplier.get();\n                System.out.println("Success: " + result);\n            } catch (Exception e) {\n                System.out.println("Error: " + e.getMessage());\n            }\n        }\n    }\n\n    // Simulating an unreliable external service\n    public static String riskyOperation() {\n        if (Math.random() > 0.3) {\n            throw new RuntimeE