Coding-Su

[Design Doc] Transactional Outbox Pattern — Kafka 직접 발행의 한계와 설계 (7주차 · 6팀 · 조수현)

Coding-Su — Fri, 3 Jul 2026 17:06:57 +0900

TL;DR

Kafka에 직접 발행하면 트랜잭션 커밋과 Kafka 발행 사이의 원자성을 보장할 수 없다. Outbox 테이블을 경유하는 방식으로 At Least Once 발행을 보장했고, partition-offset 기반 멱등성 키의 한계를 발견해 outboxId 기반으로 진화시켰다.

Introduction & Goals

Context / Background

좋아요, 조회, 주문 이벤트를 다른 시스템(commerce-streamer)으로 전파해야 했다. 처음엔 서비스 로직 안에서 직접 kafkaTemplate.send()를 호출하는 방식을 고려했는데, 트랜잭션 커밋 직후 Kafka 발행 직전에 애플리케이션이 죽으면 이벤트가 유실된다는 문제가 있었다.

// 문제: 커밋 후 send 전에 죽으면 이벤트 유실
@Transactional
public void like(Long memberId, Long productId) {
    likeRepository.save(new LikeModel(memberId, productId));
    // ← 여기서 죽으면?
    kafkaTemplate.send("catalog-events", event); // 발행 안 됨
}

Goals

이벤트 유실 없이 At Least Once 발행 보장
Kafka 장애가 핵심 비즈니스 로직(좋아요 등록)에 영향을 주지 않아야 함
중복 발행이 발생해도 Consumer가 멱등하게 처리

Detailed Design

System Architecture

[commerce-api]
핵심 로직 실행 (좋아요 저장)
  └─ 같은 트랜잭션에서 outbox 테이블에 PENDING으로 저장

OutboxRelayScheduler (1초마다)
  └─ PENDING 최대 100개 조회
  └─ payload에 outboxId 추가 후 Kafka 발행
  └─ 성공 → PUBLISHED, 실패 → PENDING 유지 (자동 재시도)

[commerce-streamer]
CatalogEventsConsumer / OrderEventsConsumer
  └─ outboxId로 event_handled 체크 (중복 skip)
  └─ eventType switch → metrics upsert
  └─ manual Ack

Data Models

outbox 테이블

컬럼	설명
id	PK (outboxId로 활용)
topic	발행 대상 토픽
partition_key	Kafka 파티션 키
event_type	이벤트 종류 식별자
payload	JSON 직렬화된 이벤트
status	PENDING / PUBLISHED
created_at / published_at	발행 시각 추적

event_handled 테이블

컬럼	설명
event_id (PK)	outboxId — 중복 처리 방지
handled_at	처리 시각

Alternatives Considered

멱등성 키 전략

옵션	Pros	Cons
`partition-offset`	Kafka 메타데이터 기반, payload 파싱 불필요	Outbox 재발행 시 다른 offset으로 도착 → event_handled 미스 → 중복 처리
`outboxId`	같은 비즈니스 이벤트는 항상 동일한 ID → 재발행 횟수에 무관하게 차단	Producer/Consumer 간 payload 구조 의존성

선택 근거: Outbox 크래시 시나리오를 분석했더니 partition-offset 방식의 허점이 있었다.

처음엔 partition-offset을 멱등성 키로 썼다. Kafka 메시지는 파티션 번호와 offset이라는 고유 위치를 가지는데, 이걸 조합해 event_handled에 저장하면 같은 메시지가 두 번 와도 차단할 수 있다고 생각했다.

문제는 "같은 메시지가 다른 offset으로 올 수 있다"는 점이었다. 아래 시나리오에서 발생한다:

1. OutboxRelay → Kafka 발행 성공 → ack 수신
2. outbox 레코드를 PUBLISHED로 업데이트 시도
3. DB 커밋 전 장애 발생  
4. 재시작 → outbox 레코드가 여전히 PENDING
5. "아직 안 보낸 것"으로 인식 → 재발행
6. 새 offset으로 Consumer에 도착
7. event_handled에 이전 offset은 있지만 새 offset은 없음 → 중복 처리

Kafka가 이미 메시지를 받았는데, Outbox DB는 모르는 상황이 만들어진 것이다. enable.idempotence=true도 이 경우엔 막을 수 없다 — 재시작하면 새 Producer 인스턴스가 생기고, 새 시퀀스 번호를 써서 Kafka가 새 메시지로 인식한다.

outboxId를 사용하면 재발행 횟수나 offset에 관계없이 같은 비즈니스 이벤트는 항상 동일한 ID를 가지므로 event_handled에서 차단된다. outboxId는 닭-달걀 문제(payload 생성 시 ID가 없음)가 있어, RelayScheduler가 Kafka 발행 직전에 이미 저장된 outbox의 ID를 payload에 주입하는 방식으로 해결했다.

Cross-cutting Concerns

Observability

PUBLISHED 전환 실패 시 [OutboxRelay] 발행 실패: outboxId={} 로그로 추적 가능
PENDING 레코드가 누적되면 Kafka 장애 또는 직렬화 오류 신호

Known Limitations

DLQ 미구현: 기술적 실패(DB 오류 등)가 반복되면 같은 메시지가 무한 재시도되어 파티션 블로킹 가능
발행 재시도 횟수 제한 없음: retry_count + Exponential Backoff 미적용 (Nice-to-Have)

[Design Doc] PG 외부 연동 장애 대응 설계 (6주차 · 6팀 · 조수현)

Coding-Su — Fri, 26 Jun 2026 17:10:50 +0900

TL;DR

FeignClient로 PG를 호출하는 결제 시스템에서 Timeout + Retry + CircuitBreaker 조합을 적용해 PG 장애가 전체 서비스로 번지는 Cascading Failure를 차단했다. 타임아웃/CB Open 시 PENDING 유지 + 30초 배치 복구로 상태 정합성을 보장한다.

Introduction & Goals

Context / Background

결제 요청 시 우리 서버가 PG(Payment Gateway)를 FeignClient로 동기 호출한다. PG는 외부 시스템이므로 응답 지연이나 장애를 제어할 수 없다. Tomcat 스레드 풀(기본 200개)은 PG 응답을 기다리는 동안 블로킹 상태로 묶이며, 스레드가 고갈되면 결제와 무관한 상품 조회나 주문 생성까지 503을 반환하게 된다. 이것이 Cascading Failure다.

Goals

PG 장애 시 결제 외 기능(상품 조회, 주문 등)은 정상 동작한다
타임아웃/CircuitBreaker Open 시 Payment는 즉시 FAILED가 아닌 PENDING을 유지하고, 30초 배치가 PG 상태를 확인해 최종 상태로 수렴한다
PG 500 에러는 Retry 3회 소진 후 즉시 FAILED 처리하고 주문을 취소한다

Detailed Design

System Architecture

PG 호출 흐름에 Resilience4j를 통해 3단 방어선을 적용한다.

Client
  └─ PaymentController
       └─ PaymentFacade  (@Transactional 없음 — TX 분리 핵심)
            ├─ [TX 1] PaymentService.create()  → Payment(PENDING) 저장 & DB 커넥션 반납
            └─ [TX 외부] PgClient.requestPayment()
                  └─ CircuitBreaker
                       └─ Retry (500 에러만, 최대 3회)
                            └─ TimeLimiter (readTimeout 400ms)
                                 └─ FeignClient → PG

트랜잭션 분리가 핵심이다. PaymentFacade에 @Transactional을 두지 않아 Payment 저장(TX 1) 커밋 직후 DB 커넥션을 반납한다. 이후 PG 호출이 느려지거나 CB가 열려도 DB 커넥션 풀에 영향을 주지 않는다.

장애 유형별 처리 흐름

장애 유형	처리 방식	최종 상태
PG 500 에러	Retry 3회 → 소진 시 즉시 FAILED + 주문 취소	FAILED
Timeout (400ms 초과)	Retry 없음, PENDING 유지 → 배치 복구	PENDING → 배치가 수렴
CircuitBreaker Open	PG 호출 차단, PENDING 유지 → 배치 복구	PENDING → 배치가 수렴
PG 정상 응답	transactionKey 저장, PENDING 유지	PENDING → 콜백으로 수렴

500은 Retry하고 Timeout은 Retry하지 않는 이유: PG 500은 createTransaction 이전 실패이므로 PG에 기록이 없다. 중복 결제 위험 없이 재시도 가능하다. 반면 Timeout은 PG가 처리 중일 수 있어 재시도하면 이중 결제가 발생한다.

Resilience4j 설정

feign:
  client:
    config:
      pg-client:
        connectTimeout: 1000
        readTimeout: 400   # PG 최대 지연 500ms 기준 — 타임아웃 시나리오 재현 의도

resilience4j:
  circuitbreaker:
    instances:
      pgCircuit:
        sliding-window-size: 10
        failure-rate-threshold: 50
        slow-call-duration-threshold: 2s
        slow-call-rate-threshold: 50
        wait-duration-in-open-state: 10s
        permitted-number-of-calls-in-half-open-state: 2
  retry:
    instances:
      pgRetry:
        max-attempts: 3
        retry-exceptions:
          - feign.RetryableException       # 503, 네트워크 오류
          - java.net.SocketTimeoutException
        ignore-exceptions:
          - SocketTimeoutException         # Timeout은 재시도 안 함

slow-call 설정이 중요하다. PG가 죽지는 않았지만 모든 요청이 3~4초씩 걸리는 상황에서 실패율은 0%이지만 스레드는 이미 고갈되고 있다. 이 설정 없이는 CB가 열리지 않는다.

PENDING 복구 배치

콜백이 메인 경로, 배치는 안전망이다.

@Scheduled(fixedDelay = 30000)
대상: status = PENDING AND created_at < now() - 30s

PG 조회 결과:
  SUCCESS + 주문 PENDING   → Payment SUCCESS + Order CONFIRMED
  SUCCESS + 주문 CANCELLED → 로그 기록 + 수동 처리 대상 표시
  FAILED                   → Payment FAILED + cancelBySystem + 재고 복구
  기록 없음                → Payment FAILED + cancelBySystem + 재고 복구
  PENDING                  → 건드리지 않음, 다음 사이클에 재시도

트레이드오프: split-commit

recoverAsFailure()에서 @Transactional을 제거해 failByOrderId()가 먼저 독립 커밋된다.

왜 하나의 트랜잭션으로 묶으면 안 되는가? cancelBySystem() 예외 시 failByOrderId()도 함께 롤백돼 결제가 PENDING으로 남는다. 배치가 30초 후 같은 건을 다시 처리하고 또 같은 예외가 발생하는 무한 재시도 루프가 된다.

허용하는 불일치: failByOrderId() 커밋 후 cancelBySystem()이 실패하면 결제는 FAILED지만 주문이 CANCELLED 되지 않은 상태가 일시적으로 발생할 수 있다. 결제가 FAILED로 확정되면 배치 재시도는 없으므로 운영팀 수동 보정 또는 향후 Outbox Pattern으로 해결한다.

Alternatives Considered

옵션	Pros	Cons
A. Timeout만 적용	구현 단순	PG 지속 장애 시 매 요청마다 Timeout까지 스레드 점유, Cascading Failure 완전 차단 불가
B. Timeout + Retry만 적용	A보다 회복력 향상	반복 실패 시 Retry Storm 위험, CB 없으면 이미 죽은 PG에 계속 호출
C. Timeout + Retry + CircuitBreaker 조합	장애 확산 차단 + 일시 장애 회복 + 빠른 Fallback	설정값 튜닝 필요, 구현 복잡도 증가

