= 함수형 프로그래밍을 위해 설계된 내결함성 라이브러리 :author: Robert Winkler and Bohdan Storozhuk :icons: :toc: macro :numbered: 1 ifdef::env-github[] :tip-caption: 💡 :note-caption: ℹ️ :important-caption: ❗ :caution-caption: 🔥 :warning-caption: ⚠️ endif::[]

image:https://github.com/resilience4j/resilience4j/actions/workflows/gradle-build.yml/badge.svg["Build Status"] image:https://img.shields.io/nexus/r/io.github.resilience4j/resilience4j-circuitbreaker?server=https%3A%2F%2Foss.sonatype.org["Release"] image:https://img.shields.io/nexus/s/io.github.resilience4j/resilience4j-circuitbreaker?server=https%3A%2F%2Foss.sonatype.org["Snapshot"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"]

image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=coverage["Coverage", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=sqale_rating["Maintainability", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=reliability_rating["Reliability", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=security_rating["Security", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=vulnerabilities["Vulnerabilities", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=bugs["Bugs", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"]

image:https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg["SWUbanner",link="https://vshymanskyy.github.io/StandWithUkraine"]

toc::[]

== 소개

Resilience4j는 함수형 프로그래밍을 위해 설계된 경량 내결함성 라이브러리입니다. Resilience4j는 고차 함수(데코레이터)를 제공하여 모든 함수형 인터페이스, 람다 표현식 또는 메서드 참조를 회로 차단기(Circuit Breaker), 속도 제한기(Rate Limiter), 재시도(Retry) 또는 벌크헤드(Bulkhead)로 강화할 수 있게 해줍니다. 어떤 함수형 인터페이스, 람다 표현식 또는 메서드 참조에도 데코레이터를 여러 개 쌓을 수 있습니다. 장점은 필요한 데코레이터만 선택할 수 있고 그 외에는 아무것도 필요하지 않다는 것입니다.

Resilience4j 3는 Java 21이 필요합니다.

[source,java]

// Create a CircuitBreaker with default configuration CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("backendService");

// Create a Retry with default configuration // 3 retry attempts and a fixed time interval between retries of 500ms Retry retry = Retry.ofDefaults("backendService");

// Create a Bulkhead with default configuration Bulkhead bulkhead = Bulkhead.ofDefaults("backendService");

Supplier supplier = () -> backendService .doSomething(param1, param2);

// Decorate your call to backendService.doSomething() // with a Bulkhead, CircuitBreaker and Retry // **note: you will need the resilience4j-all dependency for this Supplier decoratedSupplier = Decorators.ofSupplier(supplier) .withCircuitBreaker(circuitBreaker) .withBulkhead(bulkhead) .withRetry(retry) .decorate();

// Execute the decorated supplier and recover from any exception String result = Try.ofSupplier(decoratedSupplier) .recover(throwable -> "Hello from Recovery").get();

// When you don't want to decorate your lambda expression, // but just execute it and protect the call by a CircuitBreaker. String result = circuitBreaker .executeSupplier(backendService::doSomething);

// You can also run the supplier asynchronously in a ThreadPoolBulkhead ThreadPoolBulkhead threadPoolBulkhead = ThreadPoolBulkhead .ofDefaults("backendService");

// The Scheduler is needed to schedule a timeout on a non-blocking CompletableFuture ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(3); TimeLimiter timeLimiter = TimeLimiter.of(Duration.ofSeconds(1));

CompletableFuture future = Decorators.ofSupplier(supplier) .withThreadPoolBulkhead(threadPoolBulkhead) .withTimeLimiter(timeLimiter, scheduler) .withCircuitBreaker(circuitBreaker) .withFallback(asList(TimeoutException.class, CallNotPermittedException.class, BulkheadFullException.class), throwable -> "Hello from Recovery") .get().toCompletableFuture();

NOTE: Resilience4j를 사용하면 모든 것을 한 번에 적용할 필요가 없습니다. https://mvnrepository.com/artifact/io.github.resilience4j[*필요한 것만 선택*]할 수 있습니다.

== 문서

설정 및 사용 방법은 *https://resilience4j.readme.io/docs[사용자 가이드]*에 설명되어 있습니다.

• https://github.com/resilience4j-docs-ja/resilience4j-docs-ja[有志による日本語訳(非公式) Japanese translation by volunteers(Unofficial)]

• https://github.com/lmhmhl/Resilience4j-Guides-Chinese[这是Resilience4j的非官方中文文档 Chinese translation by volunteers(Unofficial)]

== 개요

Resilience4j는 여러 핵심 모듈을 제공합니다:

• resilience4j-circuitbreaker: 회로 차단
• resilience4j-ratelimiter: 속도 제한
• resilience4j-bulkhead: 벌크헤딩
• resilience4j-retry: 자동 재시도(동기 및 비동기)
• resilience4j-timelimiter: 타임아웃 처리
• resilience4j-cache: 결과 캐싱

메트릭, Feign, Kotlin, Spring, Ratpack, Vertx, RxJava2 등을 위한 추가 모듈도 있습니다.

NOTE: 전체 모듈 목록은 *https://resilience4j.readme.io/docs#section-modularization[사용자 가이드]*에서 확인하세요.

TIP: 핵심 모듈 패키지 또는 +Decorators+ 빌더는 *https://mvnrepository.com/artifact/io.github.resilience4j/resilience4j-all[resilience4j-all]*을 참조하세요.

== 모범 사례

=== 인스턴스 관리: 인스턴스를 공유해야 하는 경우와 공유하지 말아야 하는 경우

새로 배우는 사용자가 이해해야 할 가장 중요한 개념 중 하나는 언제 별도의 인스턴스를 만들고 언제 서로 다른 원격 서비스 또는 백엔드 간에 인스턴스를 공유할지입니다.

[IMPORTANT]

핵심 원칙: 통신하는 각 보호 대상 원격 서비스 또는 백엔드마다 고유한 ID를 가진 인스턴스를 하나씩 생성하세요.

==== 고유 인스턴스가 중요한 이유

백엔드 서비스마다 별도의 인스턴스를 만드는 것은 다음 이유로 중요합니다:

1. 정확한 메트릭 수집 - 각 인스턴스가 자체 메트릭을 추적하므로 개별 서비스의 상태를 모니터링할 수 있습니다.
2. 장애 격리 - 서비스 A가 실패해도 서비스 B를 보호하는 복원력 패턴에는 영향을 미치지 않습니다.
3. 독립적인 구성 - 백엔드마다 서로 다른 회로 차단기 임계값, 동시성 제한, 속도 제한 또는 재시도 정책이 필요할 수 있습니다.

==== 인스턴스 인식 패턴과 인스턴스 비인식 패턴

복원력 패턴마다 인스턴스 분리에 대한 요구 사항이 다릅니다:

===== 인스턴스 인식 패턴 (반드시 공유 금지)

이러한 패턴은 특정 서비스에 고유한 상태를 유지하므로 반드시 별도의 인스턴스가 있어야 합니다:

• CircuitBreaker - 서비스별 실패율과 상태(OPEN/CLOSED/HALF_OPEN)를 추적합니다.

[source,java]

// CORRECT: Separate CircuitBreaker for each service CircuitBreaker paymentServiceCB = CircuitBreaker.ofDefaults("paymentService"); CircuitBreaker inventoryServiceCB = CircuitBreaker.ofDefaults("inventoryService"); CircuitBreaker notificationServiceCB = CircuitBreaker.ofDefaults("notificationService");

// WRONG: Sharing one CircuitBreaker across multiple services CircuitBreaker sharedCB = CircuitBreaker.ofDefaults("shared"); // DON'T DO THIS! // If one service fails, the circuit opens for ALL services!

• Bulkhead (SemaphoreBulkhead 및 ThreadPoolBulkhead 모두) - 서비스별 동시 호출 한도를 관리합니다.

[source,java]

// CORRECT: Separate Bulkhead for each service Bulkhead paymentBulkhead = Bulkhead.ofDefaults("paymentService"); Bulkhead inventoryBulkhead = Bulkhead.ofDefaults("inventoryService");

// WRONG: Sharing limits resource isolation benefits Bulkhead sharedBulkhead = Bulkhead.ofDefaults("shared"); // DON'T DO THIS!

• RateLimiter - 서비스별 요청 속도를 제어합니다.

[source,java]

// CORRECT: Different rate limits for different services RateLimiter apiRateLimiter = RateLimiter.ofDefaults("externalAPI"); RateLimiter dbRateLimiter = RateLimiter.ofDefaults("database");

===== 인스턴스 비인식 패턴 (공유할 수는 있지만 권장하지 않음)

이러한 패턴은 각 실행마다 새로운 컨텍스트를 생성하며 서비스별 상태를 유지하지 않습니다:

• Retry - 구성을 공유할 수 있지만 정확한 메트릭을 위해 고유 인스턴스를 여전히 권장합니다.
• TimeLimiter - 타임아웃 설정이 여러 서비스에서 동일하다면 공유할 수 있습니다.

[source,java]

// TECHNICALLY OK: Retry doesn't maintain state between calls Retry sharedRetry = Retry.ofDefaults("shared");

// BETTER: Unique instances provide better metrics and monitoring Retry paymentRetry = Retry.ofDefaults("paymentService"); Retry inventoryRetry = Retry.ofDefaults("inventoryService");