Antigravity Agent
155 lines
4.6 KiB
Markdown
155 lines
4.6 KiB
Markdown
---
|
|
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]]
|