선택 근거: C안. CB가 열리면 스레드가 즉시 반납되고 PG에 트래픽이 끊겨 회복 시간을 준다. PENDING + 배치 조합으로 Timeout/CB Open 케이스의 정합성을 보장한다. Retry는 일시적 500 에러에만 적용해 Retry Storm을 방지한다.

Cross-cutting Concerns

Observability

K6로 30 TPS 부하를 주면서 PG 지연 시나리오를 돌리면 CB 동작을 p99로 관찰할 수 있다.

[CB Closed — PG 지연 발생]
  http_req_duration p99 → 급등 (Timeout 400ms 대기)
  http_req_failed rate  → 증가

[CB Open 전환 시점]
  p99 → 갑자기 낮아짐  ← 핵심 관찰 포인트
  fallback 비율        → 증가

[CB Open 구간]
  p99 → 회복 (Fallback은 즉시 반환)
  PG 트래픽 → 0

CB가 없다면 p99가 내내 높은 상태를 유지한다. "PG 장애 → 일정 시간 후 p99 급락" 패턴이 보이면 CB가 제대로 동작한다는 증거다.

Scalability

PENDING 건수가 많아지면 배치 실행 시간이 길어질 수 있다. 건수 제한(페이징) 처리로 대응 가능하다.

Known Limitations

handleCallback() FAILED 경로에서 getById()(잠금 없음) → cancelBySystem()(FOR UPDATE) 사이에 사용자 수동 취소가 끼어드는 TOCTOU 레이스 컨디션이 존재한다. 30초 배치가 PENDING을 재확인해 최종 상태로 수렴되므로 허용한다.
PG SUCCESS + 주문 CANCELLED 케이스는 pg-simulator에 취소 API가 없어 자동화 불가다. 실무에서는 PG 취소 API 호출로 자동화 가능하다.
split-commit의 완전한 해결은 Outbox Pattern 도입이 필요하다.

[Benchmark] MySQL 인덱스 전략 비교 — 좋아요 순 상품 목록 최적화 (5주차 · 6팀 · 조수현)

Coding-Su — Mon, 22 Jun 2026 17:22:27 +0900

TL;DR

상품 목록 API의 좋아요 순 정렬 성능을 확보하기 위해 13개 시나리오에서 인덱스 전략을 실측 비교했다.
brand_id 단일 인덱스만으로 풀스캔 대비 100ms → 0.1ms(약 1,000배) 를 달성했으며,
읽기 성능이 사실상 동일한 반정규화 vs 분리 테이블 중
동시 쓰기의 락 경합 격리를 이유로 product_like_view 분리 테이블을 선택했다.

Question — 무엇을 비교했는가

결정해야 했던 것

브랜드별 상품 목록을 좋아요 순으로 정렬하는 API에서 두 가지 질문을 동시에 풀어야 했다.

인덱스 전략: 인덱스 없음 / 단일(brand_id) / 복합(brand_id, like_count DESC) / 커버링 중 어느 수준까지 필요한가?
like_count 저장 구조: products 테이블에 컬럼으로 두는 반정규화 vs 별도 product_like_view 테이블로 분리하는 분리 테이블 중 무엇을 선택할 것인가?

두 결정은 독립적이지 않다. like_count 저장 위치가 달라지면 인덱스 설계도 달라지고, 쓰기 경로의 락 경합 구조도 달라진다.

비교 대상

축	후보
인덱스 전략	없음 → `(brand_id)` → `(brand_id, like_count DESC)` → 커버링
like_count 구조	반정규화 `products.like_count` vs 분리 테이블 `product_like_view`
정렬 조건	좋아요 순 / 최신순 / 가격순 / 복합 필터(브랜드 + 가격 범위 + 좋아요)
연관 쿼리	좋아요 목록, 구매 목록, 재고 JOIN

Setup — 측정 환경

항목	값
DB	MySQL 9.7 (로컬, macOS arm64)
products	996,327건
likes	2,490,470건
brands	7,500개 (brand당 평균 133건)
like_count 분포	0개(164K), 1~10개(834K), 11~100개(82건), 100초과(1K건)
측정 도구	자체 SQL 스크립트 — `EXPLAIN FORMAT=TRADITIONAL` + `NOW(6)` 기반 마이크로초 측정
공통 조건	`brand_id = 1`, `LIMIT 20`, OFFSET 0(1페이지) vs OFFSET 500,000(25,000페이지)

데이터는 seed 스크립트로 직접 생성했다. 브랜드 카디널리티(7,500개)와 brand당 상품 수(평균 133건)를 의도적으로 설계해서, 인덱스가 실제로 필터를 얼마나 줄여주는지 검증할 수 있도록 했다.

Results — 측정 결과

Round 1~4: 브랜드별 좋아요 순 (핵심 시나리오)

라운드	인덱스 전략	구조	OFFSET	Extra	실행시간
1	없음	반정규화	0	Using filesort	103ms
1	없음	반정규화	500,000	Using filesort	102ms
2	`(brand_id)`	반정규화	0	Using where; Using filesort	0.10ms
2	`(brand_id)`	반정규화	500,000	Using where; Using filesort	0.09ms
3	`(brand_id, like_count DESC)`	반정규화	0	Using where (filesort 제거)	0.09ms
3	`(brand_id, like_count DESC)`	반정규화	500,000	Using where	0.08ms
4	커버링 `(brand_id, like_count DESC, id, name, price)`	반정규화	0	Using where	0.12ms
4	커버링	반정규화	500,000	Using where	0.11ms

첫 번째 발견: 인덱스 없음 → (brand_id) 단일 인덱스 한 줄로 1,000배 개선된다.
이유는 카디널리티에 있다. brand_id = 1 조건으로 996K 행이 즉시 133건으로 줄어든다. 이후 filesort는 133건만 대상으로 하므로 메모리 정렬 마이크로초 수준이 된다.

두 번째 발견: 복합 인덱스 (brand_id, like_count DESC) 는 filesort 자체를 제거하지만, 실행시간은 0.09ms로 단일 인덱스(0.10ms)와 차이가 거의 없다.
이유도 동일하다 — 어차피 133건을 정렬하는 것은 인덱스 순서를 타든 filesort를 하든 체감 차이가 없는 수준이다.

세 번째 발견: 커버링 인덱스는 기대와 달리 복합 인덱스보다 오히려 미세하게 느렸다(0.12ms).
deleted_at IS NULL 조건이 인덱스에 없어서 테이블 접근이 필요하고, 인덱스 크기 자체가 커져서 B-tree 탐색 비용이 소폭 증가한 것으로 판단된다. deleted_at까지 포함하면 커버링 조건이 깨지고, 포함시키면 인덱스 크기 문제가 더 심해진다.

Round 5: 분리 테이블 `product_like_view` JOIN

인덱스	실행시간	Extra
없음	111ms	Using filesort
`(brand_id)` 단일	0.12ms	Using filesort
`(brand_id, like_count DESC)` 복합	0.12ms	Using filesort
커버링	0.15ms	Using filesort

분리 테이블은 JOIN으로 인해 인덱스 종류와 무관하게 항상 Using filesort 가 발생한다.
하지만 brand_id 필터 후 133건만 대상으로 하므로 실행시간은 0.12~0.15ms로 반정규화와 실질적으로 동일하다.
분리 테이블 구조에서 추가 인덱스를 더 걸어도 성능 개선이 없다는 의미이기도 하다.

Round 6: 정렬 조건별 비교

정렬	인덱스 없음	복합 인덱스
최신순 `created_at DESC`	123ms	0.10ms
가격순 `price ASC`	108ms	0.10ms

정렬 컬럼이 바뀌어도 패턴은 동일하다. 각 정렬마다 (brand_id, 정렬컬럼 방향) 복합 인덱스가 필요하다.

Round 9: 전체 좋아요 순 — OFFSET의 함정

인덱스	OFFSET	실행시간
없음	0	128ms
없음	500,000	242ms
`(like_count DESC)` 단일	0	0.13ms
`(like_count DESC)` 단일	500,000	253ms
커버링	0	0.25ms
커버링	500,000	264ms (풀스캔으로 전환)

OFFSET 500,000에서 인덱스 스캔이 253ms로 올라가며 풀스캔(242ms)과 비슷해졌다.
옵티마이저가 인덱스를 통해 500,020번째 행을 읽는 비용이 풀스캔보다 비싸다고 판단해 인덱스를 포기했다.
OFFSET 기반 페이지네이션의 구조적 한계이며, 실서비스에서는 커서 기반 페이지네이션이 필요함을 시사한다.

Round 10: 복합 필터 (브랜드 + 가격 범위 + 좋아요 순)

인덱스	Extra	실행시간
없음	Using filesort	103ms
`(brand_id)`	Using filesort	0.12ms
`(brand_id, like_count DESC)`	Using where (filesort 제거)	0.10ms
`(brand_id, price ASC)`	Using index condition; Using filesort	0.10ms

price BETWEEN 같은 range 조건이 있어도 (brand_id, like_count DESC) 인덱스는 filesort를 제거한다.
MySQL이 brand_id = 1 구간을 like_count 내림차순으로 읽으면서 price 조건을 행별로 필터링하기 때문이다.
반면 (brand_id, price ASC) 인덱스는 range 이후 정렬 컬럼이 달라 filesort가 불가피하다.

Round 11: stocks JOIN — hash join의 함정

인덱스	type(p)	type(s)	Extra	실행시간
없음	eq_ref	ALL	Using filesort	541ms
products: `(brand_id)`	ref	ALL	hash join + Using filesort	0.16ms
products: `(brand_id, like_count DESC)`	ref	ALL	hash join + Using filesort	0.15ms
+ stocks: `(product_id, quantity)`	ref	ref	nested loop + filesort 제거	0.16ms

(brand_id, like_count DESC) 인덱스 단독으로는 filesort가 제거되지 않았다.
hash join이 행 처리 순서를 파괴하므로 인덱스 정렬 순서를 보장할 수 없기 때문이다.
stocks에 (product_id, quantity) 인덱스를 추가하면 hash join → nested loop join으로 전환되어 비로소 filesort가 제거된다.

반정규화 vs 분리 테이블 — 읽기/쓰기 종합

기준	반정규화	분리 테이블
브랜드별 좋아요 순 읽기	0.08ms (filesort 제거)	0.12ms (filesort 있음)
실질적 차이	—	0.04ms
좋아요 단건 쓰기	~1.5ms	~1.0ms
동시 10명	~2ms	~1ms
동시 100명	10~30ms (스파이크)	~2ms
동시 1,000명	100ms+	5~10ms

동시 쓰기 성능 차이의 원인은 락 경합 범위다.
products는 상품 목록/상세 등 모든 API가 읽는 핫 테이블이다.
반정규화 구조에서는 좋아요 등록/취소마다 products.like_count UPDATE가 일어나고, 동시 사용자가 늘수록 조회 API와의 락 경합이 심화된다.
product_like_view는 좋아요 연산만 접근하는 테이블이므로 락 범위가 격리된다.

Decision

선택

product_like_view 분리 테이블 + products(brand_id) 단일 인덱스

선택 이유

읽기 성능 차이 0.04ms는 실서비스에서 의미 없는 수준이다.
brand_id 인덱스가 먼저 ~133건으로 행 수를 줄이면, 이후 정렬은 메모리 내 마이크로초 연산이기 때문에 구조 차이가 희석된다.

반면 쓰기 경로에서의 차이는 실질적이다.
좋아요는 사용자가 실시간으로 발생시키는 이벤트다. 동시 요청이 늘어날수록 products 테이블의 락 경합이 상품 목록/상세 조회까지 영향을 미친다.
분리 테이블은 이 문제를 구조적으로 차단한다.

