❄️

추천 서버 호출에 Circuit Breaker 적용하기 (Resilience4j)

Created
2026/07/22
Tags
Kotlin
SpringBoot
Network
운영이슈
 
2026-07-22 @이영훈
 

개요

product-api는 딜/딜상품 목록을 추천순으로 내려줄 때 별도의 추천 서버(reco serving API)를 동기 호출합니다. 문제는 이 추천 서버가 우리 서비스의 외부 의존성이라는 점이에요. 추천 서버가 느려지거나 죽으면, 호출하던 스레드가 응답을 기다리며 물려버리고 그 지연이 product-api 전체로 전파됩니다. 화면에 상품 목록을 못 그리는 정도가 아니라, 커넥션 풀이 마르면서 무관한 다른 API까지 같이 죽는 장애로 번질 수 있어요.
그래서 추천 서버와의 통신 구간에 Resilience4j Circuit Breaker를 붙였습니다. 추천 서버가 불안정해지면 빠르게 차단(Fail-Fast)하고, 추천 대신 DB 기반 Fallback 목록을 내려주도록 만들어 "추천이 안 될 뿐, 서비스는 계속 뜨는" 상태를 보장하는 것이 목표였어요.
 
 

본문

Circuit Breaker란?

Circuit Breaker(회로 차단기)는 이름 그대로 전기 차단기에서 따온 패턴입니다. 전기 차단기가 과부하를 감지하면 회로를 끊어 집 전체가 타는 것을 막듯이, 소프트웨어에서는 외부 서비스 호출이 계속 실패할 때 그 호출을 아예 막아 장애가 전체로 번지는 것을 막습니다.
동작은 세 가지 상태로 설명됩니다.
  • CLOSED (정상): 모든 요청이 실제 서비스로 전달되며, 실패율을 집계해요.
  • OPEN (차단): 실패율이 임계치를 넘으면 전환돼요. 이후 요청은 실제 호출 없이 즉시 Fallback으로 빠집니다(Fail-Fast).
  • HALF_OPEN (탐색): 일정 시간이 지나면 제한된 수의 요청만 실제 호출해 보고, 성공하면 CLOSED로 복귀 / 실패하면 다시 OPEN으로 돌아갑니다.
 
핵심은 실패할 게 뻔한 호출은 아예 시도하지 않는다는 점입니다. 이미 죽은 서비스에 매 요청마다 타임아웃(5초)을 기다리는 대신, Circuit이 열려 있는 동안은 즉시 실패시켜 스레드와 커넥션을 아낍니다.
 

장점

  • 장애 격리(Fault Isolation): 외부 서비스의 장애가 우리 서비스 스레드 풀과 커넥션 풀을 잠식하지 못하게 막아요. 추천 서버 하나 때문에 무관한 API까지 죽는 연쇄 장애를 끊습니다.
  • 빠른 실패(Fail-Fast): 죽은 서비스를 매번 타임아웃까지 기다리지 않고 즉시 Fallback으로 응답합니다. 사용자 대기 시간이 5초 → 수 ms로 줄어들어요.
  • 자동 복구(Self-Healing): HALF_OPEN을 통해 사람이 개입하지 않아도 외부 서비스가 회복되면 스스로 정상 상태로 돌아와요.
  • Graceful Degradation: Fallback과 결합하면 "기능 일부만 저하될 뿐 서비스는 계속 동작"하는 우아한 성능 저하가 가능합니다.
 

기대 효과

product-api 관점에서 기대한 효과는 다음과 같습니다.
  • 추천 서버가 느려지거나 죽어도 product-api의 스레드/커넥션이 물리지 않아, 추천과 무관한 다른 API의 가용성이 보호돼요.
  • 추천 실패 시에도 DB 기반 Fallback 목록이 내려가 사용자는 빈 화면 없이 정렬만 다른 목록을 보게 됩니다.
  • waitDurationInOpenState를 10초로 짧게 잡아, 추천 서버가 잠깐 흔들렸다 회복되는 경우 빠르게 정상 추천으로 복귀합니다.
  • 결과적으로 외부 의존성 장애가 전체 장애(P1)가 아니라 부분 기능 저하로 축소됩니다.
 
⚠️
Circuit Breaker는 만능이 아니에요. Fallback이 없으면 OPEN 상태에서 그냥 예외를 던질 뿐이므로, "차단했을 때 무엇을 내려줄지"(Fallback 설계)가 오히려 본질입니다. 그래서 이 프로젝트도 CB보다 Fallback 목록 설계에 더 공을 들였습니다.
 

어디에 붙였나

추천 통신 구간은 크게 두 종류예요.
  • dealRecommendation: 딜 목록 추천 (예: 메인배너의 활성 딜 순서)
  • dealProductRecommendation: 딜상품 목록 추천 (추천순 정렬 V2 API)
 
각 통신을 담당하는 Adapter는 예외를 일부러 처리하지 않습니다. 아래처럼 주석으로 명시해두고, Fallback 책임을 호출하는 쪽(Strategy)으로 넘겼어요. Circuit Breaker가 예외를 감지해야 실패로 카운트하고 상태를 전환할 수 있기 때문입니다.
Kotlin
// [Notice] 사용하는 곳에서 Fallback 처리 반드시 필요
// 그래서 의도적으로 예외를 처리하지 않음
override fun getRecommendedDealsOfDealType(
    dealType: String,
    userId: String,
): RecommendedDealResponseDTO {
    val response = runBlocking {
        dealRecommendationServingAPIApi.getRecommendedDealsOfDealType(dealType, userId)
    }
    return RecommendedDealResponseDTO(dealIds = response.dealIds)
}
 

