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,156 @@
|
||||
---
|
||||
id: backend-outbox-pattern
|
||||
title: Outbox — DB write + 메시지 발행 원자성
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [backend, outbox, messaging, vibe-coding]
|
||||
tech_stack: { language: "TS / SQL", applicable_to: ["Backend"] }
|
||||
applied_in: []
|
||||
aliases: [outbox, transactional outbox, dual-write, CDC, event publisher]
|
||||
---
|
||||
|
||||
# Outbox Pattern
|
||||
|
||||
> "DB commit + Kafka publish" 둘 다 동시 = 불가능. **DB 트랜잭션 안에서 events 테이블에 같이 insert** → 별도 publisher 가 events 읽어 publish. 원자성 보장.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- Dual-write 문제: DB OK + 메시지 실패 → 메시지 없음 / DB 실패 + 메시지 OK → 잘못된 메시지.
|
||||
- Outbox: 같은 트랜잭션 안 outbox 테이블 insert.
|
||||
- Publisher: outbox 읽어 broker 로 보내고 sent 표시.
|
||||
- CDC 변형: outbox 도 안 쓰고 Debezium 이 binlog/WAL 직접.
|
||||
|
||||
## 💻 코드 패턴
|
||||
|
||||
### Outbox 테이블
|
||||
```sql
|
||||
CREATE TABLE outbox (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
aggregate_type TEXT NOT NULL,
|
||||
aggregate_id TEXT NOT NULL,
|
||||
event_type TEXT NOT NULL,
|
||||
payload JSONB NOT NULL,
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
sent_at TIMESTAMPTZ
|
||||
);
|
||||
|
||||
CREATE INDEX outbox_unsent ON outbox(id) WHERE sent_at IS NULL;
|
||||
```
|
||||
|
||||
### Write (트랜잭션 안)
|
||||
```ts
|
||||
async function createOrder(input: CreateOrder) {
|
||||
return db.transaction(async (tx) => {
|
||||
const order = await tx.orders.insert(input);
|
||||
await tx.outbox.insert({
|
||||
aggregateType: 'order',
|
||||
aggregateId: order.id,
|
||||
eventType: 'OrderCreated',
|
||||
payload: { orderId: order.id, userId: input.userId, amount: input.amount },
|
||||
});
|
||||
return order;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Publisher (poll loop)
|
||||
```ts
|
||||
async function publishLoop() {
|
||||
while (true) {
|
||||
const batch = await db.outbox.findUnsent({ limit: 100 });
|
||||
if (batch.length === 0) {
|
||||
await sleep(500);
|
||||
continue;
|
||||
}
|
||||
|
||||
for (const e of batch) {
|
||||
try {
|
||||
await broker.publish(e.eventType, e.payload, {
|
||||
headers: { 'x-event-id': String(e.id), 'aggregate-id': e.aggregateId },
|
||||
});
|
||||
await db.outbox.markSent(e.id);
|
||||
} catch (err) {
|
||||
log.error('publish failed', err);
|
||||
// 재시도 — 다음 loop 에서 또 시도
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### At-least-once 보장 + idempotency 헤더
|
||||
```ts
|
||||
// Consumer 측
|
||||
on('OrderCreated', async (msg) => {
|
||||
const id = msg.headers['x-event-id'];
|
||||
if (await db.processed.exists(id)) return; // 이미 처리
|
||||
await handle(msg.payload);
|
||||
await db.processed.insert({ id, processedAt: now() });
|
||||
});
|
||||
```
|
||||
|
||||
### CDC (Debezium) 변형
|
||||
- DB binlog/WAL 을 Debezium 이 읽음.
|
||||
- Outbox 테이블의 INSERT 만 필터.
|
||||
- Kafka 로 자동 발행.
|
||||
- 앱 코드는 outbox INSERT 만 — publisher 코드 불필요.
|
||||
|
||||
```yaml
|
||||
# Debezium connector
|
||||
{
|
||||
"connector.class": "io.debezium.connector.postgresql.PostgresConnector",
|
||||
"transforms": "outbox",
|
||||
"transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
|
||||
"transforms.outbox.table.field.event.id": "id",
|
||||
"transforms.outbox.table.field.event.key": "aggregate_id",
|
||||
"transforms.outbox.table.field.event.payload": "payload"
|
||||
}
|
||||
```
|
||||
|
||||
### TX-side cleanup
|
||||
```ts
|
||||
// 발행된 이벤트 N일 후 삭제
|
||||
DELETE FROM outbox WHERE sent_at < NOW() - INTERVAL '30 days';
|
||||
```
|
||||
|
||||
### Lock for parallel publishers
|
||||
```sql
|
||||
-- N 개 publisher 가 동시에 도는 경우
|
||||
SELECT * FROM outbox
|
||||
WHERE sent_at IS NULL
|
||||
ORDER BY id
|
||||
LIMIT 100
|
||||
FOR UPDATE SKIP LOCKED;
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 상황 | 추천 |
|
||||
|---|---|
|
||||
| Postgres + 이벤트 발행 | Outbox + poll publisher |
|
||||
| 큰 처리량 + Kafka | Outbox + Debezium CDC |
|
||||
| Strict ordering 필요 | Outbox + partition key (aggregate_id) |
|
||||
| 여러 broker | Outbox + 여러 publisher |
|
||||
| Email / Slack 알림 | Outbox 패턴 그대로 |
|
||||
| Idempotency 강 | Consumer 측 dedupe table |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Dual-write 직접**: DB commit + publish 사이 crash → 한쪽 실패.
|
||||
- **Outbox publish 후 삭제**: 한 번에 안 되면 stuck.
|
||||
- **Polling 대신 immediate publish (트랜잭션 후)**: crash 위험.
|
||||
- **Sent_at 기반 ID 정렬 X**: skip 가능. id 정렬.
|
||||
- **Partitioning 없이 강 ordering**: 불가능.
|
||||
- **Cleanup 안 함**: 테이블 무한.
|
||||
- **Consumer 멱등성 없음**: at-least-once 가 중복.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- DB commit + 이벤트 발행 = outbox.
|
||||
- Postgres SKIP LOCKED 로 병렬 publisher.
|
||||
- Debezium 도입 시 publisher 코드 X.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[Backend_Saga_Patterns]]
|
||||
- [[Backend_Event_Sourcing]]
|
||||
- [[Backend_Webhook_Patterns]]
|
||||
Reference in New Issue
Block a user