포기한 것

반정규화 + 복합 인덱스의 filesort 제거: 0.04ms 이득. 읽기 최고 성능을 포기했다.
단순한 스키마: 테이블이 하나 늘고, 좋아요 등록/취소 시 product_like_view 동기화 로직을 애플리케이션에서 관리해야 한다.

최종 인덱스 목록

테이블	인덱스	용도
products	`(brand_id)`	브랜드별 상품 필터
products	`(brand_id, created_at DESC)`	최신순 정렬
products	`(brand_id, price ASC)`	가격순 정렬
product_like_view	`(like_count DESC, product_id)`	전체 좋아요 순 커버링
likes	`(member_id, created_at DESC)`	좋아요 목록 시간순
orders	`(member_id, created_at DESC)`	구매 목록
order_items	`(order_id, product_id)`	주문 상세 JOIN

Future Work

커서 기반 페이지네이션: OFFSET 500K 시나리오에서 인덱스 스캔도 253ms로 올라가는 것을 확인했다. 실서비스에서는 WHERE like_count < :cursor 형태의 커서 방식이 필요하다.
product_like_view 정합성: 좋아요 등록/취소 트랜잭션 실패 시 like_count 불일치 가능성이 있다. 정렬 참고용 수치이므로 소폭 오차는 허용하지만, 모니터링 기준값 설정이 필요하다.
재평가 시점: 브랜드당 평균 상품 수가 현재 133건을 크게 넘어서거나, 좋아요 동시 요청이 수백 RPS 이상으로 증가하면 반정규화 재검토 여지가 있다.

[Design Doc] 쿠폰 테이블 설계 (6팀, 4주차, 조수현)

Coding-Su — Fri, 12 Jun 2026 17:25:17 +0900

TL;DR

CouponTemplate과 UserCoupon을 분리하고, isActive(신규 발급 차단)와 isBlocked(기존 쿠폰 전량 차단)를 별도 책임으로 설계했다. CouponStatus는 DB에 저장하지 않고 조회 시점에 계산한다.

Introduction & Goals

Context: 쿠폰 정책(할인율, 유효기간)과 발급본(소유자, 사용 여부)을 하나의 테이블로 관리하면 정책 변경 시 발급된 전체 row가 영향을 받는다. 100만 명이 발급받은 쿠폰의 할인율이 잘못됐으면 100만 row를 UPDATE해야 한다.
Goals: 정책 변경이 기존 발급 쿠폰에 소급 적용되지 않는 구조. 운영자가 신규 발급만 막거나, 기존 쿠폰 사용까지 막거나, 두 가지를 독립적으로 제어할 수 있을 것.

Detailed Design

Data Models

CouponTemplate
  id, name (수정 가능)
  type, value, minOrderAmount, expiredAt → 불변
  isActive   → 신규 발급 차단 스위치
  isBlocked  → DELETE API 호출 시 true, 기존 발급 쿠폰 전량 차단

UserCoupon
  id, memberId, templateId
  usedAt     → null: AVAILABLE, not null: USED
  @Version version  → 낙관적 락
  UNIQUE(memberId, templateId)

불변 필드를 둔 이유가 있다. expiredAt을 운영자가 당길 수 있으면 "7일 유효"로 받은 쿠폰이 갑자기 "3일 유효"가 된다. 발급 시점의 조건이 소급 변경되면 안 되기 때문에 type, value, minOrderAmount, expiredAt은 생성 후 수정 불가다.

수정이 필요하면 기존 템플릿을 isActive=false로 내리고 새 템플릿을 만든다. 번거롭지만 그게 맞는 방향이다.

CouponStatus 동적 계산

status 컬럼은 DB에 저장하지 않는다.

CouponStatus getStatus(LocalDateTime templateExpiredAt, boolean templateBlocked) {
    if (templateBlocked) return BLOCKED;
    if (templateExpiredAt.isBefore(LocalDateTime.now())) return EXPIRED;
    if (usedAt != null) return USED;
    return AVAILABLE;
}

저장하면 두 가지 문제가 생긴다. expiredAt이 이미 있는데 status=EXPIRED를 따로 저장하면 중복 데이터다. 그리고 배치가 돌기 전 짧은 시간 동안 expiredAt은 지났는데 status는 AVAILABLE인 row가 존재할 수 있다. 어느 쪽이 진실인지 모호해진다.

중복 발급 방지

서비스 레이어의 exists 체크는 의미 없다. 두 요청이 동시에 exists를 통과하면 둘 다 INSERT를 시도한다. TOCTOU 문제다.

실제 보호는 UNIQUE(memberId, templateId) 제약이 한다. 충돌 시 DataIntegrityViolationException → ApiControllerAdvice에서 409로 변환.

Alternatives Considered

옵션	Pros	Cons
A. 단일 테이블	구조 단순	정책 변경 시 발급 전체 row UPDATE, 소급 적용 위험
B. isActive 하나로 발급 차단 + 사용 차단 통합	필드 추가 없음	isActive 의미 두 가지 혼용 — 코드 읽는 사람이 어느 쪽인지 모름
C. UserCoupon에 isBlocked 추가	개별 차단 가능	100만 건 발급이면 100만 row UPDATE 필요
D. CouponTemplate에 isBlocked 추가 (채택)	row 1개 변경으로 전량 차단, 책임 분리 명확	필드 하나 추가

선택 근거: 운영 시나리오는 "잘못 발급된 쿠폰 전량 차단"이다. UserCoupon에 넣으면 발급 건수에 비례한 UPDATE가 필요하다. CouponTemplate에 넣으면 row 1개만 바꾸면 된다. isActive는 신규 발급 차단 단일 책임을 유지하고, isBlocked는 기존 쿠폰 사용 차단 책임을 분리했다.

Cross-cutting Concerns

Scalability: UserCoupon 목록 조회는 CouponTemplate JOIN이 필수다. 목록 조회마다 template를 개별 조회하면 N+1이 생긴다. JOIN 쿼리로 한 번에 가져온다.
Observability: CouponTemplate.isBlocked를 true로 바꾸는 DELETE API는 되돌리기 어렵다. 운영자 실수 방지를 위해 감사 로그가 필요한 시점이다.

[Design Doc] 레이어드 아키텍처 설계 — 4개 레이어, 컴포넌트, 실제 구현 (3주차 · 6팀 · 조수현)

Coding-Su — Fri, 29 May 2026 16:26:54 +0900

TL;DR

4개 레이어(interfaces, application, domain, infrastructure)로 구성된 레이어드 아키텍처를 적용했다.
의존 방향은 interfaces → application → domain ← infrastructure 단방향으로 강제하고,
DIP(의존성 역전 원칙)로 domain이 Spring/JPA/BCrypt 같은 인프라 기술을 모르는 구조를 만들었다.

Introduction & Goals

커머스 백엔드 API를 설계할 때 두 가지 문제를 피하고 싶었다.

기술 의존 전파: Spring Security, JPA 같은 인프라 기술이 비즈니스 로직에 직접 침투하는 것
책임 불명확: "이 코드는 어느 레이어에 있어야 하나?"라는 질문에 명확히 답할 수 없는 구조

레이어드 아키텍처 + DIP로 두 문제를 해결하고, MSA 이행 시에도 레이어 구조 변경 없이 호출 방식만 교체할 수 있는 설계를 목표로 했다.

Goals:

interfaces → application → domain ← infrastructure 의존 방향 단방향 강제
domain이 Spring, JPA, BCrypt를 import하지 않도록 유지
경계 위반 경로를 코드 구조 자체로 없앰 (문서 규칙이 아닌 컴파일 에러로 강제)

System Architecture

클라이언트
     ↕ HTTP (JSON)
┌─────────────────────────────────────────┐
│  interfaces / api                       │
│  Controller · DTO · ApiControllerAdvice │
│  LoginInterceptor · WebMvcConfig        │
└─────────────────────────────────────────┘
     ↕ Info (record)
┌─────────────────────────────────────────┐
│  application                            │
│  Facade · Service · Info                │
└─────────────────────────────────────────┘
     ↕ Model
┌─────────────────────────────────────────┐
│  domain                                 │
│  Model · VO · Repository 인터페이스     │
│  PasswordHasher 인터페이스              │
└──────────────↑──────────────────────────┘
               │ 구현 (DIP)
┌─────────────────────────────────────────┐
│  infrastructure                         │
│  XJpaRepository · XRepositoryImpl       │
│  BCryptPasswordHasher                   │
└─────────────────────────────────────────┘
     ↕ DB (MySQL)

의존 규칙:

① interfaces → application  : Controller는 Facade만 호출. Model import 금지.
② application → domain      : Facade·Service는 Model·Repository 인터페이스 사용.
③ domain ← infrastructure   : domain이 정의한 인터페이스를 infrastructure가 구현(DIP).

패키지 구조

src/main/java/com/loopers/
├── interfaces/api/
│   ├── {domain}/     XController.java, XDto.java
│   ├── common/       ApiControllerAdvice.java, ApiResponse.java
│   └── config/       LoginInterceptor.java, WebMvcConfig.java
├── application/
│   └── {domain}/     XFacade.java, XService.java, XInfo.java
├── domain/
│   ├── {domain}/     XModel.java, XRepository.java
│   │   └── vo/       LoginId.java, Email.java, PlainPassword.java ...
│   └── common/       CoreException.java, ErrorType.java, BaseEntity.java
└── infrastructure/
    └── {domain}/     XJpaRepository.java, XRepositoryImpl.java

Layer 1. interfaces / api

책임: HTTP 요청을 파싱하고 application에 위임한 뒤, 결과를 HTTP 응답으로 변환한다.
비즈니스 로직이 없다. 도메인 객체(XModel)를 직접 생성하거나 반환하지 않는다.

컴포넌트	책임
`XController`	HTTP 엔드포인트 정의. Facade 호출, Info → Response 변환
`XDto`	HTTP 입출력 형태 정의. 로직 없음
`ApiControllerAdvice`	`CoreException` → HTTP 상태코드 변환 (전역 예외 처리)
`LoginInterceptor`	헤더에서 인증 정보 파싱, 인증 검증, `userId`를 request attribute에 저장
`WebMvcConfig`	인터셉터 등록. blacklist 방식 — 전체 적용 후 공개 경로만 제외

설계 포인트:

Controller는 XModel을 import하지 않는다. BrandInfo info = brandFacade.create(...) 처럼 Info만 받아 DTO로 변환한다.
LoginInterceptor의 책임은 인증만이다. 데이터를 Controller에 전달하면 인증 + 데이터 전달 두 책임이 생기고 Controller가 Interceptor 구조에 결합된다.
catch(CoreException e) — Exception이 아닌 CoreException만 잡아 401로 변환한다. DB 장애 같은 시스템 오류는 그대로 전파해 500이 된다.
WebMvcConfig는 new LoginInterceptor(...) 아닌 Bean 주입으로 받는다. new로 생성하면 Spring이 관리하는 Bean과 별개 인스턴스가 두 개 생긴다.
whitelist(인증 경로를 하나씩 추가) 대신 blacklist를 채택했다. 새 API 추가 시 인증 누락 위험이 없다.

Layer 2. application

책임: 도메인 Service를 조합해 유스케이스를 완성한다. Model → Info 변환으로 도메인 객체가 Controller까지 나가지 못하게 막는다.

컴포넌트	책임	Repository 의존
`XFacade`	여러 Service 조합, 유스케이스 진입점, Model → Info 변환	❌
`XService`	단일 도메인 유스케이스, 트랜잭션 관리	✅ 하나만
`XInfo`	Facade 출력 DTO. 서버 내부 계약. Record로 구현	—

