2nd/10_Wiki/Topics/Domain_Programming/Coding/Backend_Circuit_Breaker.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
backend-circuit-breaker	Circuit Breaker — 외부 의존성 격리	Coding	draft	B	conceptual	2026-05-09	2026-05-09	backend resilience circuit-breaker vibe-coding	language applicable_to TypeScript / opossum Backend		bulkhead fail-fast half-open fallback

Circuit Breaker

외부 의존성이 죽으면 우리도 같이 죽지 마라. 연속 실패 N회 → 회로 OPEN → 즉시 fail-fast 또는 fallback. 일정 시간 후 HALF-OPEN 으로 한 번 시도 → 성공이면 CLOSED 복귀.

📖 핵심 개념

3 상태:

• CLOSED: 정상. 요청 통과.
• OPEN: 차단. 즉시 fail (또는 fallback).
• HALF-OPEN: 시도 1번. 성공 → CLOSED. 실패 → OPEN.

전이 조건:

• CLOSED → OPEN: 에러율 > 임계값 (예: 50%) AND 최소 호출 수.
• OPEN → HALF-OPEN: timeout (보통 30s~1m) 후 자동.
• HALF-OPEN → CLOSED: 성공.
• HALF-OPEN → OPEN: 실패.

💻 코드 패턴

opossum (Node)

import CircuitBreaker from 'opossum';

const options = {
  timeout: 3000,                  // 호출 자체 timeout
  errorThresholdPercentage: 50,
  resetTimeout: 30_000,           // OPEN 후 HALF-OPEN 까지
  rollingCountTimeout: 10_000,    // 통계 window
  rollingCountBuckets: 10,
  volumeThreshold: 10,            // 최소 호출 수 (그 전엔 OPEN 안 됨)
};

const fetchUser = (id: string) => api.get(`/users/${id}`);
const breaker = new CircuitBreaker(fetchUser, options);

// fallback
breaker.fallback((id: string) => ({ id, name: 'Unknown', cached: true }));

breaker.on('open', () => alerts.send('USER_API_OPEN'));
breaker.on('halfOpen', () => log.info('USER_API_HALF_OPEN'));
breaker.on('close', () => log.info('USER_API_CLOSED'));

// 사용
const user = await breaker.fire('123');

Custom 간단 구현

class CB {
  private state: 'CLOSED'|'OPEN'|'HALF' = 'CLOSED';
  private failures = 0;
  private nextTry = 0;
  constructor(private threshold = 5, private resetMs = 30_000) {}

  async exec<T>(op: () => Promise<T>, fallback?: () => T): Promise<T> {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextTry) {
        if (fallback) return fallback();
        throw new Error('CIRCUIT_OPEN');
      }
      this.state = 'HALF';
    }
    try {
      const r = await op();
      this.onSuccess();
      return r;
    } catch (e) {
      this.onFailure();
      if (fallback && this.state === 'OPEN') return fallback();
      throw e;
    }
  }
  private onSuccess() { this.failures = 0; this.state = 'CLOSED'; }
  private onFailure() {
    this.failures++;
    if (this.failures >= this.threshold) {
      this.state = 'OPEN';
      this.nextTry = Date.now() + this.resetMs;
    }
  }
}

🤔 의사결정 기준

의존성	breaker 적합
외부 HTTP API	✅
메시지 큐 (Kafka, RabbitMQ)	✅ — produce 실패 시
DB (단일 인스턴스)	✅ — 단 fallback 보통 어렵
Redis cache	✅ — fallback = origin DB
자체 마이크로서비스 호출	✅
동기 라이브러리 호출	❌ 의미 없음

❌ 안티패턴

• fallback 없이 OPEN: 사용자에게 그대로 에러. 캐시된 데이터 / 부분 응답 등 fallback 고민.
• threshold 너무 낮음 (3회 실패 = OPEN): 일시 hiccup 에 over-react.
• threshold 너무 높음 (1000회): 의미 없는 늦은 차단.
• breaker 인스턴스를 매 요청 새로: state 안 누적. 공유.
• 모든 의존성 한 breaker 공유: 한 의존성 사고가 무관한 의존성 차단.
• HALF-OPEN 동안 다수 호출 통과: 동시성 제어 없이 그냥 다 통과 → 다 실패하면 다시 OPEN. HALF 에서는 1개만.
• 알림 / 모니터링 없음: OPEN 됐는지 모름. 운영자 알림 필수.

🤖 LLM 활용 힌트

• 외부 의존성마다 별도 breaker.
• fallback 명시 필수 — degraded service 가 fail 보다 낫다.

🔗 관련 문서

• Backend_Retry_Strategy
• Backend_Health_Check_Patterns