[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -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]]