설계 포인트:

Service가 Repository 하나에만 의존하는 이유: 여러 도메인을 조율하는 로직은 Facade가 담당한다. Service가 여러 Repository를 의존하면 Facade의 존재 이유가 없어진다.
Facade가 얇아 보여도 자리를 잡아두는 이유: BrandFacade는 지금 위임 + Info 변환뿐이지만, ProductFacade처럼 Brand 존재 확인 → Product 저장 → Stock 생성을 한 흐름에서 조율하는 Facade가 있어야 Controller가 여러 Service를 직접 건드리지 않아도 된다.
DTO(외부 계약) vs Info(내부 계약) 분리: 지금은 BrandInfo(id, name)와 BrandResponse(id, name)이 같아 보여도 나중에 갈라진다. Info에 productCount가 추가돼도 DTO는 그대로라 클라이언트에 영향이 없다.

OrderFacade의 핵심 흐름: 확인을 먼저 전체 통과시킨 후 차감해야 부분 차감 없이 All-or-Nothing이 보장된다.

1. 상품 목록 조회
2. productId 오름차순 정렬     ← 모든 트랜잭션이 같은 순서로 락 → 데드락 방지
3. 재고 SELECT FOR UPDATE      ← 비관적 락
4. isAvailable() 전체 선검사  ← 하나라도 부족하면 여기서 중단, DB 변경 없음
5. Order + OrderItem 저장      ← 가격·상품명 스냅샷
6. 재고 일괄 차감              ← 더티 체킹으로 save() 없이 반영

LikeFacade: likeService.create()와 productService.increaseLikeCount()를 같은 @Transactional 안에서 호출한다. 분리하면 Like는 있는데 likeCount가 안 오르는 데이터 불일치가 생긴다.

Layer 3. domain

책임: 비즈니스 규칙을 캡슐화한다. Spring/JPA에 의존하지 않는다.
단, @Entity, @Embeddable 같은 JPA 매핑 어노테이션은 사용한다.

컴포넌트	책임	Spring 의존
`XModel` (Entity)	도메인 상태 보유, 비즈니스 불변식 보호, 상태 변경 메서드	`@Entity` (매핑만)
`VO`	값 타입, 불변, 생성자에서 즉시 검증	`@Embeddable` (매핑만)
`XRepository` (인터페이스)	영속성 인터페이스 정의. JPA를 import하지 않음	❌
`PasswordHasher` (인터페이스)	비밀번호 해싱/검증 포트. BCrypt를 import하지 않음	❌
`CoreException` / `ErrorType`	도메인 예외. `ErrorType`이 HTTP 상태코드와 묶임	❌
`BaseEntity`	`id`, `createdAt`, `updatedAt`, `deletedAt` 공통 필드	`@MappedSuperclass`

설계 포인트:

Model 생성자에서 VO 즉시 생성: this.loginId = new LoginId(loginId) — VO 생성자가 검증을 담당하므로 Model 생성자는 유효성 검사를 직접 하지 않는다.

VO는 Record 불가: @Embeddable + Record 조합은 QueryDSL APT가 컴파일 타임에 ElementKind.RECORD를 처리하지 못해 컴파일 에러가 난다. JPA 명세도 no-arg 생성자를 요구하는데 Record는 이를 지원하지 않는다. 일반 클래스 + @NoArgsConstructor(PROTECTED) + @EqualsAndHashCode로 구현했다.

@Embeddable
@EqualsAndHashCode
@NoArgsConstructor(access = AccessLevel.PROTECTED) // JPA 명세: no-arg 생성자 필요
public class LoginId {
    private String value;
    public LoginId(String value) {
        if (!value.matches("^[a-zA-Z0-9]+$"))
            throw new CoreException(ErrorType.BAD_REQUEST, "아이디는 영문과 숫자만 사용 가능합니다.");
        this.value = value;
    }
    public String value() { return value; }
}

VO 배치 기준: 값 하나의 유효성 → VO 생성자. 객체 자신의 상태 변경 → Entity 메서드. 여러 객체 사이의 정책 → Domain Service (현재 미도입). DB 조회 필요 → Application Service.
PlainPassword 생성자 오버로딩: 비밀번호 변경 시 형식만 검증하는 생성자와, 회원가입 시 형식 + 생년월일 포함 여부를 검증하는 생성자를 분리했다.

ProductModel에 @ManyToOne BrandModel 대신 Long brandId: @ManyToOne이면 product.getBrand().update()가 컴파일된다 — 코드 구조 자체로 타 도메인 상태 변경 경로를 막는다.

// ❌ @ManyToOne → 타 도메인 상태 변경 경로가 열림
product.getBrand().update("새 브랜드명");

// ✅ Long brandId → 이 코드 자체가 컴파일 안 됨
private Long brandId;

OrderItemModel에 스냅샷 저장: productId만 저장하면 이후 상품 가격이 바뀔 때 과거 주문 금액이 소급 변경된다. 주문 시점 상품명·가격을 함께 저장해 상품 수정·삭제와 무관하게 주문 데이터를 보존한다.

PasswordHasher 인터페이스 (DIP 포트): UserModel과 UserService는 이 인터페이스에 의존한다. BCrypt가 뭔지 모른다. domain 레이어에 spring-security import가 없다.

// domain — spring-security import 없음
public interface PasswordHasher {
    String hash(String raw);
    boolean matches(String raw, String encoded);
}
// infrastructure — BCryptPasswordEncoder는 여기서만 등장
@Component
public class BCryptPasswordHasher implements PasswordHasher { ... }

Repository 인터페이스: JPA를 import하지 않는 순수 인터페이스. 파라미터와 반환 타입만 정의한다. findByProductIdForUpdate처럼 비관적 락 의도를 메서드 이름에 명시한다.
CoreException → HTTP 변환: domain은 CoreException(ErrorType.BAD_REQUEST, "...") 만 던진다. ApiControllerAdvice가 ErrorType을 보고 HTTP 상태코드로 변환한다. domain은 HTTP를 모른다.

Layer 4. infrastructure

책임: domain이 정의한 Repository 인터페이스와 PasswordHasher를 기술로 구현한다. 기술 선택(JPA, Redis, BCrypt 등)은 이 레이어에서만 이루어진다.

컴포넌트	책임
`XJpaRepository`	Spring Data JPA 인터페이스. `@Lock`, `@Query` 등 JPA 어노테이션 사용
`XRepositoryImpl`	`domain`의 `XRepository` 구현체. `XJpaRepository`에 위임
`BCryptPasswordHasher`	`PasswordHasher` 구현체. `BCryptPasswordEncoder`에 위임

설계 포인트:

비관적 락은 JpaRepository에서: "어떻게 DB에서 읽어올 것인가"는 인프라 관심사다. StockModel은 DB를 모르는 순수 도메인 객체여야 한다.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("SELECT s FROM StockModel s WHERE s.productId = :productId AND s.deletedAt IS NULL")
Optional<StockModel> findByProductIdForUpdate(@Param("productId") Long productId);

@Embedded 필드 경로 탐색: findByLoginIdValue(String) — loginId가 LoginId VO이고 내부 필드가 value이므로, Spring Data JPA가 loginId.value를 파싱해 WHERE login_id = ? 쿼리를 생성한다.
BCryptPasswordHasher: PasswordHasher 인터페이스를 구현해 DIP를 완성한다. Spring Security 의존이 이 클래스에서만 발생한다.

Cross-cutting Concerns

Soft Delete

모든 엔티티는 BaseEntity를 상속해 deletedAt 컬럼을 갖는다.
삭제 시 deletedAt을 현재 시각으로 설정하고, @SQLRestriction("deleted_at IS NULL")이 조회 쿼리에 자동으로 필터를 추가한다.

Soft Delete + Unique 제약 (MySQL)

활성 계정 간 loginId, email 중복 불허 + 탈퇴 후 재가입 허용을 충족해야 했다.
MySQL은 WHERE deleted_at IS NULL 조건의 Filtered Index를 지원하지 않아 Generated Column으로 우회했다.

ALTER TABLE users
  ADD COLUMN login_id_unique_key VARCHAR(20)
  GENERATED ALWAYS AS (IF(deleted_at IS NULL, login_id, NULL)) VIRTUAL;
CREATE UNIQUE INDEX uk_users_login_id_active ON users (login_id_unique_key);

활성 계정은 login_id 값을, 탈퇴 계정은 NULL을 갖는다. MySQL Unique 제약은 NULL을 중복으로 보지 않으므로 탈퇴 계정이 아무리 많아도 unique 위반이 없다.

애그리거트 경계

같은 애그리거트  → @OneToMany 직접 참조 허용
  Order + OrderItem: 항상 함께 생성·삭제, 같은 트랜잭션

다른 애그리거트  → Long ID로만 참조, FK 제약 없음
  Product → Brand: Long brandId
  Stock → Product: Long productId
  Like, Order → Member: Long memberId

읽기(Query)  → JOIN 허용
쓰기(Command) → 경계 엄격히 유지

FK 없이 애플리케이션에서 검증하는 이유: MSA 전환 시 다른 서비스 DB에 FK를 걸 수 없다. 모놀리스부터 같은 구조를 써두면 코드 변경 없이 Service 간 호출 방식(직접 → HTTP API)만 교체하면 된다.

Alternatives Considered

항목	대안	선택	이유
Service 위치	`domain` 레이어	`application` 레이어	Repository 의존 Service는 인프라를 간접 필요로 함
Brand-Product 참조	`@ManyToOne BrandModel`	`Long brandId`	컴파일 레벨에서 타 도메인 상태 변경 경로 차단
비밀번호 해싱	`UserModel`에서 직접 BCrypt	`PasswordHasher` 포트	DIP — domain이 인프라 기술을 import하지 않음
Facade 유무	Controller에서 Service 직접 조합	Facade 경유	Controller가 여러 Service를 조율하면 레이어 위반
VO 구현	Java Record + `@Embeddable`	일반 클래스 + Lombok	QueryDSL APT 컴파일 에러, JPA no-arg 생성자 스펙 위반
WebMvcConfig 경로	whitelist	blacklist	새 API 추가 시 인증 누락 위험 제거

Lessons Learned

1. Repository 인터페이스가 domain에 있다고 Service도 domain에 있는 게 아니다

Repository 인터페이스가 domain에 있는 이유는 DIP다. Service가 그 인터페이스를 사용한다는 사실은 변하지 않고, Service는 infrastructure를 간접 필요로 한다. 그 책임은 application 레이어에 있다.

2. 컴파일 레벨에서 경계를 강제하라

Long brandId를 쓰면 product.getBrand().update()가 컴파일 자체가 안 된다. 경계를 문서나 팀 규약으로 강제하는 것보다 코드 구조로 위반 경로를 없애는 게 더 강력하다.

3. Service가 Repository 하나에만 의존하는 것이 Facade를 의미 있게 만든다

이 원칙이 없으면 Facade는 그냥 위임 클래스일 뿐이다. Service의 단일 의존 제약이 있어야 Facade가 "여러 도메인을 조율하는 레이어"라는 의미를 갖는다.

4. VO는 "이 값이 존재하기 위한 조건"을, Entity 메서드는 "이 객체의 상태 변경"을 담당한다

경계가 애매할 때 판단 기준: "이 로직이 없어도 이 값/객체는 존재할 수 있는가?" 없으면 안 된다 → 그 안에 넣는다. 외부 조건이다 → 바깥으로 꺼낸다.

5. VO를 Record로 구현하면 QueryDSL APT와 충돌한다