설정: ResilienceConfig

초기에는 어노테이션(@CircuitBreaker) + application.yml 기반으로 시작했지만, 최종적으로는 Spring Cloud Circuit Breaker의 프로그래밍 방식 설정으로 옮겼습니다. 설정이 한 곳(ResilienceConfig)에 모여 있어 통신 구간별 튜닝이 명확해져요.
Kotlin
@Configuration
class ResilienceConfig {
    companion object {
        const val DEAL_PRODUCT_RECOMMENDATION = "dealProductRecommendation"
        const val DEAL_RECOMMENDATION = "dealRecommendation"
    }

    @Bean
    fun circuitBreakerCustomizer(): Customizer<Resilience4JCircuitBreakerFactory> {
        return Customizer { factory ->
            factory.configureDefault { id ->
                Resilience4JConfigBuilder(id)
                    .circuitBreakerConfig(defaultCircuitBreakerConfig())
                    .timeLimiterConfig(defaultTimeLimiterConfig())
                    .build()
            }
            factory.configure({ b ->
                b.circuitBreakerConfig(dealProductRecommendationCircuitBreakerConfig())
                    .timeLimiterConfig(defaultTimeLimiterConfig())
            }, DEAL_PRODUCT_RECOMMENDATION)
            factory.configure({ b ->
                b.circuitBreakerConfig(dealRecommendationCircuitBreakerConfig())
                    .timeLimiterConfig(defaultTimeLimiterConfig())
            }, DEAL_RECOMMENDATION)
        }
    }
}
 
통신 구간별로 다르게 잡은 핵심 설정값은 다음과 같습니다.
설정
default
dealProductRecommendation
dealRecommendation
slidingWindowType
COUNT_BASED
COUNT_BASED
COUNT_BASED
slidingWindowSize
100
100
50
failureRateThreshold
50%
50%
50%
waitDurationInOpenState
60s
10s ⚡
10s ⚡
minimumNumberOfCalls
10
10
10
permittedNumberOfCallsInHalfOpenState
10
10
10
timeoutDuration (TimeLimiter)
5s
5s
5s
 
추천 통신은 waitDurationInOpenState를 기본 60초가 아니라 10초로 짧게 잡았어요. 추천 서버가 잠깐 흔들리다 회복되는 케이스에서 10초 만에 다시 HALF_OPEN으로 붙여보고 빠르게 복구시키기 위함입니다. 추천은 없어도 Fallback으로 서비스가 유지되니, OPEN을 오래 끄는 것보다 자주 재시도하는 편이 사용자 경험에 유리하다고 판단했습니다.
 
💡
Spring Cloud Circuit Breaker는 TimeLimiter가 기본 활성화라 타임아웃(5s)을 넘긴 느린 호출도 실패로 카운트되어 실패율 계산에 포함됩니다. 추천 서버가 죽지 않고 느려지기만 해도 Circuit이 열려요.
 

Strategy에서 감싸기 + Fallback

실제 차단/Fallback은 Displaying Strategy에서 circuitBreaker.run(호출, fallback)으로 감싸요. Factory에서 통신 구간 이름으로 Circuit 인스턴스를 하나 만들어 재사용합니다.
Kotlin
private val circuitBreaker: CircuitBreaker =
    circuitBreakerFactory.create(ResilienceConfig.DEAL_PRODUCT_RECOMMENDATION)

private fun getRecommendedDealProductsOfDealV2(...): RecommendedDealProductPagingResponseDTO {
    return userId?.let {
        circuitBreaker.run(
            {
                dealProductRecommendationOutputPort.getRecommendedDealProductsOfDealV2(...)
            },
            { ex ->
                logger.warn("[...] CircuitBreaker fallback triggered. error=${ex.message}", ex)
                getFallbackDealProductsOfDeal(dealId, filter)
            },
        )
    } ?: getFallbackDealProductsOfDeal(dealId, filter) // userId 없으면 애초에 추천 불가 → 바로 Fallback
}
 
Fallback은 추천 서버 없이 DB만으로 만들 수 있는 "그럴듯한" 목록이에요.
  • 딜 목록: 최신 등록순(DEAL_ID_DESC)으로 현재 라이브 중인 딜을 내려줌
  • 딜상품 목록: 딜ID 최신순 / 주문수 많은 순 등으로 라이브 상품 100개를 내려줌
 
즉 추천 서버가 죽어도 사용자에게는 비어 있는 화면이 아니라 정렬만 다른 목록이 보입니다.
 

정리

  • 외부 의존(추천 서버) 통신 구간에 Circuit Breaker를 둬서 장애 전파를 끊었습니다.
  • Adapter는 예외를 삼키지 않고, Fallback 책임은 호출부(Strategy)로 통일했어요.
  • 추천 서버 특성상 waitDurationInOpenState를 10초로 짧게 잡아 빠른 복구를 노렸습니다.
  • Fallback을 DB 기반 목록으로 설계해, 최악의 경우에도 서비스가 계속 뜨도록 했어요.
 
❄️
관련 PR: COM-707 딜상품 추천 Circuit Breaker (#3688), 딜 추천 Circuit Breaker (#3698). 코드 위치: packages/product/api/.../common/config/circuitbreakerconfig/ResilienceConfig.kt, .../deal/adapter/out/web/*RecommendationRestClientAdapter.kt