Spring Cloud에서 Resilience4j로 Circuit Breaker 구현하기

 

 

마이크로서비스 아키텍처에서 개별 서비스의 장애가 전체 시스템에 영향을 주지 않도록 하기 위한 가장 효과적인 방법 중 하나는 Circuit Breaker(서킷 브레이커) 패턴입니다. 이 글에서는 Spring Cloud에서 제공하는 spring-cloud-starter-circuitbreaker-resilience4j 스타터를 이용해 Resilience4j 기반의 Circuit Breaker를 적용하는 방법과 주요 설정, 활용 팁까지 자세히 다뤄보겠습니다.

---

✅ Resilience4j란?

Resilience4j는 Netflix Hystrix 이후로 가장 널리 사용되는 Java 기반의 장애 회복 라이브러리입니다. 다음과 같은 주요 기능을 제공합니다.

• Circuit Breaker
• Rate Limiter
• Retry
• Bulkhead
• TimeLimiter

Spring Cloud는 spring-cloud-starter-circuitbreaker-resilience4j라는 스타터를 통해 이 Resilience4j를 손쉽게 통합할 수 있게 도와줍니다.

---

✅ 의존성 추가

Gradle 기준으로는 다음과 같이 의존성을 추가합니다:

dependencies {
    implementation 'org.springframework.cloud:spring-cloud-starter-circuitbreaker-resilience4j'
}

Spring Cloud BOM을 사용 중이라면 버전은 자동으로 관리됩니다.

---

✅ 기본적인 Circuit Breaker 적용 방법

Spring Boot 프로젝트에서는 @CircuitBreaker 어노테이션만으로도 손쉽게 적용이 가능합니다.

@RestController
@RequiredArgsConstructor
public class OrderController {

    private final OrderService orderService;

    @GetMapping("/orders/{id}")
    @CircuitBreaker(name = "orderService", fallbackMethod = "fallback")
    public ResponseEntity<Order> getOrder(@PathVariable Long id) {
        return ResponseEntity.ok(orderService.findOrderById(id));
    }

    public ResponseEntity<Order> fallback(Long id, Throwable t) {
        // 실패 시 대체 응답 처리
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
    }
}

---

✅ application.yml 설정 예시

Resilience4j는 설정의 유연함이 큰 장점입니다. 예를 들어, 아래와 같이 orderService에 대한 Circuit Breaker 동작 조건을 정의할 수 있습니다:

resilience4j:
  circuitbreaker:
    instances:
      orderService:
        registerHealthIndicator: true
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 10
        minimumNumberOfCalls: 5
        failureRateThreshold: 50
        waitDurationInOpenState: 10s
        permittedNumberOfCallsInHalfOpenState: 3

설정 설명:

• slidingWindowSize: 실패율 계산을 위한 호출 수
• failureRateThreshold: 실패율 기준(%) - 이 값을 초과하면 OPEN 상태로 전환
• waitDurationInOpenState: OPEN 상태 유지 시간
• permittedNumberOfCallsInHalfOpenState: HALF_OPEN 상태에서 허용할 호출 수

---

✅ 상태 전이 요약

Resilience4j의 Circuit Breaker는 3가지 상태를 가집니다:

상태 설명

CLOSED	정상 작동 중. 실패율이 낮음
OPEN	호출 차단. 일정 시간 이후 HALF_OPEN으로 전환
HALF_OPEN	제한된 호출만 허용하여 복구 가능성 테스트

---

✅ Actuator와 통합

spring-boot-starter-actuator를 함께 사용하면 /actuator/metrics나 /actuator/health 엔드포인트에서 Circuit Breaker 상태를 확인할 수 있습니다.

management:
  endpoints:
    web:
      exposure:
        include: health,metrics

이후, /actuator/health에 circuitBreakers 상태가 포함됩니다.

---

✅ Custom Fallback 활용 팁

실패 상황에 따라 사용자 정의 예외 처리나 대체 데이터를 제공하고 싶다면 fallbackMethod에 다양한 파라미터를 넘겨 받아 처리 가능합니다.

public ResponseEntity<Order> fallback(Long id, RuntimeException ex) {
    log.warn("Fallback executed due to: {}", ex.getMessage());
    return ResponseEntity.ok(new Order(id, "임시 주문"));
}

---

✅ Retry와 함께 사용하기

Resilience4j의 또 다른 기능인 Retry를 함께 사용할 수도 있습니다:

@Retry(name = "orderServiceRetry", fallbackMethod = "fallback")
@CircuitBreaker(name = "orderService", fallbackMethod = "fallback")

application.yml에 retry 설정도 함께 정의해줘야 합니다.

---

✅ 마무리

spring-cloud-starter-circuitbreaker-resilience4j를 활용하면 장애 대응과 복구에 강한 마이크로서비스를 구현할 수 있습니다. 설정이 직관적이고 확장성도 좋아 실제 운영 환경에서도 널리 활용되고 있습니다. 만약 아직 서킷 브레이커를 도입하지 않았다면, Resilience4j는 좋은 출발점이 되어줄 것입니다.