Hibernate 6이 런타임에서 Record를 우회 처리해줘도, QueryDSL APT는 컴파일 타임에 ElementKind.CLASS만 처리한다. "런타임에서 동작하는가"와 "생태계 도구 전체가 지원하는가"는 별개의 질문이다.

[Challenge Story] 주문·결제 동시성 제어 — 6개 문제를 연쇄 발견한 설계 여정 (2주차 · 6팀 · 조수현)

Coding-Su — Fri, 22 May 2026 16:12:52 +0900

TL;DR

주문/결제 시스템에서 동시성 문제를 하나씩 해결할 때마다 새로운 문제가 연쇄적으로 드러났다.
SAGA 패턴 → 취소 시 Lost Update → 데드락 → 이중 취소까지 6개 문제를 차례로 발견하고,
SELECT FOR UPDATE와 정렬 기반 락 획득 순서로 모두 해결했다.

문제 1: 결제 실패 중 새 주문 → 트랜잭션 분리로 보상 범위 명확화 (보상 자동 실행은 미구현)
    ↓
문제 2: 주문 취소 시 재고 Lost Update → 취소에도 SELECT FOR UPDATE 추가
    ↓
문제 3: 여러 상품 주문 시 데드락 → productId 오름차순 정렬로 해결
    ↓
문제 4: 이중 취소 요청 → Order에 SELECT FOR UPDATE 추가
    ↓
문제 5: PENDING 방치 → 배치 자동 취소 (잠재 리스크)
    ↓
문제 6: 결제 확정 주체 → 클라이언트 confirm 호출 (B방식, Webhook 예정)

Context (배경 및 목표)

어떤 시스템을 만드는가?: 외부 PG(결제대행사)와 연동하는 주문/결제 API. 재고 차감 → PG 결제 → 주문 확정의 흐름을 여러 사용자가 동시에 요청해도 안전하게 처리해야 한다.
가장 큰 기술적 도전 과제는?: PG 호출이 트랜잭션 경계 밖에 있어 기존 단일 트랜잭션 방식으로는 대응이 불가능하고, 주문·취소·재시도가 동시에 쏟아질 때 재고 정합성을 유지하는 것이다.

Design & Implementation (설계 및 구현)

핵심 기술 선택: 비관적 락 (`SELECT FOR UPDATE`)

낙관적 락(@Version)과 비교했을 때 재고 도메인에서는 비관적 락이 필수였다.

	낙관적 락	비관적 락
DB 음수 저장	발생 안 함	발생 안 함
재고 있는데 주문 실패	발생 가능 (충돌 시 재시도 반복 → 결국 실패)	발생 안 함 (대기 후 처리)
Throughput	높음	낮음 (대기 발생)
적합한 상황	충돌 빈도 낮은 데이터	충돌 빈도 높은 데이터

선택 근거: 재고는 충돌 빈도가 높고, 재고가 있으면 반드시 주문이 성공해야 한다는 요구사항이 핵심이다. 낙관적 락의 "충돌 → 재시도 → 또 충돌" 패턴은 재고가 남아 있는데 고객이 실패를 보는 상황을 만들어낸다.

Logic Flow

트랜잭션을 세 구간으로 분리한 SAGA 패턴을 기반으로 한다.

[TX 1] 재고 차감 + 주문 생성 (PENDING) → 커밋
    ↓ 트랜잭션 종료 후
PG 결제 요청 (외부 시스템, 트랜잭션 외부)
    ↓
결제 성공 → 클라이언트 confirm 호출 → [TX 2] PENDING → CONFIRMED
결제 실패 → 클라이언트 취소 호출 → [TX 3] 재고 복구 + CANCELLED

Engineering Challenges (트러블슈팅 및 최적화)

문제 1. 보상 트랜잭션이 다른 주문의 차감량을 덮어쓴다

처음 설계는 재고 차감 + PG 결제 + 주문 생성을 하나의 트랜잭션에 묶는 구조였다. 두 가지 문제가 있었다. PG 응답이 느린 동안 DB 락이 그대로 유지되고, 보상 트랜잭션 실행 중에 새 주문의 차감량까지 덮어쓸 수 있었다.

1번 주문: 재고 차감 → 결제 실패 → 보상 트랜잭션 실행 중
                                    ↓ (동시에)
                    2번 주문: 같은 상품 재고 차감
                                    ↓
1번 보상 완료 → 2번의 차감량까지 복구해버림

트랜잭션이 길수록 보상 범위가 불명확해진다. 외부 시스템(PG)을 트랜잭션 안에 넣으면 트랜잭션 길이를 통제할 수 없다.

트랜잭션 경계를 분리해 각 TX를 독립적으로 만들었고, 보상 범위가 명확해졌다.

	적용 여부	비고
로컬 트랜잭션 분리	✅	TX1 / TX2 / TX3 분리
보상 트랜잭션 자동 실행	❌	TX3(취소)는 클라이언트가 수동 호출해야 실행됨

완전한 SAGA가 되려면 실패를 감지하고 보상을 자동으로 트리거하는 메커니즘(이벤트 or 오케스트레이터)이 필요하다. 현재는 클라이언트가 호출하지 않으면 보상이 일어나지 않으며, 이것이 문제 3(PENDING 방치)의 근본 원인이기도 하다. Webhook 전환 시 PG가 서버에 직접 결과를 전달하므로 보상 자동화가 가능해진다.

문제 2. 재고 락 밖에서 생긴 두 가지 문제

재고 경로에는 락이 있었다. 문제는 그 바깥이었다.

데드락 — 여러 상품을 동시에 주문할 때

정렬 없이 items 순서대로 락을 잡으면 두 요청이 서로를 기다리는 순환 대기가 생긴다.

주문 A: [상품 1 락] 획득 → [상품 2 락] 대기
주문 B: [상품 2 락] 획득 → [상품 1 락] 대기 → 데드락

productId 오름차순 정렬로 해결했다. 주문 생성·취소 양쪽 모두 적용했다.

이중 취소 — Order 행에도 락이 필요했다

재고에는 락을 걸었는데 Order 상태 확인은 락 없이 읽고 있었다. 클라이언트 재시도 또는 추후 도입될 배치 자동 취소가 동시에 실행되면 두 요청이 모두 PENDING을 보고 재고를 두 번 복구한다.

취소 A: Order 읽기 (PENDING) → 재고 복구 중...
취소 B: Order 읽기 (PENDING) → 재고 복구 시작 → 중복 복구!

Order 조회에도 SELECT FOR UPDATE를 추가했다. 두 번째 요청은 반드시 CANCELLED를 보고 400을 반환한다.

문제 3. PENDING 방치 (클라이언트 미응답)

클라이언트가 confirm도 취소도 안 하면 재고가 차감된 채 PENDING이 영구 유지된다. B 방식(클라이언트 confirm)의 구조적 한계다. 배치 자동 취소 도입이 필요하다. 실제 PG 연동 시 Webhook으로 교체할 예정이다.

배치 스케줄러: PENDING 상태이고 생성 후 N분 경과한 주문 조회
→ 자동 취소 처리 (재고 복구 + CANCELLED)

문제 4. 결제 확정 주체 선택

방식	흐름	문제
A (Admin 수동)	Admin이 PG 대시보드 확인 후 confirm	주문량 많으면 현실적으로 불가능
B (Client 호출)	클라이언트가 PG 성공 후 confirm 호출	클라이언트 신뢰에 의존, 결제 없이 confirm 가능
C (Webhook)	PG가 서버에 자동 notify	가장 안전하나 현재 구현 범위 초과

현재 PG 연동이 없으므로 서버가 결제 여부를 검증할 방법이 없다. B 방식으로 흐름을 구현하고, 실제 PG 연동 시 Webhook으로 교체한다.

변경된 엔드포인트: PATCH /api/v1/orders/{orderId}/confirm (USER 권한)

Verification & Insight (검증)

문제	해결 방법	결과
보상 트랜잭션 범위 불명확	SAGA 패턴 (TX 분리)	보상 범위 명확화
취소 시 Lost Update	취소 경로에 `SELECT FOR UPDATE` 추가	Lost Update 제거
다중 상품 데드락	`productId` 오름차순 정렬	순환 대기 제거
이중 취소 중복 복구	Order 행 `SELECT FOR UPDATE`	직렬화로 중복 제거
처리량(Throughput) 영향	—	[미측정 — 부하 테스트 필요]

잠재 리스크

리스크	현재 대응	추후 개선
PENDING 방치 (클라이언트 미응답)	배치 자동 취소 도입 필요 (미구현)	Webhook으로 교체
클라이언트 신뢰 의존 (결제 없이 confirm 호출)	현재 허용	PG Webhook 수신 후 서버 검증
상품 수 많을수록 락 보유 시간 증가	productId 정렬로 데드락만 방지	배치/비동기 이벤트 방식 검토

Lessons Learned

락은 쓰는 경로뿐 아니라 읽는 경로도 확인해야 한다. 주문 생성에만 락이 있어도 취소 경로에 락이 없으면 Lost Update가 생긴다. read-modify-write 패턴이 있는 모든 경로를 빠짐없이 점검해야 한다.
트랜잭션 경계가 락 전략보다 먼저다. 외부 시스템(PG)을 트랜잭션 안에 넣으면 락 전략이 아무리 정교해도 락 보유 시간이 제어 불가능해진다. SAGA처럼 트랜잭션을 짧게 유지하는 것이 먼저다.
동시성 설계는 전체 흐름을 시나리오 단위로 반복 검토해야 허점이 없다. 주문 생성 직렬화 → 취소 Lost Update → 데드락 → 이중 취소의 순서처럼, 해결하고 나면 숨어 있던 다음 문제가 나온다.
SAGA의 본질은 트랜잭션 분리가 아니라 보상 자동화다. 트랜잭션을 쪼개는 것만으로는 SAGA가 아니다. 실패를 감지하고 보상을 자동으로 트리거하는 메커니즘이 없으면, 보상이 클라이언트 몫이 되고 PENDING 방치 같은 구조적 허점이 생긴다.

TDD와 DDD로 처음 개발해보며 얻은 것들

Coding-Su — Fri, 15 May 2026 17:58:40 +0900

이론으로만 알던 TDD와 DDD를 loopers에서 직접 적용하면서 "왜 이렇게 해야 하는가"를 몸으로 깨달은 기록.

TDD 방법론은 무엇인가?

TDD란 Test Driven Development의 약자로 '테스트 주도 개발'이다.

소프트웨어 방법론으로 작은 단위 테스트 케이스를 작성하고 이를 통과하는 코드를 추가하는 단계를 반복하여 구현한다. TDD의 개발 절차에는 Red -> Green -> Refactor를 반복하면서 Red 단계에서는 테스트 케이스에 맞는 실패하는 테스트 코드를 먼저 작성하고, Green 단계에서는 테스트를 성공시키기 위한 최소한의 코드를 작성한다. 마지막으로 Refactor 단계에서 중복 코드 제거, 일반화 등 리팩토링을 한다.

이 과정에서 중요한것은 실패하는 테스트 코드를 작성하기 전에는 동작하는 실제 코드를 작성하지 않는것과 테스트 코드를 통과하기 위해서는 최소한의 코드를 작성하는 것이다. 이를 통해 불필요한 설계를 테스트 케이스를 작성하면서 피할 수 있고, 정확한 요구 사항에 집중할 수 있게 된다.

TDD를 직접 써보고 나서

