[Resilience4j] 장애 허용성을 위한 라이브러리 소개와 사용법 (자바 스프링 부트)

시스템 장애에 대한 선수 지식이 있어야지 이 글을 이해할 수 있습니다.

 

https://konkukcodekat.tistory.com/240

장애허용성과 TMR, 프로세스 그룹의 개념 설명 (Fault Tolerance, Process Group)

---

Resilience4j가 왜 필요한가?

Resilience4j는 마이크로서비스나 분산 시스템에서 여러 외부 서비스(API, DB, 다른 마이크로서비스 등)와 통신할 때, 네트워크 오류나 외부 시스템 장애와 같은 불안정성에 효과적으로 대응하기 위한 라이브러리입니다.

이런 장애가 개별 서비스 뿐 아니라 전체 시스템 장애로 확산되는 것을 막고, 서비스의 신뢰성 복원력을 높여줍니다.

Retry 예시: Intermittent Failure

Retry 패턴은 "간헐적 장애(Intermittent Failure)"에 대응합니다.

어떤 서비스에서 외부 결제 API 호출 시 간혹 네트워크 불안이나 서버 과부하 등으로 인해 1~2초 정도 '일시적'으로 실패가 발생할 수 있습니다.

이런 경우 Retry를 적용해 자동으로 요청을 재시도하면, 첫 번째 시도는 실패해도 2~3회 시도 끝에 정상 처리될 가능성이 높아집니다.

이로 인해 실제 업무 처리 성공률이 크게 올라가고, 사용자 경험도 개선됩니다.

CircuitBreaker 예시: 상품저장소와 리뷰 저장소

CircuitBreaker는 Permanent Fault가 발생하는 외부 서비스로부터 시스템 전체 장애로 번지는 것을 막는 패턴입니다.

한 쇼핑몰 서비스에서 "상품 저장"과 "리뷰 저장"을 처리해야 하는 상황이 있습니다.

만약 "리뷰 저장소"가 반복적으로 장애를 일으킨다고 해서, 상품 자체 저장까지 모두 실패하면 전체 서비스가 다운되는 결과가 나올 수 있습니다.

이 때 CircuitBreaker를 적용하면, 리뷰 저장소에 장애가 지속적으로 발생할 경우 서킷이 열려 더 이상 해당 서비스에 요청을 보내지 않도록 격리합니다.

그러면 "상품 저장고" 기능은 정상적으로 동작하고, 리뷰 저장소의 장애가 시스템 전체로 확산되는 것을 막을 수 있습니다. 손님은 상품 저장은 여전히 할 수 있습니다.

 

---

Resilience4j 주요 개념과 기능

Resilience4j는 아래와 같은 복원력 패턴(Resilience Patterns)을 지원합니다.

패턴 이름	설명
Circuit Breaker	장애가 반복될 때 더 이상 요청을 멈추고, 일정 시간 후 다시 시도하는 패턴(서킷이 열림/닫힘/반개방 등)
Rate Limiter	시간당/초당 처리 요청의 최대 수량을 제한하여 시스템 오버로드를 방지
Bulkhead	특정 작업을 격리시켜 장애가 시스템 전체로 확산되는 것을 막음 (스레드/풀 분리)
Retry	실패 시 지정된 횟수/간격으로 재시도하여 일시적인 장애 극복
TimeLimiter	메서드 실행 시간 제한(타임아웃)
Fallback	장애 발생 혹은 모든 재시도 실패 시 대체 로직(fallback)을 실행
Cache	저장된 데이터로 실패 혹은 느린 응답을 보완
Event Registry	각 패턴의 상태 변화, 성공/실패 이벤트 등 모니터링 가능

 

---

Resilience4j 설정 방법

application yaml 작성 방법:

resilience4j.retry:
  configs:   # 여러 설정(템플릿) 집합
    default: # 'default'라는 이름의 설정 템플릿
      ...
  instances: # 각각의 인스턴스별 실제 적용 객체 (여러 서비스 별로 각각 적용 가능)
    simpleRetryConfig: # 인스턴스 이름
      baseConfig: default # 위 configs에서 정의한 템플릿을 기반으로 실제 인스턴스 생성

