msa — CQRS + Event Sourcing 주문 서비스

주문 서비스의 CQRS 경로만 단일 모듈로 구성한 학습 프로젝트다. 주문의 상태를 테이블에 저장하지 않고, 일어난 일 (이벤트)만 쌓은 뒤 읽을 때 다시 재생 (replay) 한다.

---

1. 한눈에 보기

	Command (쓰기)	Query (읽기)
진입점	OrderCommandController — POST PATCH	OrderQueryController — GET
서비스	EventCommandService	EventQueryService
하는 일	불변식 검사 → 이벤트 append → 발행	이벤트 replay → OrderDto 복원
저장소 접근	save() + 검증용 스트림 로드	SELECT만
결과	201/200 빈 바디	OrderDto / List<OrderDto>

두 경로는 컨트롤러·서비스 수준에서 완전히 갈라져 있고, order_event 테이블 하나로만 만난다.

---

2. 왜 이렇게 나눴나 — CQRS

CQRS (Command Query Responsibility Segregation)는 "상태를 바꾸는 요청"과 "상태를 읽는 요청"을 서로 다른 모델·경로로 처리하는 방식이다. 이 프로젝트에서는 다음과 같이 적용했다.

• Command는 조회 응답을 만들지 않는다. POST/PATCH는 이벤트를 쌓고 상태 코드만 돌려준다. 바뀐 결과가 궁금하면 GET으로 다시 묻는다.
• Query는 저장하지 않는다. EventQueryService에는 save()가 없다. 읽기 모델 (OrderDto)은 요청마다 이벤트에서 복원되는 일회성 결과물이며 어디에도 영속하지 않는다.
• Command가 이벤트를 읽는 것은 Query가 아니다. EventCommandService.updateUser()는 이벤트를 쌓기 전에 해당 주문의 스트림을 로드해 "주문이 존재하는가", "요청자가 소유자인가"를 검사한다. 이는 불변식 검사를 위한 애그리거트 로딩이고, 클라이언트에게 돌려줄 조회 응답을 만드는 게 아니다. 이 구분을 놓치면 이 호출을 "CQRS 위반"으로 오해하고 되돌리기 쉽다.

---

3. 상태의 원본 — Event Sourcing

order_event 테이블이 유일한 진실이다

eventId | orderId | userId | eventType     | payload (JSON)                                   | timestamp
--------+---------+--------+---------------+--------------------------------------------------+----------
1       | a1      | u1     | EVENT_CREATED | {"productId":"P1","qty":2,"unitPrice":1000,"totalPrice":2000} | …
2       | a1      | u1     | EVENT_UPDATED | {"productId":"P1","qty":5,"unitPrice":1000,"totalPrice":5000} | …
3       | b2      | u1     | EVENT_CREATED | {…}                                              | …

• append-only. 행을 update/delete하는 코드가 없다. 상태 변경은 항상 새 이벤트다.
• userId·orderId는 컬럼, 주문 내용은 payload (JSON, Gson) 에 들어간다.
• 현재 상태를 담는 orders 테이블은 의도적으로 두지 않았다. 상태를 캐시하는 테이블이 없으므로, 읽기는 반드시 replay를 거친다.

쓰기 — 이벤트를 쌓기까지

RequestOrder ──@Valid──▶ OrderDto ──▶ EventCommandService
                                        ├─ (PATCH) 스트림 로드 → 없으면 404 / 소유자 다르면 403
                                        ├─ OrderEvent 생성, payload = Gson(EventPayload)
                                        ├─ save()            ← append
                                        └─ publishEvent()    ← 커밋 뒤 OrderEventListener 실행

• createOrder/updateUser는 @Transactional. save와 publishEvent가 한 트랜잭션에 묶인다.
• OrderEventListener는 @TransactionalEventListener(AFTER_COMMIT)라 커밋된 뒤에만 실행되고, 롤백되면 부수효과도 일어나지 않는다. 리스너 예외는 삼킨다 — 커밋 후에 던지면 "저장은 됐는데 500 → 클라이언트 재시도 → 중복 이벤트"가 되기 때문이다.

읽기 — replay

List<OrderEvent> events = repo.findByOrderIdOrderByTimestampAscEventIdAsc(orderId);
OrderDto order = new OrderDto();
events.

forEach(order::apply);   // CREATED → 전체 채움, UPDATED → 덮어씀, DELETED → deleted=true

