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,154 @@
|
||||
---
|
||||
id: backend-cqrs-patterns
|
||||
title: CQRS — 명령 / 조회 분리
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [backend, cqrs, ddd, vibe-coding]
|
||||
tech_stack: { language: "TS / SQL", applicable_to: ["Backend"] }
|
||||
applied_in: []
|
||||
aliases: [CQRS, command query separation, read model, write model]
|
||||
---
|
||||
|
||||
# CQRS
|
||||
|
||||
> **Command (write)** 와 **Query (read)** 를 다른 모델 / 다른 DB / 다른 API. 단순한 read model 로 빠른 query, 정확한 write model 로 일관성. ES 와 자주 페어 — 그러나 ES 없이도 가능.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- Command: 쓰기 (CreateOrder). 모델 = Aggregate.
|
||||
- Query: 읽기. 모델 = denormalized view.
|
||||
- Eventual consistency: write → projection 까지 ms~s 지연.
|
||||
|
||||
## 💻 코드 패턴
|
||||
|
||||
### Command vs Query API 분리
|
||||
```ts
|
||||
// commands.ts
|
||||
async function createOrder(cmd: CreateOrderCommand): Promise<OrderId> { ... }
|
||||
async function shipOrder(cmd: ShipOrderCommand): Promise<void> { ... }
|
||||
|
||||
// queries.ts
|
||||
async function getOrderSummary(id: OrderId): Promise<OrderSummary> { ... } // 읽기 전용 view
|
||||
async function listOrdersForUser(userId: UserId): Promise<OrderListItem[]> { ... }
|
||||
```
|
||||
|
||||
### Write side (정확)
|
||||
```ts
|
||||
async function createOrder(cmd: CreateOrderCommand) {
|
||||
return db.transaction(async (tx) => {
|
||||
const order = OrderAggregate.create(cmd);
|
||||
await tx.orders.insert(order.toRow());
|
||||
await publishEvent(new OrderCreated(order.id, ...));
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Read side (빠른)
|
||||
```sql
|
||||
-- 미리 계산된 view (denormalized)
|
||||
CREATE TABLE order_summary (
|
||||
order_id UUID PRIMARY KEY,
|
||||
user_email TEXT, -- join 안 해도 됨
|
||||
user_name TEXT,
|
||||
item_count INT,
|
||||
total_amount NUMERIC,
|
||||
status TEXT,
|
||||
created_at TIMESTAMPTZ,
|
||||
...
|
||||
);
|
||||
|
||||
-- 1 query 로 끝
|
||||
SELECT * FROM order_summary WHERE user_id = $1;
|
||||
```
|
||||
|
||||
### Projection (write events → read view)
|
||||
```ts
|
||||
async function projectOrderEvent(e: OrderEvent) {
|
||||
switch (e.type) {
|
||||
case 'OrderCreated':
|
||||
const user = await getUserView(e.userId);
|
||||
await db.orderSummary.insert({
|
||||
orderId: e.orderId,
|
||||
userEmail: user.email, userName: user.name,
|
||||
itemCount: 0, totalAmount: 0,
|
||||
status: 'open',
|
||||
createdAt: e.createdAt,
|
||||
});
|
||||
break;
|
||||
case 'ItemAdded':
|
||||
await db.orderSummary.update(e.orderId, {
|
||||
itemCount: { increment: 1 },
|
||||
totalAmount: { increment: e.price * e.qty },
|
||||
});
|
||||
break;
|
||||
case 'OrderShipped':
|
||||
await db.orderSummary.update(e.orderId, { status: 'shipped' });
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 다른 DB (read 최적화)
|
||||
- Write: Postgres (정확).
|
||||
- Read: Elasticsearch (검색) / DynamoDB (key 검색) / Redis (cache).
|
||||
- 동기화 = projection / CDC (Debezium).
|
||||
|
||||
### Read replica + materialized view (가벼운 CQRS)
|
||||
```sql
|
||||
-- Postgres materialized view
|
||||
CREATE MATERIALIZED VIEW order_summary AS
|
||||
SELECT o.id, u.email, u.name, count(i) AS item_count, ...
|
||||
FROM orders o JOIN users u ON ... LEFT JOIN items i ON ...
|
||||
GROUP BY o.id, u.email, u.name;
|
||||
|
||||
-- 주기적 refresh
|
||||
REFRESH MATERIALIZED VIEW CONCURRENTLY order_summary;
|
||||
```
|
||||
|
||||
### API 분리 (다른 endpoint / service)
|
||||
```
|
||||
POST /api/orders → Command service
|
||||
GET /api/orders/:id → Query service (다른 cluster, 다른 cache)
|
||||
```
|
||||
|
||||
### Eventual consistency 처리
|
||||
```ts
|
||||
// 사용자가 만든 후 list 에서 안 보일 수 있음
|
||||
await api.orders.create(input);
|
||||
// 즉시 navigate('/orders') → 새 order 안 보임 (projection 늦음)
|
||||
|
||||
// 해결: optimistic (TanStack Query setQueryData)
|
||||
qc.setQueryData(['orders', userId], (old) => [...old, new]);
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 상황 | 추천 |
|
||||
|---|---|
|
||||
| Read >> Write (10:1 이상) | CQRS read 분리 |
|
||||
| 검색 / 필터 복잡 | CQRS + Elasticsearch |
|
||||
| 실시간 보장 필요 | CQRS 비추 (eventual consistency) |
|
||||
| ES 사용 중 | CQRS 자연 |
|
||||
| 단순 CRUD | 과잉 |
|
||||
| 보고서 / 분석 | Read replica 또는 OLAP DB |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Eventual consistency 모름**: 사용자가 자기 거 못 봄.
|
||||
- **Read 와 Write 가 같은 모델 — CQRS 흉내**: 분리 의미 없음.
|
||||
- **Projection lag 모니터링 없음**: 1시간 lag 도 모름.
|
||||
- **Write 가 read 도 직접 query**: 일관성 깨짐.
|
||||
- **너무 많은 read view**: 동기화 부담.
|
||||
- **Replay 불가 (이벤트 누락)**: ES + replay 가 안전.
|
||||
- **Strong consistency 가정 한 곳**: read-after-write 사용자 불일치.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- Read >> Write 일 때 도입.
|
||||
- Materialized view 가 가장 가벼운 CQRS.
|
||||
- 진짜 분리 = ES + projection.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[Backend_Event_Sourcing]]
|
||||
- [[DB_Read_Replica_Patterns]]
|
||||
- [[Backend_Outbox_Pattern]]
|
||||
Reference in New Issue
Block a user