docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,123 @@
|
||||
---
|
||||
id: backend-circuit-breaker
|
||||
title: Circuit Breaker — 외부 의존성 격리
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [backend, resilience, circuit-breaker, vibe-coding]
|
||||
tech_stack: { language: "TypeScript / opossum", applicable_to: ["Backend"] }
|
||||
applied_in: []
|
||||
aliases: [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)
|
||||
```ts
|
||||
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 간단 구현
|
||||
```ts
|
||||
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]]
|
||||
Reference in New Issue
Block a user