전에 테스트 코드를 공부할 때는 로직 구현을 먼저 완료하고, 테스트 코드를 작성하였다. 이 과정에서 왜 테스트 코드가 중요하다고 하는지 정확하게 알 지 못하였다. 그러다 보니 중요한 케이스를 빠뜨리기 쉽고, 무엇보다 테스트 코드 작성이 지루했다. 이미 코드가 정상적으로 동작을 하고있는데 테스트 코드 작성이 왜 중요한지 이해를 할 수 없었다.

TDD로 테스트 코드를 먼저 작성을 하고 로직을 작성하니 상황이 바뀌었다. 아직 로직이 없으니 테스트 케이스를 먼저 작성해야 했고, 테스트 케이스에 따라 테스트 코드를 먼저 작성하면서 어떤 API가 필요하고 필요 없는지를 생각하게 되었다.

TDD를 하면서 DDD에 대해서도 알게 되면서 Service가 아닌 Domain에 로직을 넣고, Domain을 설계해야 한다는 것을 알게 되었다.

DDD란 무엇인가?

DDD는 “데이터를 저장하는 객체”가 아니라
“업무 규칙을 수행하는 객체”를 만들기 위한 설계 방법론이다.

DDD를 이용하면 비즈니스 도메인에 집중하기 때문에 요구사항을 더 잘 이해하고 모델링 할 수 있고, 도메인 모델링을 통해 각 요소가 높은 응집도를 갖게 되어 코드의 가독성과 유지보수성이 향상된다.

DDD: Entity가 없어도 가능하다.

DDD를 처음 접했을 때 "서비스를 최대한 단순하게 만들고, 도메인에 넣는다"는 말을 들었다. 하지만 나는 MyBatis 환경에서 개발을 하면서 '@Entity' 클래스를 쓰지 않으니 DDD는 불가능하다고 생각했었다.

하지만 DDD는 ORM 기술이 아니라 설계 방식이다. '@Entity'의 유무가 핵심이 아니었다. DDD에서의 Entity는 식별자와 생명주기를 가지는 도메인 객체이고, DDD의 핵심은 비즈니스 규칙, 상태 변화 규칙, 불변성, 행위를 객체 안에 넣는 것을 의미한다. DTO에서 도메인 객체를 분리하면 MyBatis 환경에서도 DDD를 적용할 수 있다는 것을 알게 되었다.

MyBatis를 사용하면 자연스럽게 'DB -> DTO -> Service' 흐름이 강해진다. 비즈니스 로직이 모두 Service에 쌓이는 Transaction Script 패턴이 된다. 단순 CRUD라면 괜찮지만, 주문/결제/쿠폰처럼 규칙이 복잡해질수록 Service가 길어질 수 밖에 없는 구조로 이어진다.

핵심 개념 정리: Entity, VO, DTO

내가 알고있던 Entity가 아니라는 것을 알고 Entity와 VO, DTO에 대해 정리를 해보았다.

Entity (Model)

고유 ID가 있고, 상태가 변할 수 있으며, 비즈니스 로직을 직접 가진다.

public class User {
    private UserId id;
    private String loginId;
    private String password;
    private String name;

    public void changePassword(String newPassword) {
        validatePassword(newPassword);
        this.password = newPassword;
    }
}

VO (Value Object)

값 자체가 의미인 객체. ID가 없고, 불변이며, 생성 시점에 스스로 유효성을 검증한다. JPA의 @Embedded로 별도 테이블 없이 컬럼으로 저장되는 경우가 일반적이다.

public class Email {
    private final String value;

    public Email(String value) {
        if (!value.contains("@")) {
            throw new CoreException(ErrorType.BAD_REQUEST,
                "이메일 형식이 올바르지 않습니다.");
        }
        this.value = value;
    }
}

DTO (Data Transfer Object)

레이어 간 데이터를 전달만 하는 객체. 비즈니스 로직이 없고, Controller ↔ Facade ↔ Service 경계에서 사용한다.

// 요청 DTO
public record SignUpRequest(
    String loginId, String password, String name
) {}

// 응답 DTO (비밀번호는 포함하지 않음)
public record UserResponse(
    String loginId, String name, String email
) {}

한눈에 비교

	Entity	VO	DTO
DB 저장	O 별도 테이블	컬럼(Embedded)	X
고유 ID	O	X	X
불변	X	O	보통 O
비즈니스 로직	O	O (자기검증)	X
사용 위치	domain	domain	레이어 경계

DB 중심 사고 → 비즈니스 중심 사고

그동안 테이블 구조를 먼저 생각하고 코드를 짰다. DDD를 공부하면서 이 사고방식이 얼마나 Service를 망가뜨리는지 알게 됐다.
멘토님이 “기계적으로 코딩하지 말고 도메인 설계와 비즈니스 로직을 고민해야 한다”라고 말씀하셨을 때는 그 의미를 잘 이해하지 못했다. 그런데 지금 돌아보면, 단순히 DB 구조를 설계하라는 뜻이 아니었다.

도메인 객체는 DB 테이블 구조를 그대로 옮겨놓은 객체가 아니라, 실제 비즈니스 개념과 업무 규칙을 표현하는 객체라는 의미였다. 즉, 객체 안에 데이터만 담는 것이 아니라 업무 규칙과 행위를 함께 담아야 한다는 뜻이었다.

테이블 = 객체 X
비즈니스 개념 = 객체 O, DB는 단순 저장소
객체는 상태 + 행동 + 규칙을 함께 가진다
프로젝트 규모가 커지면 정책이 늘고, 예외 케이스가 늘고, Service가 자연스럽게 비대해진다. 도메인 객체에 책임을 나눠주면 Service는 흐름 조율(orchestration)과 트랜잭션 관리에만 집중할 수 있다.

결론 — DDD의 핵심은 비즈니스 개념을 객체로 모델링하고, 관련된 데이터와 행위를 하나의 책임으로 묶어 복잡한 비즈니스 로직을 이해하기 쉽고 유지보수하기 좋은 구조로 만드는 것이다. 결국 DDD는 객체지향 설계를 비즈니스 복잡성에 체계적으로 적용하는 방법론이라고 생각한다.

[Spring Boot] JWT를 이용한 인증/인가 구현하기(Spring Security X)

Coding-Su — Fri, 15 Nov 2024 20:05:51 +0900

JWT를 사용하기 위한 파일

FilterConfig.java

@Configuration
@RequiredArgsConstructor
public class FilterConfig {

    private final JwtUtil jwtUtil;

    @Bean
    public FilterRegistrationBean<JwtFilter> jwtFilter() {
        FilterRegistrationBean<JwtFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new JwtFilter(jwtUtil));
        registrationBean.addUrlPatterns("/*"); // 필터를 적용할 URL 패턴을 지정합니다.

        return registrationBean;
    }
}

우선 jwt를 필터에서 config 파일을 등록해줍니다.

JwtFilter.java

@Slf4j
@RequiredArgsConstructor
public class JwtFilter implements Filter {

    private final JwtUtil jwtUtil;
    private final Pattern authPattern = Pattern.compile("^/v\\d+/auth.*");

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
        Filter.super.init(filterConfig);
    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;

        String url = httpRequest.getRequestURI();

        // `/v{숫자}/auth`로 시작하는 URL은 필터를 통과하지 않도록 설정
        if (authPattern.matcher(url).matches()) {
            chain.doFilter(request, response);
            return;
        }

        // NOTE: 위의 방법이 이해가 어려운 분은 이런 방법을 사용하셔도 좋습니다.
//        if (url.startsWith("/v1/auth") || url.startsWith("/v2/auth")) {
//            chain.doFilter(request, response);
//            return;
//        }

        String bearerJwt = httpRequest.getHeader("Authorization");

        if (bearerJwt == null || !bearerJwt.startsWith("Bearer ")) {
            // 토큰이 없는 경우 400을 반환합니다.
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "JWT 토큰이 필요합니다.");
            return;
        }

        String jwt = jwtUtil.substringToken(bearerJwt);

        try {
            // JWT 유효성 검사와 claims 추출
            Claims claims = jwtUtil.extractClaims(jwt);

            // 사용자 정보를 ArgumentResolver 로 넘기기 위해 HttpServletRequest 에 세팅
            httpRequest.setAttribute("userId", Long.parseLong(claims.getSubject()));
            httpRequest.setAttribute("email", claims.get("email", String.class));

            chain.doFilter(request, response);
        } catch (SecurityException | MalformedJwtException e) {
            log.error("Invalid JWT signature, 유효하지 않는 JWT 서명 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "유효하지 않는 JWT 서명입니다.");
        } catch (ExpiredJwtException e) {
            log.error("Expired JWT token, 만료된 JWT token 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "만료된 JWT 토큰입니다.");
        } catch (UnsupportedJwtException e) {
            log.error("Unsupported JWT token, 지원되지 않는 JWT 토큰 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "지원되지 않는 JWT 토큰입니다.");
        } catch (IllegalArgumentException e) {
            log.error("JWT claims is empty, 잘못된 JWT 토큰 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "잘못된 JWT 토큰입니다.");
        } catch (Exception e) {
            log.error("JWT 토큰 검증 중 오류가 발생했습니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "JWT 토큰 검증 중 오류가 발생했습니다.");
        }
    }

    @Override
    public void destroy() {
        Filter.super.destroy();
    }
}

JWT 필터를 등록합니다.

	if (authPattern.matcher(url).matches()) {
            chain.doFilter(request, response);
            return;
        }

위 코드 부분은 doFilter에서 검증을 하지 않고 넘어가기 위해 등록을 합니다.

로그인과 회원가입의 경우 필터를 통과하지 않고 그냥 지나간다고 명시해 주는 과정입니다.

만약 하지 않는다면 로그인과 회원가입을 하기 위해 JWT토큰이 필요하다는 에러가 나타나게 됩니다.

JwtUtil.java

@Slf4j(topic = "JwtUtil")
@Component
public class JwtUtil {

    private static final String BEARER_PREFIX = "Bearer ";
    private static final long TOKEN_TIME = 60 * 60 * 1000L; // 60분

    @Value("${jwt.secret.key}")
    private String secretKey;

    private Key key;
    private final SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;

    @PostConstruct
    public void init() {
        byte[] bytes = Base64.getDecoder().decode(secretKey);
        key = Keys.hmacShaKeyFor(bytes);
    }

    public String createToken(Long userId, String username, String email, UserRole userRole) {
        Date date = new Date();

        return BEARER_PREFIX +
                Jwts.builder()
                        .setSubject(String.valueOf(userId))
                        .claim("username", username)
                        .claim("email", email)
                        .claim("userRole", userRole.name())
                        .setExpiration(new Date(date.getTime() + TOKEN_TIME))
                        .setIssuedAt(date) // 발급일
                        .signWith(key, signatureAlgorithm) // 암호화 알고리즘
                        .compact();
    }

    public String substringToken(String tokenValue) {
        if (StringUtils.hasText(tokenValue) && tokenValue.startsWith(BEARER_PREFIX)) {
            return tokenValue.substring(7);
        }
        log.error("Not Found Token");
        throw new NullPointerException("Not Found Token");
    }

    public Claims extractClaims(String token) {
        return Jwts.parserBuilder()
                .setSigningKey(key)
                .build()
                .parseClaimsJws(token)
                .getBody();
    }
}

위 코드에서는 JWT 토큰을 생성해서 발급해주는 코드입니다.

"${jwt.secret.key}"는 application.yaml이나 application.properties에서 설정해주시면 됩니다.

3개의 파일을 모두 작성하였다면 기본적으로 JWT를 사용할 준비가 끝났습니다.

하지만 저희는 로그인에서 사용할 예정임으로 몇가지 더 코드를 추가하겠습니다.

이번 로그인에서는 @Auth 어노테이션 방식으로 사용할 예정입니다.

추가적인 코드

비밀번호 암호화

@Component
public class PasswordEncoder {

    /**
     * 원문 비밀번호를 BCrypt 알고리즘을 사용하여 암호화합니다.
     * @param rawPassword 원문 비밀번호
     * @return 암호화된 비밀번호 문자열
     */
    public String encode(String rawPassword) {
        // BCrypt의 기본 설정을 사용하여 비밀번호를 해시화
        return BCrypt.withDefaults().hashToString(BCrypt.MIN_COST, rawPassword.toCharArray());
    }

    /**
     * 원문 비밀번호와 암호화된 비밀번호를 비교하여 일치 여부를 확인합니다.
     * @param rawPassword 원문 비밀번호
     * @param encodedPassword 암호화된 비밀번호
     * @return 비밀번호 일치 여부 (true: 일치, false: 불일치)
     */
    public boolean matches(String rawPassword, String encodedPassword) {
        // BCrypt를 사용하여 원문 비밀번호와 암호화된 비밀번호를 비교
        BCrypt.Result result = BCrypt.verifyer().verify(rawPassword.toCharArray(), encodedPassword);
        return result.verified; // 비교 결과 반환
    }
}

회원가입 할때 비밀번호를 바로 DB에 저장하면 보안성에 취약해지기 때문에 원문 비밀번호를 암호화 해야합니다.

Auth.java

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Auth {
}

로그인 과정에서 사용할 어노테이션을 생성해줍니다. 이 어노테이션의 경우 커스텀 어노테이션이기 때문에 원하는 이름으로 설정할 수 있습니다.

AuthUserArgumentResolver.java

public class AuthUserArgumentResolver implements HandlerMethodArgumentResolver {

    // @Auth 어노테이션이 있는지 확인
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterAnnotation(Auth.class) != null;
    }

    // AuthUser 객체를 생성하여 반환
    @Override
    public Object resolveArgument(
            @Nullable MethodParameter parameter,
            @Nullable ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            @Nullable WebDataBinderFactory binderFactory
    ) {
        HttpServletRequest request = (HttpServletRequest) webRequest.getNativeRequest();

        // JwtFilter 에서 set 한 userId, email 값을 가져옴
        Long userId = (Long) request.getAttribute("userId");
        String email = (String) request.getAttribute("email");

        return new AuthUser(userId, email); // userid 와 email를 담기 위한 객체를 생성함
    }
}

ArgumentResolver를 생성해줍니다. ArgumentResolver를 통해 유저의 정보를 가져올 수 있습니다. 즉, 로그인 할때 유저의 정보를 가져오기 위해 필요합니다.

WebConfig.java

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {

    // ArgumentResolver 등록
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new AuthUserArgumentResolver());
    }
}