• 정렬은 timestamp → eventId(시퀀스). 같은 밀리초에 두 이벤트가 들어와도 삽입 순서를 따른다.
• 목록 (GET /{userId}/orders)은 userId의 orderId를 첫 이벤트 (생성) 시각 순으로 나열한 뒤 각각 replay한다.
• OrderDto는 apply()로만 상태가 바뀐다. setter로 직접 채우는 조회 코드는 없다.

새 상태 변경을 추가하려면 — 세 곳을 같이 고친다

1. EventType에 상수 추가
2. EventCommandService에 이벤트를 만들어 save + publishEvent하는 메서드 추가
3. OrderDto.apply()에 case + applyXxx() 추가

1↔3 짝이 안 맞으면 replay 시 IllegalArgumentException이다. 컴파일은 통과하니 주의한다. payload 필드명 (EventPayload)과 읽기 클래스 (OrderCreatedData/OrderUpdatedData) 필드명이 다르면 Gson이 조용히 null 을 넣는다.

---

4. API

Method	Path	동작	성공	실패
POST	/{userId}/orders	EVENT_CREATED append	201	400 검증 실패·오버플로
PATCH	/{userId}/orders/{orderId}	EVENT_UPDATED append	200	400 / 404 없는 주문 / 403 타인 주문
GET	/{userId}/orders	userId의 주문 전부 replay	200 [] 가능	—
GET	/orders/{orderId}	주문 하나 replay	200	404 없는 주문

요청 바디 (RequestOrder):

{
  "productId": "P1",
  "qty": 2,
  "unitPrice": 1000
}

productId 필수, qty ≥ 1, unitPrice ≥ 0. totalPrice = qty × unitPrice는 컨트롤러가 계산하며 int 범위를 넘으면 400.

EVENT_DELETED는 OrderDto.apply()가 처리할 수 있지만 대응하는 엔드포인트는 아직 없다.

---

5. 패키지 구조

com.project.msa
├── controller/   OrderCommandController (POST/PATCH) · OrderQueryController (GET)
├── event/
│   ├── entity/     OrderEvent (Event Store 행) · EventType · EventPayload (payload 스키마)
│   ├── repository/ OrderEventRepository
│   ├── service/    EventCommandService (쓰기) · EventQueryService (읽기/replay)
│   └── consumer/   OrderEventListener (@TransactionalEventListener)
├── dto/          OrderDto (읽기 모델, apply로 replay) · OrderCreatedData · OrderUpdatedData (payload 역직렬화)
├── vo/           RequestOrder · ResponseOrder (HTTP 경계)
└── exception/    OrderNotFoundException (404) · OrderAccessDeniedException (403) · GlobalExceptionHandler

레이어 방향은 controller → event.service → event.repository 단방향이다.

---

6. 실행

./gradlew bootRun        # :8082

curl -X POST  localhost:8082/u1/orders -H 'Content-Type: application/json' -d '{"productId":"P1","qty":2,"unitPrice":1000}'
curl          localhost:8082/u1/orders
curl -X PATCH localhost:8082/u1/orders/{orderId} -H 'Content-Type: application/json' -d '{"productId":"P1","qty":5,"unitPrice":1000}'
curl          localhost:8082/orders/{orderId}

이벤트 스토어를 직접 보려면 H2 콘솔: http://localhost:8082/h2-console (JDBC URL jdbc:h2:mem:testdb, 사용자 sa, 비밀번호 없음) → SELECT * FROM ORDER_EVENT ORDER BY EVENT_ID.

스택
Java 17 · Spring Boot 4.1.1 (Spring MVC)	Spring Data JPA + H2 in-memory
Gson — payload 직렬화	Jackson — HTTP 응답 직렬화
Lombok · ModelMapper	Bean Validation

H2는 인메모리라 재기동하면 이벤트가 사라진다. 영속 DB로 바꾸는 순간 "이미 저장된 이벤트가 새 applyXxx()로 replay되는가"가 실제 문제가 된다 — payload 구조를 바꿀 때 가장 먼저 봐야 할 지점이다.

---

7. 이 프로젝트가 의도적으로 하지 않는 것

• 스냅샷·프로젝션 테이블 — 조회 때마다 전체 replay한다. 이벤트가 많아지면 느려지지만 학습 범위 밖.
• 보상 이벤트 — 잘못 쌓인 이벤트를 되돌리는 경로가 없다. 그래서 쌓기 전 검증 (404/403/400)이 중요하다.
• 호출 측 서비스 — 별도로 두지 않는다. curl로 직접 호출한다.
• 인증 — 경로의 {userId}를 그대로 신뢰한다. 소유자 검사는 "경로 userId == 첫 이벤트 userId"까지만.