서킷 브레이커(Circuit Breaker) 완벽 정리 + Spring Boot 적용 (Resilience4j)

외부 API가 장애 나면 어떻게 될까

외부 API가 장애 나면 서비스 전체가 멈출 수 있다.

이 문제를 막기 위한 대표적인 패턴이 서킷 브레이커다.

이 글에서는
개념 → 동작 원리 → Spring Boot 적용 → 실무 포인트까지 한 번에 정리한다.

---

1. 서킷 브레이커란

서킷 브레이커는

외부 시스템 장애 발생 시 호출을 차단해서 장애 확산을 막는 패턴이다

 

핵심은 하나다.

• 장애를 해결하는 것이 아니라
• 장애가 퍼지는 것을 막는다

---

2. 왜 필요한가

다음 상황을 보면 바로 이해된다.

A 서비스 → B 서비스 API 호출
B 서비스 장애 발생

이때 A 서비스는 계속 요청을 시도한다.

결과

• 응답 지연
• 스레드 누적
• 커넥션 풀 고갈
• 전체 서비스 장애

하나의 장애가 전체 시스템을 무너뜨리는 구조다.

그래서 일정 기준 이상 실패하면
요청 자체를 차단하는 장치가 필요하다.

---

3. 동작 원리

서킷 브레이커는 세 가지 상태로 동작한다.

CLOSED (정상 상태)

• 모든 요청 정상 처리
• 실패율을 지속적으로 측정

OPEN (차단 상태)

• 실패율이 기준 초과 시 전환
• 외부 API 호출 차단
• 즉시 실패 반환

HALF_OPEN (복구 확인 상태)

• 일부 요청만 허용
• 성공 시 CLOSED 전환
• 실패 시 다시 OPEN

이 상태 전이가 핵심이다.

---

4. Spring Boot 적용 (Resilience4 j)

실무에서는 Resilience4j를 사용한다.

 

4.1 의존성 추가

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

 

4.2 기본 코드

@CircuitBreaker(name = "externalApi", fallbackMethod = "fallback") 
public String getUserInfo(Long userId) { 
	return restTemplate.getForObject( "http://external-api/users/" + userId, String.class ); 
}

 

name은 설정과 연결되는 식별자

 

4.3 fallback

public String fallback(Long userId, Exception e) { 
	return "기본 사용자 정보"; 
}

 

 

• 장애 발생 시 대체 응답
• 파라미터 + Exception 형태 유지

4.4 설정 (application.yml)

resilience4j: 
	circuitbreaker: 
    	instances: 
        	externalApi: 
            	failureRateThreshold: 50 
                waitDurationInOpenState: 10s 
                slidingWindowSize: 10

 

 

설정 의미

• failureRateThreshold: 실패율 기준
• waitDurationInOpenState: 차단 유지 시간
• slidingWindowSize: 판단 기준 요청 수

---

5. 실무 적용 방식

실무에서는 보통 다음 세 가지를 함께 사용한다.

• timeout
• retry
• circuit breaker

이 세 가지를 함께 설계해야 안정적인 구조가 된다.

---

예시 1. 결제 API

• 외부 PG사 장애 발생
• 서킷 브레이커로 빠른 실패 처리
• 시스템 리소스 보호

예시 2. 상품 조회 API

• 외부 API 실패
• fallback으로 캐시 데이터 반환

---

6. 적용 전과 적용 후

적용 전

외부 API 장애 → 요청 누적 → 전체 장애

적용 후

외부 API 장애 → 빠른 실패 → 서비스 정상 유지

---

7. 실무에서 주의할 점

1. fallback 남용 금지

모든 실패를 fallback으로 처리하면
데이터 정합성 문제가 발생할 수 있다.

2. 모든 API에 적용하지 말 것

다음 경우에만 적용하는 것이 적절하다.

• 외부 API
• 장애 가능성이 높은 구간

3. timeout 없이 사용하지 말 것

서킷 브레이커만으로는 충분하지 않다.

반드시 timeout과 함께 사용해야 한다.

---

8. 정리

서킷 브레이커는 장애를 해결하는 기술이 아니라
장애 확산을 막는 안전장치다

 

외부 API를 사용하는 서비스라면
필수적으로 고려해야 하는 패턴이다.