마지막으로 ArgumentResolver를 사용하기 위해 WebConfig에 등록을 해줍니다.

이제 로그인 기능을 위한 준비는 모두 끝났습니다.

로그인, 회원가입 구현하기

AuthController.java

@RestController
@RequiredArgsConstructor
@RequestMapping("/v1/auth")
public class AuthController {

    private final AuthService authService;

    @PostMapping("/signup")
    public ResponseEntity<SiginupResponseDto> signup(@RequestBody SiginupRequestDto siginupRequestDto) {
        return ResponseEntity.ok(authService.signup(siginupRequestDto));
    }

    @PostMapping("/signin")
    public ResponseEntity<SigininResponseDto> siginin(@RequestBody SigininRequestDto sigininRequestDto) {
        String token = authService.signin(sigininRequestDto).getBearerToken();
        return ResponseEntity.ok().header("Authorization",token).body(authService.signin(sigininRequestDto));
    }
}

AuthService.java

@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class AuthService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    private final JwtUtil jwtUtil;

    @Transactional
    public SiginupResponseDto signup(SiginupRequestDto siginupRequestDto) {

        if(userRepository.existsByEmail(siginupRequestDto.getEmail())) {
            throw new IllegalArgumentException("이미 존재하는 이메일 입니다.");
        }

        String encodedPassword = passwordEncoder.encode(siginupRequestDto.getPassword());

        User newUser = new User(siginupRequestDto.getName(), siginupRequestDto.getEmail(), encodedPassword);

        User savedUser = userRepository.save(newUser);

        String bearerToken = jwtUtil.createToken(
                savedUser.getId(),
                savedUser.getName(),
                savedUser.getEmail(),
                savedUser.getRole()
        );

        return new SiginupResponseDto(bearerToken);
    }

    public SigininResponseDto signin(SigininRequestDto sigininRequestDto) {
        User user = userRepository.findByEmail(sigininRequestDto.getEmail()).orElseThrow(
                () -> new IllegalArgumentException("이메일을 찾을 수 없습니다.")
        );

        if (!passwordEncoder.matches(sigininRequestDto.getPassword(), user.getPassword())) {
            throw new IllegalArgumentException("잘못된 비밀번호 입니다.");
        }

        String bearerToken = jwtUtil.createToken(
                user.getId(),
                user.getName(),
                user.getEmail(),
                user.getRole()
        );

        return new SigininResponseDto(bearerToken);
    }
}

AuthController와 AuthService에서 로그인과 회원가입을 구현하였습니다.

Controller에서 RequestMapping을 보면 "/v1/auth"로 시작하는 것을 알 수 있습니다. 따라서 Filter를 넘어가기 때문에 JWT토큰이 없이 바로 로그인이나 회원가입을 할 수 있습니다.

로그인을 하게 되면 JWT토큰을 반환합니다. 현재 방법은 body와 header 모두에서 반환을 하는데 만약 header에서만 반환을 하고 싶다면 body부분을 지우고 사용할 수 있습니다.

AuthService에서는 우선 회원가입 할 때 Id중복을 확인하고 비밀번호를 인코딩 한 다음 저장합니다.

로그인을 할 때는 회원이 가입되어 있는지 확인을 하고, 비밀번호를 확인한 뒤에 토큰을 생성해서 발급해줍니다.

@Auth 사용하기

MemoController.java

@RestController
@RequiredArgsConstructor
@RequestMapping("/memos")
public class MemoController {

    private final MemoService memoService;

    @PostMapping
    public ResponseEntity<MemoResponseDto> createMemo(@Auth AuthUser authUser, @RequestBody MemoRequsetDto memoRequsetDto) {
        MemoResponseDto memoResponseDto = memoService.createMemo(authUser, memoRequsetDto);
        return ResponseEntity.status(HttpStatus.OK).body(memoResponseDto);
    }

    @GetMapping
    public ResponseEntity<List<MemoResponseDto>> getMemo() {
        List<MemoResponseDto> memoResponseDtoList = memoService.getMemo();
        return ResponseEntity.status(HttpStatus.OK).body(memoResponseDtoList);
    }

    @PatchMapping("/{memoId}")
    public ResponseEntity<MemoResponseDto> patchMemo(@PathVariable("memoId") Long memoId, @RequestBody MemoRequsetDto memoRequsetDto) {
        MemoResponseDto memoResponseDto = memoService.patchMemo(memoId, memoRequsetDto);
        return ResponseEntity.status(HttpStatus.OK).body(memoResponseDto);
    }

    @DeleteMapping("/{memoId}")
    public void deleteMemo(@PathVariable("memoId") Long memoId) {
        memoService.deleteMemo(memoId);
    }

}

MemoService.java

@Service
@RequiredArgsConstructor
public class MemoService {

    private final MemoRepository memoRepository;
    private final UserRepository userRepository;

    public MemoResponseDto createMemo(AuthUser authUser, MemoRequsetDto memoRequsetDto) {
        User findUser = userRepository.findById(authUser.getId()).orElseThrow(
                ()-> new IllegalArgumentException("유저를 찾을 수 없습니다."));

        Memo memo = new Memo(findUser.getName(), memoRequsetDto);
        return new MemoResponseDto(memoRepository.save(memo));
    }

    public List<MemoResponseDto> getMemo() {
        return memoRepository.findAll().stream().map(MemoResponseDto::new).toList();
    }

    @Transactional
    public MemoResponseDto patchMemo(Long memoId, MemoRequsetDto memoRequsetDto) {
        Memo findMemo = memoRepository.findById(memoId).orElseThrow();
        return new MemoResponseDto(findMemo.patchMemo(memoRequsetDto));
    }

    public void deleteMemo(Long memoId) {
        memoRepository.delete(memoRepository.findById(memoId).orElseThrow());
    }
}

메모 CRUD를 간단하게 만들었습니다.

@Auth 어노테이션은 위와 같이 유저의 정보를 가져올 수 있습니다.

메모를 생성할 때 누가 작성하였는지 저장을 하고, 조회나 수정은 누구나 할 수 있지만 삭제의 경우 글을 작성한 사람이 맞는지 확인을 하고 삭제할 수 있도록 구현이 되어있습니다.

JWT를 이용한 로그인 구현, 메모 구현에 관한 코드입니다.

https://github.com/SuHyun-git/spring-basecode/tree/study/jwt

GitHub - SuHyun-git/spring-basecode

Contribute to SuHyun-git/spring-basecode development by creating an account on GitHub.

github.com

[Spring Boot] 스레드(Thread)

Coding-Su — Fri, 15 Nov 2024 17:24:34 +0900

스레드란?

스레드란 프로그램에서 실행되는 작업의 최소 단위입니다.

예를 들어 API를 호출하면 Spring에서 스레드가 요청을 처리합니다.

여기 한 식당이 있습니다. 그 식당에는 종업원(Thread) 이 있습니다. 각각의 종업원은 손님(Client)
들에게 주문(request)을 받고 주방(Spring MVC) 에서 음식(response) 이 완성이되면 음식을 손님에게
음식을 전달해 줍니다.

성능이 좋은 서버란?

1. 하나의 스레드를 극한의 효율로 사용하기(싱글 스레드), 비동기 방식과 non-blocking방식을 사용 -> Node.js

2. 스레드를 여러개 사용하기(멀티 스레드), 비공기 방식과 non-blocking 방식을 사용 -> Spring

동기와 비동기

동기: 동기 방식에서는 작업이 순차적으로 진행됩니다. 즉, 하나의 작업이 끝나야 다음 작업이 실행됩니다.

예시: 함수 A가 함수B를 호출하고, 함수 B의 실행이 완료될 때까지 함수 A가 기다리는 경우, 이는 동기 호출입니다.

비동기: 비동기 방식에서는 작업이 시작된 후, 해당 작업의 완료를 기다리지 않고 다음 작업을 즉시 수행합니다.

예시: 파일을 읽는 비동기 작업을 시작한 후, 파일 읽기가 완료되기를 기다리지 않고 다음 작업을 계속 수행합니다. 파일 읽기가 완료되면, 설정된 콜백 함수가 실행되어 결과를 처리합니다.

Blocking과 Non-Blocking

Blocking: 블로킹은 특정 작업이 완료될 때까지 현재 스레드의 실행을 멈추는 것을 의미합니다. 블로킹 호출에서는 현재 작업이 완료될 때까지 프로그램의 다른 작업이나 이벤트가 실행되지 않습니다.

Non-Blocking: 논블로킹 방식에서는 작업을 수행하는 동안 해당 작업이 완료될 때까지 기다리지 않고, 즉시 제어권을 반환합니다. 논블로킹 호출은 결과가 즉시 반환하거나 작업이 아직 완료되지 않았음을 의미합니다.

스레드 풀이란?

Spring에서 미리 사용할 스레드를 여러 개 생성해서 저장해두는 개념입니다.