• configs: ‘템플릿’ 역할. 반복적으로 사용하는 설정들을 이름(default 등)으로 따로 정리—여러 곳에 재사용 가능.
• instances: 실제 적용될 객체의 별칭. 각 비즈니스 로직이나 서비스별로 독립적으로 사용할 수 있게 이름을 분리해 사용.
• 인스턴스는 baseConfig 속성으로 특정 템플릿(configs의 default 등)을 참조합니다.
• 인스턴스 이름(예: simpleRetryConfig, simpleCircuitBreakerConfig, simpleRateLimiter)은 실제 코드의 어노테이션에서 name 파라미터로 사용됩니다.

java spring에서 함수에 적용 방법:

// application.yml에 인스턴스 이름: simpleRetryConfig
@Retry(name = "simpleRetryConfig", fallbackMethod = "fallback")
public void someMethod() { ... }

// CircuitBreaker
@CircuitBreaker(name = "simpleCircuitBreakerConfig", fallbackMethod = "fallback")
public void anotherMethod() { ... }

// RateLimiter
@RateLimiter(name = "simpleRateLimiter")
public void limitedMethod() { ... }

• 이처럼 YAML에서 정의한 인스턴스의 이름이 코드에서 연결되어 동작합니다.
• 만약 name 값을 잘못 입력하면 설정이 적용되지 않거나, 기본 설정만 적용됩니다.

역할	예시 이름	코드에서 사용하는 위치
config	default	baseConfig로 참조
instance	simpleRetryConfig	@Retry(name="simpleRetryConfig")
instance	simpleCircuitBreakerConfig	@CircuitBreaker(name="simpleCircuitBreakerConfig")
instance	simpleRateLimiter	@RateLimiter(name="simpleRateLimiter")

 

이 구조를 정확히 이해하면, 여러 곳에서 커스텀 복원력 정책을 쉽게 분배해서 관리할 수 있습니다.

Retry 예시

resilience4j.retry:
  configs:
    default:
      maxAttempts: 3
      waitDuration: 1000           # 밀리초 단위 (1000ms = 1초)
      retryExceptions:
        - com.example.resilience4jdemo.exception.RetryException   # 명시적으로 재시도할 예외 클래스들
      ignoreExceptions:
        - com.example.resilience4jdemo.exception.IgnoreException  # 재시도하지 않을 예외 클래스(직접 예외로 반환)
  instances:
    simpleRetryConfig:
      baseConfig: default

 

CircuitBreaker 예시

resilience4j.circuitbreaker:
  configs:
    default:
      slidingWindowSize: 10
      failureRateThreshold: 50
      waitDurationInOpenState: 5000
  instances:
    simpleCircuitBreakerConfig:
      baseConfig: default

RateLimiter 예시

resilience4j.ratelimiter:
  instances:
    simpleRateLimiter:
      limitForPeriod: 10
      limitRefreshPeriod: 1s
      timeoutDuration: 100ms

---

Gradle 의존성 설정 방법

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-aop'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'io.github.resilience4j:resilience4j-spring-boot2:1.7.0'
    implementation 'io.github.resilience4j:resilience4j-all:1.7.0'
    // 선택적으로 각 패턴별 모듈(resilience4j-circuitbreaker, resilience4j-retry, 등)만 추가해도 됨
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

• 최신 버전은 공식 문서에 따라 변경될 수 있음.

---

Java 코드,어노테이션 설정 방법

Retry 예시

@Service
public class RetryService {
    @Retry(name = "simpleRetryConfig", fallbackMethod = "fallback")
    public String process(String param) {
        //...
    }
    private String fallback(String param, Exception ex) {
        return "Recovered: " + ex.toString();
    }
}

CircuitBreaker 예시

@Service
public class CircuitBreakerService {
    @CircuitBreaker(name = "simpleCircuitBreakerConfig", fallbackMethod = "fallback")
    public String someRequest() {
    }
    private String fallback(Exception ex) {
         return "Fallback result";
    }
}

• @Retry, @CircuitBreaker, @RateLimiter 등 각 패턴별 어노테이션이 제공됩니다.
• fallbackMethod는 모든 시도가 실패했을 때 실행할 메서드 지정.

Resilience4j 사용 방법 요약

1. 의존성 추가 (Gradle/Maven)
2. application.yml 등 설정 파일에 각 패턴별 config 작성
3. @Retry, @CircuitBreaker 등 어노테이션을 서비스/컴포넌트에 추가
4. 필요에 따라 Actuator 엔드포인트 (/actuator/circuitbreakers 등)로 상태 모니터/제어