스레드를 미리 생성하는 이유는 스레드를 생성하고 제거하는 작업에는 비용이 많이 소요됩니다.

스레드를 생성할 때 시스템 자원을 할당하고 제거할 때는 자원을 해제해야 하는데 많은 스레드를 생성하고 제거하는 경우에는 성능 저하가 발생할 수 있기 때문에 스레드 풀에 스레드를 미리 생성하고 재사용합니다.

내용 정리

API요청이 들어오면

1. 가장 머너저 서블릿 컨테이너에 들어옵니다.

2. 스레드 풀에서 스레드가 할당됩니다.

3. 할당된 스레드는 필터 페인에 등록된 필터를 순서대로 통과합니다.

4. 필터를 통화한 스레드는 DispatcherServlet을 호출하여 어떤 Servlet을 사용할 것인지 결정합니다.

5. Spring 3 Layer 계층을 통과합니다.

[Spring Boot] Spring Security를 이용하여 인증인가 구현하기

Coding-Su — Fri, 15 Nov 2024 17:01:25 +0900

Spring Security란?

Spring Security는 인증, 인가를 구현하는 데 도움을 주는 Spring의 프레임워크입니다.

Spring Security를 이용하면 전에 구현했던 어노테이션을 만드는 과정도 매우 쉽게 구현할 수 있습니다.

이전에 JWT를 이용한 인증인가

[Spring Boot] JWT를 이용한 인증/인가 구현하기(Spring Security X)

JWT를 사용하기 위한 파일FilterConfig.java@Configuration@RequiredArgsConstructorpublic class FilterConfig { private final JwtUtil jwtUtil; @Bean public FilterRegistrationBean jwtFilter() { FilterRegistrationBean registrationBean = new FilterRegistr

coding-su.tistory.com

Spring Security를 이용한 인증/인가 구현하기

위에 있는 전에 사용한 코드를 변경하여 구현하겠습니다.

JwtUtil.java

@Slf4j(topic = "JwtUtil")
@Component
public class JwtUtil {

    private static final String BEARER_PREFIX = "Bearer ";
    private static final long TOKEN_TIME = 60 * 60 * 1000L; // 60분

    @Value("${jwt.secret.key}")
    private String secretKey;
    private Key key;
    private final SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;

    @PostConstruct
    public void init() {
        byte[] bytes = Base64.getDecoder().decode(secretKey);
        key = Keys.hmacShaKeyFor(bytes);
    }

    public String createToken(Long userId, String email, UserRole userRole) {
        Date date = new Date();

        return BEARER_PREFIX +
                Jwts.builder()
                        .setSubject(String.valueOf(userId))
                        .claim("email", email)
                        .claim("userRole", userRole.getUserRole())
                        .setExpiration(new Date(date.getTime() + TOKEN_TIME))
                        .setIssuedAt(date) // 발급일
                        .signWith(key, signatureAlgorithm) // 암호화 알고리즘
                        .compact();
    }

    public String substringToken(String tokenValue) {
        if (StringUtils.hasText(tokenValue) && tokenValue.startsWith(BEARER_PREFIX)) {
            return tokenValue.substring(7);
        }
        log.error("Not Found Token");
        throw new NullPointerException("Not Found Token");
    }

    public Claims extractClaims(String token) {
        return Jwts.parserBuilder()
                .setSigningKey(key)
                .build()
                .parseClaimsJws(token)
                .getBody();
    }
}

SecurityConfig.java

@Configuration
@RequiredArgsConstructor
@EnableWebSecurity
@EnableMethodSecurity(securedEnabled = true)
public class SecurityConfig {

    private final JwtSecurityFilter jwtSecurityFilter;
    
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                .csrf(AbstractHttpConfigurer::disable)
                .sessionManagement(session -> session
                        .sessionCreationPolicy(SessionCreationPolicy.STATELESS) // SessionManagementFilter, SecurityContextPersistenceFilter
                )
                .addFilterBefore(jwtSecurityFilter, SecurityContextHolderAwareRequestFilter.class)
                .formLogin(AbstractHttpConfigurer::disable) // UsernamePasswordAuthenticationFilter, DefaultLoginPageGeneratingFilter 비활성화
                .anonymous(AbstractHttpConfigurer::disable) // AnonymousAuthenticationFilter 비활성화
                .httpBasic(AbstractHttpConfigurer::disable) // BasicAuthenticationFilter 비활성화
                .logout(AbstractHttpConfigurer::disable) // LogoutFilter 비활성화
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/auth/signin", "/auth/signup").permitAll()
                        .requestMatchers("/test").hasAuthority(UserRole.Authority.ADMIN)
                        .anyRequest().authenticated()
                )
                .build();
    }
}

Filter를 등록해줍니다. 여기서 여러가지 내용을 비활성화 하는 이유는 Spring Security는 JWT 토큰 방식보다는 세션 방식에 조금 더 치중되어 있어 세션기능에서 필요한 기능은 JWT 토큰 방식에서는 필요 없기 때문에 비활성화 하였습니다.

비활성화 하지 않아도 문제 없습니다.

permitAll은 전에 Spring Security 없이 구현했을 때와 마찬가지로 로그인과 회원가입은 Filter의 검증을 통과해야 하기 때문에 permitAll로 통과시켜주어야 합니다.

처음 Spring Security를 적용하시는 분들이 permitAll 설정을 하지 않아 로그인과 회원가입도 막히는 경우가 있기 때문에 꼭 설정을 해야합니다.

JwtSecurityFilter.java

@Slf4j
@Component
@RequiredArgsConstructor
public class JwtSecurityFilter extends OncePerRequestFilter {

    private final JwtUtil jwtUtil;

    @Override
    protected void doFilterInternal(
            HttpServletRequest httpRequest,
            @NonNull HttpServletResponse httpResponse,
            @NonNull FilterChain chain
    ) throws ServletException, IOException {
        String authorizationHeader = httpRequest.getHeader("Authorization");

        if (authorizationHeader != null && authorizationHeader.startsWith("Bearer ")) {
            String jwt = jwtUtil.substringToken(authorizationHeader);
            try {
                Claims claims = jwtUtil.extractClaims(jwt);
                Long userId = Long.valueOf(claims.getSubject());
                String email = claims.get("email", String.class);
                UserRole userRole = UserRole.of(claims.get("userRole", String.class));

                if (SecurityContextHolder.getContext().getAuthentication() == null) {
                    AuthUser authUser = new AuthUser(userId, email, userRole);

                    JwtAuthenticationToken authenticationToken = new JwtAuthenticationToken(authUser);
                    authenticationToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(httpRequest));
                    SecurityContextHolder.getContext().setAuthentication(authenticationToken);
                }
            } catch (SecurityException | MalformedJwtException e) {
                log.error("Invalid JWT signature, 유효하지 않는 JWT 서명 입니다.", e);
                httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "유효하지 않는 JWT 서명입니다.");
            } catch (ExpiredJwtException e) {
                log.error("Expired JWT token, 만료된 JWT token 입니다.", e);
                httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "만료된 JWT 토큰입니다.");
            } catch (UnsupportedJwtException e) {
                log.error("Unsupported JWT token, 지원되지 않는 JWT 토큰 입니다.", e);
                httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "지원되지 않는 JWT 토큰입니다.");
            } catch (Exception e) {
                log.error("Internal server error", e);
                httpResponse.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
            }
        }
        chain.doFilter(httpRequest, httpResponse);
    }
}

Filter를 만들어 줍니다.

JwtAuthenticationToken.java

public class JwtAuthenticationToken extends AbstractAuthenticationToken {

    private final AuthUser authUser;

    public JwtAuthenticationToken(AuthUser authUser) {
        super(authUser.getAuthorities());
        this.authUser = authUser;
        setAuthenticated(true);
    }

    @Override
    public Object getCredentials() {
        return null;
    }

    @Override
    public Object getPrincipal() {
        return authUser;
    }
}

Argument Resolver입니다. Spring Security를 사용하지 않을 때는 많은 설정이 필요했지만 Spring Security를 사용하면 위 파일 하나로 해결할 수 있습니다.

또한 Spring Security를 사용하지 않았을 때는 PasswordEncoder를 사용했지만 Spring Security에서는 기본적으로 제공하기 때문에 구현할 필요가 없습니다.

Spring Security를 사용하여 인증/인가, 메모를 구현한 코드

https://github.com/SuHyun-git/spring-basecode/tree/study/springsecurity

GitHub - SuHyun-git/spring-basecode

Contribute to SuHyun-git/spring-basecode development by creating an account on GitHub.

github.com

Coding-Su

[Design Doc] Transactional Outbox Pattern — Kafka 직접 발행의 한계와 설계 (7주차 · 6팀 · 조수현)

TL;DR

Introduction & Goals

Context / Background

Goals

Detailed Design

System Architecture

Data Models

Alternatives Considered

멱등성 키 전략

Cross-cutting Concerns

Observability

Known Limitations

[Design Doc] PG 외부 연동 장애 대응 설계 (6주차 · 6팀 · 조수현)

TL;DR

Introduction & Goals

Detailed Design

System Architecture

장애 유형별 처리 흐름

Resilience4j 설정

PENDING 복구 배치

트레이드오프: split-commit

Alternatives Considered

Cross-cutting Concerns

[Benchmark] MySQL 인덱스 전략 비교 — 좋아요 순 상품 목록 최적화 (5주차 · 6팀 · 조수현)

TL;DR

Question — 무엇을 비교했는가

결정해야 했던 것

비교 대상

Setup — 측정 환경

Results — 측정 결과

Round 1~4: 브랜드별 좋아요 순 (핵심 시나리오)

Round 5: 분리 테이블 product_like_view JOIN

Round 6: 정렬 조건별 비교

Round 9: 전체 좋아요 순 — OFFSET의 함정

Round 10: 복합 필터 (브랜드 + 가격 범위 + 좋아요 순)

Round 11: stocks JOIN — hash join의 함정

반정규화 vs 분리 테이블 — 읽기/쓰기 종합

Decision

선택

선택 이유

포기한 것

최종 인덱스 목록

Future Work

[Design Doc] 쿠폰 테이블 설계 (6팀, 4주차, 조수현)

TL;DR

Introduction & Goals

Detailed Design

Data Models

CouponStatus 동적 계산

중복 발급 방지

Alternatives Considered

Cross-cutting Concerns

[Design Doc] 레이어드 아키텍처 설계 — 4개 레이어, 컴포넌트, 실제 구현 (3주차 · 6팀 · 조수현)

TL;DR

Introduction & Goals

System Architecture

패키지 구조

Layer 1. interfaces / api

Layer 2. application

Layer 3. domain

Layer 4. infrastructure

Cross-cutting Concerns

Soft Delete

Soft Delete + Unique 제약 (MySQL)

애그리거트 경계

Alternatives Considered

Lessons Learned

[Challenge Story] 주문·결제 동시성 제어 — 6개 문제를 연쇄 발견한 설계 여정 (2주차 · 6팀 · 조수현)

TL;DR

Context (배경 및 목표)

Design & Implementation (설계 및 구현)

핵심 기술 선택: 비관적 락 (SELECT FOR UPDATE)

Logic Flow

Engineering Challenges (트러블슈팅 및 최적화)

문제 1. 보상 트랜잭션이 다른 주문의 차감량을 덮어쓴다

문제 2. 재고 락 밖에서 생긴 두 가지 문제

문제 3. PENDING 방치 (클라이언트 미응답)

문제 4. 결제 확정 주체 선택

Round 5: 분리 테이블 `product_like_view` JOIN

핵심 기술 선택: 비관적 락 (`SELECT FOR UPDATE`)