Payment Platform Project

15 posts with the tag “Payment Platform Project”

서로 다른 주문의 UPDATE가 충돌한 이유 — MySQL Index Merge 데드락

2026. 10. 5.

hyoguoo

Backend Engineer

결제 도메인 학습 프로젝트인 Payment Platform은 요청을 접수한 뒤 승인 처리를 비동기로 진행하고, 브라우저에서 최종 상태를 조회해 완료를 확인하는 구조다.

결제 요청부터 완료 확인까지

1. 1
   결제 서비스 요청 접수 브라우저에 접수 응답
2. 2
   PG 서비스 승인 처리 외부 결제 업체 호출·결과 저장
3. 3
   결제 서비스 완료 반영 결과 메시지를 받아 상태 변경
4. 4
   브라우저 완료 확인 조회한 최종 상태를 화면에 표시

이 구조의 처리량을 측정하던 중 일부 결제가 완료되기까지 1분 넘게 걸렸다. 요청이 밀려 생기는 대기 시간을 줄이려고 부하를 낮췄지만, 완료 시간은 여전히 큰 차이를 보였다.

구분	표본 요청의 완료 시간
중앙값(p50)	약 0.5초
지연된 일부 요청	62~77초

테스트 종료 후 최종 결제 상태 검사는 통과했다. 하지만 최종 상태만으로는 일부 요청이 겪은 긴 대기를 알 수 없었다. 지연된 요청을 추적하며 다음 사실을 확인했다.

1. 승인 결과 저장 실패: 승인 결과를 저장하는 UPDATE에서 데드락이 발생했다. 해당 결제는 결과를 다시 반영할 때까지 대기하고 있었다.
2. 두 인덱스를 읽는 실행 계획: 이 UPDATE는 UNIQUE 주문 번호로 한 행을 지정했지만, 실행 계획에는 주문 번호 인덱스와 상태 인덱스를 함께 읽는 Index Merge가 선택돼 있었다.
3. 서로 다른 주문 간 잠금 충돌: 재현 실험에서도 서로 다른 주문을 수정하는 두 트랜잭션이 같은 주문의 레코드에서 충돌했다.

저장 실패가 1분의 지연으로 이어진 과정

이 프로젝트에서 결제에 관여하는 두 서비스의 역할은 다음과 같다.

• 결제 서비스: 사용자 요청을 접수하고 최종 결제 상태를 관리한다.
• PG 서비스: 외부 결제 업체인 PG(Payment Gateway)에 승인을 요청한다.

두 서비스는 메시지로 명령과 결과를 주고받는다. 따라서 브라우저가 받는 접수 응답과 실제 결제 완료 사이에는 시간 차이가 있다.

PG 서비스는 받은 승인 요청을 수신함 테이블인 pg_inbox에 저장하고, 백그라운드 워커가 한 건씩 맡아 처리한다. 요청의 상태는 처리 대기인 PENDING에서 처리 중인 IN_PROGRESS를 거쳐, 승인 결과가 저장되면 APPROVED로 바뀐다.

처리가 중단된 요청을 다시 실행하기 위해, PG 서비스에는 pg_inbox를 주기적으로 조회하는 복구 워커도 있다. 오래도록 처리가 끝나지 않은 요청을 찾아 같은 요청의 처리 로직을 다시 호출하는 백그라운드 작업이다.

승인 처리와 저장 실패 후의 복구 경로

승인 요청을 pg_inbox에 저장 · PENDING (대기)

1. 워커 선점 선점 트랜잭션

   PENDING → IN_PROGRESS

   처리할 요청을 맡고 커밋

   COMMIT · 잠금 해제
2. 외부 PG 호출 DB 트랜잭션 없음

   외부 결제 업체에 승인 요청

   응답을 기다리는 동안 처리 중 상태 유지

3. 승인 결과 저장 결과 트랜잭션

   IN_PROGRESS → APPROVED

   승인 결과와 변경 시각 저장

   COMMIT

결과 저장 성공

결과 회신 → 결제 서비스가 최종 상태 반영 → 브라우저에서 완료 확인

결과 저장 실패

1. 처리 중 상태로 남음IN_PROGRESS 유지
2. 복구 워커가 주기 조회마지막 변경 후 60초가 지난 요청 회수
3. 같은 요청 재처리결과 저장·회신이 완료되면 결제에도 반영

외부 승인이 성공해도 별도 트랜잭션인 결과 저장은 실패할 수 있다. 복구 워커는 오래 남은 요청을 찾아 재처리를 맡기며, 60초는 조회 주기가 아닌 복구 대상 판정 기준이다. 이 그림은 결과 저장 실패로 IN_PROGRESS가 남은 경우를 표시한다.

외부 응답을 기다리는 동안 DB 잠금을 유지하지 않도록, 워커는 다음 순서로 트랜잭션을 분리해 처리한다.

1. 요청 선점: 요청을 맡고 IN_PROGRESS를 커밋한다.
2. 외부 PG 호출: 선점 트랜잭션이 끝난 뒤 승인을 요청한다.
3. 승인 결과 저장: 외부 호출이 끝나면 새 트랜잭션에서 결과를 저장한다.

마지막 결과 저장이 데드락으로 롤백되면, 앞서 커밋한 IN_PROGRESS와 외부의 승인 결과는 남아 있다. 이때 결제가 완료되기까지의 흐름은 다음과 같다.

1. 복구 대상 조회: 복구 워커가 마지막 변경 시각에서 60초가 지난 IN_PROGRESS를 찾는다.
2. 재처리: 해당 요청의 처리 로직을 다시 실행해 PG 서비스가 승인 결과를 저장하고 회신한다.
3. 결제 완료 반영: 결제 서비스가 회신을 받아 최종 상태를 갱신한다.

지연된 요청 하나의 로그를 확인하니, 결과 저장에 실패한 뒤 약 63.7초가 지나서야 복구 워커에 의해 다시 실행됐다.

같은 요청의 결과 저장 실패와 복구

1. 결과 저장 실패 23:11:23.293

   워커 시작

   23:11:23.601

   데드락으로 UPDATE 롤백

2. 복구 기준을 넘길 때까지 대기 약 63.7초

   먼저 커밋한 IN_PROGRESS 유지

   복구 조회 기준: 마지막 변경 후 60초

3. 같은 요청 재처리 23:12:27.314

   복구 워커 시작

   23:12:27.318

   복구 확인 로그

한 행을 찾는 데 두 인덱스를 사용한 UPDATE

데드락이 발생한 쿼리는 다음과 같다.

UPDATE pg_inbox
SET status = 'APPROVED',
    stored_status_result = :result,
    updated_at = :now
WHERE order_id = :order_id
  AND status = 'IN_PROGRESS';

두 WHERE 조건의 역할은 다음과 같다.

• order_id = :order_id: 결과를 저장할 주문을 지정한다.
• status = 'IN_PROGRESS': 아직 처리 중인 요청만 수정한다. 이미 다른 상태로 끝난 요청을 뒤늦게 도착한 승인 결과로 덮어쓰지 않기 위한 조건이다.

두 조건을 만족하는 행에 승인 결과와 변경 시각을 저장한다.

테이블에는 기본 키(Primary Key, PK)인 id, 주문 번호의 UNIQUE 인덱스, 상태 단일 인덱스가 있었다.

PRIMARY KEY (id)
UNIQUE KEY ux_pg_inbox_order_id (order_id)
KEY idx_pg_inbox_status (status)

주문 번호가 UNIQUE이므로 그 인덱스로 최대 한 행을 찾은 뒤 상태를 확인하면 되지만, MySQL이 실제로 선택한 접근 방식을 보여주는 EXPLAIN에는 주문 번호와 상태 인덱스를 모두 사용하는 계획이 나왔다.

type:  index_merge
key:   ux_pg_inbox_order_id, idx_pg_inbox_status
Extra: Using intersect(...); Using where

Index Merge는 여러 인덱스의 검색 결과를 합쳐 대상을 찾는 방식이며, 여기서 선택된 intersection은 각 검색에 공통으로 포함된 행을 찾는다. 이 UPDATE에서는 주문 번호로 찾은 행과 IN_PROGRESS 상태로 찾은 행들의 교집합이 최종 수정 대상이다.

주문 A를 수정할 때의 검색 범위

두 인덱스 병합

주문 번호 인덱스 · UNIQUE

A

∩ 공통 PK 찾기

상태 인덱스 · IN_PROGRESS

AB다른 주문…

↓최종 대상 A

상태 검색 범위에는 다른 주문도 포함

주문 번호 단독 검색

주문 번호 인덱스 · UNIQUE

A

↓A의 상태 확인

status = IN_PROGRESS

↓최종 대상 A

별도의 상태 인덱스 범위 검색 없음

검색 범위를 설명하기 위한 예시다. 실제 읽은 행의 수·순서나 모든 잠금을 표시한 그림은 아니며, 단독 검색도 결과 갱신에 필요한 잠금과 보조 인덱스 수정을 수행한다.

두 방식 모두 최종 대상은 한 행이지만, 병합 계획의 상태 검색 범위에는 다른 주문도 포함된다. 이 차이가 실제 잠금 충돌로 이어지는지 확인하려면 실행 계획에 더해, 데드락이 발생한 순간의 잠금 기록이 필요했다.

주문 B를 수정하면서 주문 A의 잠금을 기다린 이유

잠금 기록을 확보하려고 별도 DB에서 재현을 시도했지만, 초기 테스트에서는 문제의 Index Merge부터 나오지 않았다. 이때는 IN_PROGRESS 비율을 10%로 두는 등 상태 분포와 컬럼 정의를 단순화했고, 정적인 10만·80만 행 실험에서는 주문 번호 단독 검색만 선택됐다.

프로젝트에서는 승인이 끝난 APPROVED 이력이 쌓이고, 외부 응답을 기다리거나 결과를 저장하는 일부 요청만 IN_PROGRESS로 남는다. 이 분포와 원래 스키마를 반영해 재현 조건을 구성했다.

• DB 버전: MySQL 8.0.46의 별도 DB
• 스키마: 프로젝트의 원래 마이그레이션 V1~V7 적용
• 초기 데이터: APPROVED 이력 50만 건 적재
• 동시 처리: 10개 연결이 서로 다른 주문을 500건씩 처리

각 주문은 실제 흐름처럼 선점과 결과 저장의 트랜잭션을 분리했다.

1. 선점 트랜잭션: PENDING → IN_PROGRESS로 변경하고 커밋해 잠금을 해제한다.
2. 외부 호출 모사: 트랜잭션 밖에서 100~300ms 기다린다.
3. 결과 저장 트랜잭션: 승인 결과를 UPDATE하고 커밋한다.

워커가 맡은 주문은 중복되지 않았고, 인덱스 힌트나 별도로 유지한 PK 잠금 없이도 결과 저장 중 데드락이 발생했다.

인덱스별 레코드와 잠금

상태 인덱스에는 실제 행을 찾아갈 PK가 들어 있다. 주문 A(PK 502596)의 상태 항목과 실제 행은 다음처럼 연결된다.

같은 주문 A, 서로 다른 잠금 대상

상태 인덱스

주문 A의 상태 항목

상태IN_PROGRESS

PK502596

상태 인덱스 잠금

PK로 실제 행 찾기 →

PRIMARY

주문 A의 실제 행

PK502596

실제 행 데이터

PRIMARY 잠금

B의 UPDATE가 상태 인덱스에서 A의 항목을 잠그면, A의 실제 행(PRIMARY)에도 배타 잠금을 요청한다. A의 실제 행을 다른 트랜잭션이 이미 잠그고 있다면, B의 UPDATE는 A의 상태 항목을 잠근 채 실제 행의 잠금이 풀리기를 기다린다. UPDATE의 잠금 규칙

검색부터 대기까지의 과정은 다음과 같다.

1. 검색 중 A를 만난다. Index Merge가 IN_PROGRESS 범위를 읽는 동안, B와 같은 상태인 A의 레코드도 읽는다.
2. A의 두 잠금을 요청한다. A의 상태 인덱스 레코드에 배타 잠금을 얻고, 해당 PK로 A의 PRIMARY 레코드에도 잠금을 요청한다.
3. A의 PRIMARY에서 기다린다. 다른 트랜잭션이 이 잠금을 가지고 있으면, B의 UPDATE는 그 잠금이 풀릴 때까지 멈춘다.

이때 B의 UPDATE는 A의 상태 인덱스 잠금은 보유하고, A의 PRIMARY 잠금은 기다리는 상태다.

덤프에 남은 순환 대기

재현 덤프의 T1은 주문 A(PK 502596)를, T2는 다른 주문 B(PK 502601)를 수정하고 있었다. 그런데 T2가 기다리는 PRIMARY 레코드의 주문 번호를 확인하니 B가 아닌 A였다. 충돌에 관여한 잠금의 보유·대기 관계는 다음과 같았다. 데드락 덤프

수정 대상은 A·B, 충돌 지점은 A

실선: 잠금 보유점선: 잠금 대기

T1 → T2 → T1 순환 대기 · InnoDB가 T1 롤백

수정 대상	보유한 잠금	기다리는 잠금
T1 · 주문 A	A의 PRIMARY	A의 상태 인덱스 항목
T2 · 주문 B	A의 상태 인덱스 항목	A의 PRIMARY

T1은 A의 PRIMARY 잠금을, T2는 A의 상태 인덱스 잠금을 보유한 채 상대의 잠금을 기다렸다. InnoDB는 이 순환 대기를 감지해 T1을 롤백했다.

서로 다른 주문의 UPDATE가 검색 도중 A의 레코드에서 충돌한 것이다. 두 UPDATE는 모두 결과 저장 트랜잭션에서 행을 검색 중이었다(Searching rows for update).

UNIQUE 검색보다 Index Merge가 저렴하다고 판단한 이유

잠금 기록은 서로 다른 주문이 충돌한 지점을 보여줬다. UNIQUE 인덱스만으로 한 행을 찾을 수 있는데도 상태 인덱스까지 읽은 이유를 확인하기 위해, 데이터 분포에 따른 실행 계획과 후보별 예상 비용이 남는 optimizer trace를 살펴봤다.

상태 분포에 따른 실행 계획

같은 승인 UPDATE라도 IN_PROGRESS 건수에 따라 실행 계획이 달라지는지 확인했다. 프로젝트 스키마와 전체 50만 행을 유지하고, APPROVED 상태의 행 일부를 IN_PROGRESS로 바꿨다. 각 상태 변경을 마친 뒤, 동시 승인 UPDATE를 실행하지 않는 상태에서 EXPLAIN으로 계획을 확인했다.

IN_PROGRESS 건수	승인 UPDATE의 검색 방식
1 · 2 · 10 · 100	주문 번호·상태 인덱스 병합 (index_merge)
1,000 · 10,000 · 100,000 · 500,000	주문 번호 인덱스 단독 검색 (range)

여기서 EXPLAIN에 range로 표시된 계획은 UNIQUE 주문 번호로 최대 한 행을 찾는다. 처리 중인 행이 소수인 조건에서는, 동시 승인 UPDATE를 실행하기 전에도 Index Merge가 선택됐다. 분포별 EXPLAIN

다만 이 결과를 “100건까지는 병합, 1,000건부터는 단독 검색”이라는 일반적인 기준으로 사용할 수는 없다.

실제로 전체 50만 행을 IN_PROGRESS로 바꾼 뒤 다시 10건으로 줄였을 때는, 처음에 range가 나왔다가 이후 다시 index_merge가 관측됐다. 같은 상태별 건수에서도 계획이 달라질 수 있었다.

병합이 선택된 10건 조건의 optimizer trace에서, MySQL이 두 검색의 비용을 어떻게 비교했는지 확인했다.

옵티마이저의 예상 행 수 계산

MySQL 옵티마이저는 쿼리를 실행하기 전에 검색 방법별 비용을 비교한다. 이때 주문 번호와 상태 조건을 모두 만족할 행이 얼마나 있을지 추정하고, 그 예상 행 수를 비용 계산에 사용한다. optimizer trace는 이 판단 과정을 기록한 것으로, 실제 UPDATE의 실행 시간을 측정한 결과가 아니다.

먼저 100행 중 1행이 IN_PROGRESS인 설명용 예시로 계산의 의미를 살펴보자. 전체의 1%가 이 상태이므로, 무작위로 고른 한 행이 같은 상태일 가능성도 1%다. 이 비율을 주문 번호의 예상 1행에 적용하면 0.01행이 된다.

한 행에 상태 비율을 적용하면 예상 행 수는 소수가 된다

개념 예시100행 중 처리 중인 행은 1행

IN_PROGRESS 1행 다른 상태 99행 한 칸 = 한 행

주문 번호 조건1행

×

상태 비율1%1 / 100

=

예상 행 수0.01행

전체의 1%가 처리 중이므로, 주문 번호로 찾을 한 행에도 그 비율을 적용해 추정한다.

실제 trace같은 계산에 실험의 추정값 적용

주문 번호 조건1행

×

상태 비율10469,899

≈

비용 계산의 중간 추정0.000021행

실제 수정 대상1행

해당 주문은 실제로 존재하고, 상태도 IN_PROGRESS다.

실제 실험에서는 전체 50만 행 중 IN_PROGRESS가 10건이었다. 계산에는 InnoDB 통계의 근사값인 469,899행과 상태 조건의 예상 10행이 사용됐다. 주문 번호 조건은 UNIQUE 인덱스로 최대 한 행을 찾으므로 1행으로 추정했다. 비용 trace 원본

이번 병합 후보의 계산에서는 주문 번호 조건과 상태 조건을 서로 독립적으로 취급한다. 특정 주문이 실제로 어떤 상태인지 확인하는 대신, 전체에서 IN_PROGRESS가 차지하는 비율을 주문 번호의 예상 1행에 적용한다. 교집합 행 수·비용 계산 구현

약 0.000021행은 비용 계산에 사용한 중간 추정치이며, 실제 수정 대상은 1행이다. 다음 비용 계산에서는 이 작은 추정값이 병합 검색을 저렴하게 평가하는 데 영향을 준다.

검색 비용의 합산과 병합 계획 선택

옵티마이저는 예상 행 수를 바탕으로 읽을 양을 계산하고, 여기에 스토리지 엔진의 비용 상수 등을 적용해 후보를 비교한다. 비용은 밀리초 단위의 실행 시간이 아닌 내부 비교 단위다.

예를 들어 인덱스 읽기 비용은 읽어야 할 페이지 수를 추정하고, 여기에 페이지당 읽기 비용을 적용해 구한다. 페이지는 DB가 데이터를 읽는 단위이며, 메모리에 있는 부분과 디스크에서 읽어야 할 부분의 비용도 구분한다.

이번 trace의 후보별 비용과 병합 계획의 계산은 다음과 같다.

MySQL 옵티마이저가 계산한 후보별 예상 비용

주문 번호 단독 검색

UNIQUE 동등 조건의 예상 행 수 1행

주문 번호로 찾은 행에서 상태 확인

단독 검색의 총비용 1.64349

주문 번호 + 상태 병합

두 인덱스를 읽는 비용

주문 번호 인덱스0.980542

상태 인덱스+ 0.252470

합계약 1.23301

옵티마이저가 추정한 공통 행 수 약 0.000021행

↓ 소수점 이하를 버려 0행으로 비용 계산

행 데이터 읽기 비용: 0

병합 검색의 총비용

인덱스 읽기 1.23301 + 행 데이터 읽기 0

1.23301

1.23301 < 1.64349 → 병합 계획 선택 index_roworder_intersect

전체 50만 행 중 IN_PROGRESS가 10건일 때의 trace. 행 수와 비용은 옵티마이저의 예상값이며, 비용은 실행 시간이 아닌 내부 비교 단위다.

trace 필드와 세부 계산은 본문 뒤의 상세 기록에 정리했다.

선택된 병합 계획에서는 B를 찾다가 같은 IN_PROGRESS 상태인 A도 읽을 수 있다. UPDATE는 검색 중에도 잠금을 요청하므로, B만 수정하는 쿼리가 A의 잠금을 기다릴 수 있다. 실제 덤프에서도 이 대기가 확인됐다.

복구 조회를 고려한 상태 인덱스 교체

이미 끝난 요청을 다시 수정하지 않도록 승인 UPDATE의 status = 'IN_PROGRESS' 조건은 유지해야 했다. 상태 인덱스도 아래 복구 조회를 지원하므로, 삭제하는 대신 교체하기로 했다. 복구 조회를 SQL로 나타내면 다음과 같다.

SELECT id
FROM pg_inbox
WHERE status = 'IN_PROGRESS'
  AND updated_at < :before
ORDER BY updated_at ASC
LIMIT :batch_size;

복구 조회는 상태가 같은 요청 중 변경 시각이 오래된 순서로 읽기 때문에, 이 조건에 맞춰 V8 마이그레이션에서는 기존 (status) 인덱스를 (status, updated_at)으로 교체했다.

ALTER TABLE pg_inbox DROP INDEX idx_pg_inbox_status;

ALTER TABLE pg_inbox
ADD INDEX idx_pg_inbox_status_updated_at (status, updated_at);

교체 후 승인 UPDATE는 주문 번호 인덱스만 사용했다. 기존 병합 계획이 제외된 이유는 상태 인덱스의 정렬 순서가 달라졌기 때문이다.

인덱스 정렬 순서와 교집합 병합의 조건

index_roworder_intersect는 두 검색의 PK를 대조해 공통 행을 찾는다. PK가 같으면 공통 행이고, 다르면 작은 쪽에서 다음 PK를 읽는다. 뒤에서 더 작은 PK가 나오면 공통 행을 놓칠 수 있으므로, 각 검색 결과는 PK가 작은 순서로 나와야 한다. PK 순서 병합 구현

기존 (status) 인덱스는 같은 상태 안에서 PK 순서로 읽힌다. 새 (status, updated_at) 인덱스는 변경 시각이 먼저 정렬되므로, 같은 상태 안에서도 PK 순서가 보장되지 않는다.

정렬 예시 · IN_PROGRESS를 고정한 뒤의 순서

기존 (status)

상태 → PK

1. PK 201
2. PK 202
3. PK 203

PK 순서 유지
201 → 202 → 203

변경 (status, updated_at)

상태 → 변경 시각 → PK

1. 10:01PK 202
2. 10:02PK 203
3. 10:03PK 201

PK 순서 불일치
202 → 203 → 201

인덱스 교체가 실행 계획에 영향을 주는 과정은 다음과 같다.

1. 기존 인덱스의 PK 순서: (status)에서 IN_PROGRESS를 찾으면 PK가 201 → 202 → 203 순서로 나온다. 주문 번호로 찾은 PK가 202라면, 상태 검색에서 201을 지나 202와 일치하는 것을 확인할 수 있다.
2. 새 인덱스의 변경 시각 순서: (status, updated_at)에서는 변경 시각이 빠른 순서인 202 → 203 → 201로 나온다. 상태만 고정해서는 PK가 작은 순서로 나온다는 보장이 없다.
3. 병합 후보 제외: 옵티마이저는 새 인덱스의 상태 검색을 PK 순서 병합에 사용할 수 없다고 판단한다. 기존 intersection이 후보에서 빠지고, 이 UPDATE에는 주문 번호 단독 검색이 선택된다.

변경 후 trace에서도 상태·시간 인덱스의 rowid_ordered가 false로 바뀌었다. 이는 해당 검색에서 PK 순서가 보장되지 않는다는 옵티마이저의 판정이다. 변경 후 trace

{
  "index": "idx_pg_inbox_status_updated_at",
  "ranges": ["status = 'IN_PROGRESS'"],
  "rowid_ordered": false
}

두 쿼리에 미친 영향

인덱스 하나를 교체했지만 두 쿼리에서 얻은 효과는 달랐다. 복구 SELECT에는 상태와 시간 조건에 맞는 검색 경로를 제공했고, 승인 UPDATE에서는 충돌에 관여한 병합 경로가 제외됐다.

쿼리	유지한 조건	교체 후 검색 방식
승인 UPDATE	주문 번호 일치 · IN_PROGRESS	UNIQUE 주문 번호로 한 행을 찾은 뒤 상태 확인
복구 SELECT	IN_PROGRESS · 기준 시각 이전	상태를 고정한 뒤 변경 시각 범위 검색 지원

대안의 적용 범위

이 문제에는 특정 인덱스를 사용하도록 힌트를 주거나 intersection을 비활성화하는 방법도 고려할 수 있다. 이번에는 복구 조회에도 필요한 구성을 선택했다.

방법	적용할 때 고려할 점
상태·시간 인덱스로 교체	복구 조회 지원, 기존 intersection 제외를 trace로 확인
쿼리별 인덱스 힌트	데이터·버전 변화 후 지정한 계획의 적합성 점검 필요
전역 intersection 비활성화	해당 UPDATE 외의 쿼리에도 영향
PK 기준 갱신·다른 복합 인덱스	이번 비교 실험에서 검증하지 않은 대안

변경 전후의 데드락과 장기 지연 비교

실행 계획이 바뀐 뒤에는 실제 충돌과 결제 지연도 줄었는지 확인하기 위해 전체 결제 부하 테스트와 별도 DB 재현으로 범위를 나눠 변경 전후를 비교했다.

실험	처리 범위	지표
전체 결제	메시지 · PG 처리 · 복구	완료 시간 · 저장 데드락
DB 재현	선점 · 대기 모사 · 결과 저장	UPDATE 첫 시도의 성공·데드락

전체 결제 흐름의 지연 감소

큐에 요청이 계속 쌓이는 상황을 피하려고 주 부하의 도착률을 초당 40건으로 설정했고, 결제 서비스 2대·PG 서비스 2대 구성에서 인덱스 변경 전후를 각 1회 비교했다. 외부 PG 응답은 100~300ms 지연을 주는 테스트용 구현으로 모사했다.

완료 시간은 별도로 보낸 표본 요청에서 측정했다. 접수 응답(HTTP 202)을 받은 시점부터 상태 조회로 완료를 확인할 때까지의 시간이며, 폴링 간격에 따른 대기도 포함한다. 측정 스크립트

인덱스 교체 전후의 결제 완료 시간 p99

완료 시간(초) · 모든 막대에 같은 0~80초 축 적용

020406080

p99표본 요청 중 약 99%가 완료되는 시간감소

변경 전73.10초

변경 후9.28초

표본 요청의 접수 응답(HTTP 202) 수신부터 완료 상태를 폴링으로 확인할 때까지의 시간이다. 폴링 간격에 따른 대기도 포함한다.

항목	변경 전	변경 후
결제 완료 시간 p99	73.10초	9.28초
승인 결과 저장 데드락	163건	0건

변경 후 실행에서는 결과 저장 데드락이 관측되지 않았고, 저장 실패 뒤 복구를 기다리던 장기 지연이 줄면서, p99는 약 73초에서 9초로 감소했다. 전체 결제 부하 테스트 보고서

별도 DB에서의 결과 저장 충돌 비교

이 실험은 결제 애플리케이션을 거치지 않고 스크립트가 MySQL에 직접 SQL을 실행한 비교다.

조건	DB 재현 환경
DB	Docker의 MySQL 8.0.46 · InnoDB · REPEATABLE READ
준비	별도 DB에 프로젝트 V1~V7 적용 · 완료 이력 50만 건 적재
도구	reproduce.py가 컨테이너의 mysql 클라이언트로 SQL 실행
동시 실행	DB 연결 10개 · 연결별 서로 다른 주문 500건 · 총 5,000건
비교	같은 스크립트로 각 1회 실행 · 변경 후에는 V8 인덱스 교체 적용

스크립트는 주문마다 다음 순서를 실행했다.

1. 요청 선점: PENDING으로 넣은 주문을 PK로 잠그고, IN_PROGRESS로 바꾼 뒤 커밋한다.
2. 외부 호출 대기 모사: 트랜잭션 밖에서 100~300ms를 기다린다. 실제 PG에는 요청하지 않는다.
3. 승인 결과 저장: 새 트랜잭션에서 원래 UPDATE를 실행하고, 첫 시도의 성공 여부를 집계한다.

Java 서비스·메시지 전달·60초 복구 워커는 실행하지 않았다. 데드락이 나면 롤백 후 같은 UPDATE를 바로 재시도했다. 스크립트와 원본 결과는 DB 재현 보고서에서 확인할 수 있다.

항목	상태 단일 인덱스	상태·시간 복합 인덱스
결과 UPDATE 첫 시도	5,000건	5,000건
첫 시도 성공	4,972건	5,000건
첫 시도 데드락	28건 (0.56%)	0건
준비·재시도 단계 데드락	0건	0건
다른 오류·워커 중도 종료	0건	0건
실행 중 확인한 계획	index_merge	주문 번호 range

변경 전 실패한 28건은 재시도해 모두 완료됐다. 인덱스 교체 후에는 5,000건 모두 첫 시도에 성공했고, 실행 중 확인한 계획도 주문 번호 단독 검색이었다.

마치며

UNIQUE 주문 번호로 한 행을 지정해도, 검색 중에는 다른 주문의 레코드에 잠금을 요청할 수 있었다. 상태 인덱스를 함께 읽는 병합 경로가 서로 다른 주문의 UPDATE를 충돌시켰다.

(status)를 (status, updated_at)으로 교체하자 승인 UPDATE는 주문 번호 인덱스만 사용했다. 상태 조건과 복구 조회를 유지하면서 병합 경로를 제외한 결과다.

확인 범위	전	후
전체 결제 · 완료 시간 p99(초)	73.10	9.28
전체 결제 · 결과 저장 데드락(건)	163	0
DB 재현 · 결과 UPDATE 첫 시도 데드락(건)	28	0

각 조건을 한 번씩 측정해 확인한 결과다.

처음에는 IN_PROGRESS를 10%로 두고 스키마를 단순화해 병합 계획을 재현하지 못했다. 완료 이력이 대부분인 분포와 원래 스키마를 반영한 뒤에야 재현됐다.

앞으로는 행 수와 동시 요청 수에 더해 다음 조건도 함께 맞춰 재현하려 한다.

• 스키마: 컬럼의 자료형·길이·정렬 규칙
• 상태 분포: 누적된 완료 이력과 처리 중인 행의 비율
• 트랜잭션 경계: 선점·외부 호출·결과 저장의 분리 방식

복구 기능은 변경 전에도 최종 결제 상태를 올바르게 만들고 있었다. 비동기 처리를 검증할 때는 최종 상태와 함께 저장 실패·복구 대기·완료 시간의 분포까지 확인하려 한다.

재현 환경과 참고 자료

• 프로젝트 환경: Java 21, Spring Boot 3.4.4, MySQL 8.0
• DB 재현 환경: MySQL 8.0.46, InnoDB, REPEATABLE READ

스키마와 분포 실험의 조건

재현은 프로젝트 V1~V7 마이그레이션을 적용한 별도 DB에서 수행했다. UNIQUE와 원래 WHERE를 유지했으며, 인덱스 힌트·비용 상수·인위적인 통계값 변경은 사용하지 않았다.

항목	프로젝트 스키마 재현	초기 정적 테스트
주문 번호	VARCHAR(100)	VARCHAR(64)
상태	프로젝트의 5개 값 ENUM	VARCHAR(20)
결과	VARCHAR(1024), 이력마다 약 400바이트	VARCHAR(255)
정렬 규칙	utf8mb4_unicode_ci	utf8mb4_0900_ai_ci

비용 trace의 계산 단계

optimizer trace는 쿼리를 실행하기 전에 옵티마이저가 남긴 검색 방법별 예상 비용의 계산 기록이다. 아래에서는 행 수를 추정하고, 읽기 비용을 더해 병합 후보를 선택하는 과정을 살펴본다.

예상 행 수의 근거

옵티마이저가 계산에 사용한 행 수는 다음과 같다.

대상과 예상 행 수	추정 근거
전체 469,899행	실제 50만 행에 대한 InnoDB 통계의 근사값이다.
주문 번호 조건 1행	UNIQUE 인덱스이므로, 지정한 주문 번호에 해당하는 행은 최대 1건이다.
상태 조건 10행	상태 인덱스에서 IN_PROGRESS 범위를 살펴보고 추정한 값이다.

index dive는 인덱스에서 조건에 해당하는 범위의 양 끝을 찾아, 그 사이의 행 수를 추정하는 방식이다. 이번 trace의 index_dives_for_eq_ranges: true는 이 방식을 사용했다는 기록이다.

공통 행 수는 주문 번호와 상태 조건이 서로 독립적이라는 가정으로 계산한다.

1. 상태 비율 계산: 전체 중 IN_PROGRESS의 비율은 10 ÷ 469,899다.
2. 공통 행 수 추정: 주문 번호로 찾을 1행에 이 비율을 곱하면 1 × (10 ÷ 469,899) ≈ 0.000021행이 된다.

병합 비용과 단독 검색 비용

병합 후보의 총비용은 두 인덱스를 읽는 비용 + 두 검색에 공통으로 남을 행의 데이터를 읽는 비용이다.

병합 총비용 1.23301의 계산

인덱스 읽기

주문 번호 인덱스0.980542

상태 인덱스+ 0.252470

두 인덱스 읽기 비용의 합 약 1.23301 cumulated_index_scan_cost

+

공통 행의 데이터 읽기

인덱스에서 얻은 PK로
PRIMARY 레코드를 찾아 읽음

옵티마이저가 추정한 공통 행 수 1 × (10 ÷ 469,899) ≈ 0.000021행 matching_rows_now

↓비용 함수에 정수로 전달
소수점 이하를 버리면 0행

추가 행 읽기 비용 0 disk_sweep_cost

↓ 두 비용을 더함

병합 후보의 총비용

1.23301+0=1.23301

cumulated_total_cost

옵티마이저가 trace에 기록한 계산값. 비용은 실행 시간이 아닌 내부 비교 단위다. 구현: 병합 비용 계산 · 행 수의 정수 변환

그림의 공통 행 수와 비용 계산 결과는 원본 trace에 다음과 같이 기록돼 있다.

{
  "index": "idx_pg_inbox_status",
  "matching_rows_now": 0.0000212812,
  "cumulated_index_scan_cost": 1.23301,
  "disk_sweep_cost": 0,
  "cumulated_total_cost": 1.23301,
  "chosen": true
}

옵티마이저가 비교한 것은 다음 두 검색 방법의 예상 총비용이다.

항목	주문 번호 단독	두 인덱스 병합
검색 과정	주문 번호 인덱스로 1행을 찾고, 그 행의 데이터를 읽는다.	두 인덱스에서 읽은 PK를 대조해 공통 행을 찾고, 그 행의 데이터를 읽는다.
총비용	1.64349	1.23301
값의 근거	원본 trace의 단독 검색 후보에 기록된 예상 총비용이다.	두 인덱스 읽기 비용 1.23301에 공통 행의 데이터 읽기 비용 0을 더한 값이다.

비용 계산에서는 공통 행을 0행으로 처리했지만, 실제 수정 대상은 1행이었다. 그 행의 데이터를 읽는 작업이 필요한데도, 이번 추정에서 추가 읽기 비용인 disk_sweep_cost는 0으로 계산됐다.

그 결과 병합의 예상 총비용에는 두 인덱스 읽기 비용인 1.23301만 남았다. 이 값이 주문 번호 단독 검색의 1.64349보다 낮아, 최종 계획에는 병합 검색인 index_roworder_intersect가 선택됐다.

Tags:

• Payment Platform Project

결제 복구 상태 분리 — 부하 구간에서 안전장치가 만든 처리 정지 해소

2026. 9. 6.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.4.4, MySQL 8.0, Kafka (KRaft), Redis, Docker Compose

도입

결제 확정은 외부 벤더 (PG사)의 승인을 받아야 끝나며, 승인에는 길게 수 초가 소요될 수 있다.

• 동기로 처리하면 그동안 요청 스레드와 DB 커넥션이 묶임
• 트래픽이 몰리면 대기만 하는 요청이 자원을 모두 소진

그래서 승인 요청을 받은 즉시 접수만 응답하고, 실제 벤더 호출은 메시지로 넘겨 비동기로 처리한다.

• 결제 서비스가 확정 명령을 발행
• PG 서비스가 명령을 소비해 외부 벤더를 호출
• 벤더 판정을 확정 결과 메시지로 회신
• 결제 서비스가 결과를 소비해 결제를 종결

결과적으로 확정은 두 서비스가 메시지로 주고받는 왕복 구조가 된다.

flowchart TB
    A["결제 서비스 - 확정 명령 발행"] --> B["PG 서비스 - 명령 소비"]
    B --> C["외부 벤더 승인 요청"]
    C --> D["PG 서비스 - 확정 결과 발행"]
    D --> E["결제 서비스 - 결과 소비"]
    E --> F["결제 종결"]
    A -.->|" 회신 전 중단 "| G["진행 중 상태로 고착"]
    G -.->|" 복구 배치가 접수로 복원 "| H["다시 확정될 것으로 기대"]

명령과 결과 사이에 시간 간격이 있어, 그 사이 프로세스가 중단되면 결제가 진행 중 상태로 고착될 수 있기 때문에, 이를 되살리기 위해 복구 배치를 운영한다.

• 2분 주기로 진행 중 상태에 오래 머문 결제를 조회
• 기준 시간 5분을 넘겼으면 접수 상태로 복원
• 접수 상태로 복원된 결제는 다시 확정 흐름을 타고 종결될 것으로 기대

이 배치 결국 부하 구간에서 확정 처리를 통째로 멈추게 한 원인이 되었다.

결제 상태 정의

시스템 내 결제는 다음 상태를 가진다.

상태	의미
접수	주문이 생성되고 확정에는 아직 진입하지 않음
진행 중	확정에 진입해 벤더 응답을 기다리는 중
완료	승인이 확인되어 종결됨
실패	벤더 거절 또는 재고 부족으로 종결됨
격리	자동 판정이 불가능해 운영자 확인이 필요한 상태

격리는 이 시스템에서 “판단 보류”를 담당하며, 자동 처리를 멈추고 사람이 확인하도록 남겨 두는 상태다.

발단: 처리량 측정에서 드러난 이상

인스턴스 수를 조절하면서 처리율이 오르지 않아 원인을 추적하던 중에, 병목이 Kafka 토픽의 파티션 수에 있다는 것을 발견했다.

• 하나의 파티션은 한 번에 하나의 컨슈머만 담당
• 따라서 파티션 수가 소비 병렬도의 상한으로 작용
• 파티션보다 컨슈머를 많이 띄워도 남는 컨슈머는 배정받을 파티션이 없어 대기

측정 대상 토픽은 파티션이 3이었고, PG 서비스는 컨슈머 동시성을 지정한 적이 없어 기본값 1로 동작하고 있었다. (컨슈머 하나가 파티션 셋을 담당)

• 인스턴스를 늘려도 파티션 3을 넘는 병렬 소비가 불가능
• 파티션과 동시성을 9로 조정하자 인스턴스 증설 없이 처리율 1.86배 확보

설정값 조정으로 문제가 해결되는듯 했으나, 측정 사이클을 반복할수록 결과가 불안정해졌다.

• 일정 시간 부하를 준 뒤 결제 레코드의 상태를 세는 방식으로 진행
• 요청한 결제가 전부 완료나 실패에 도달하면 그 사이클은 정상으로 판단
• 하지만 요청한 결제 중 60%만 완료 상태에 도달하고, 나머지는 완료도 실패도 아닌 상태에서 멈춤

관측: 장애 없이 발생하는 처리 정지

로그와 지표를 확인한 결과 벤더 응답과 DB 모두 정상이었다.

결제 한 건이 막히는 과정

주문 하나를 시간순으로 따라가면 다음과 같다.

경과	발생 내용	결제 상태
0초	확정 진입, 명령 발행	진행 중
40초	벤더 승인 완료, 결과 메시지 발행	진행 중 (소비 적체로 결과가 아직 처리되지 않음)
310초	복구 배치가 기준 초과로 판정	접수 (복구 배치가 복원)
330초	승인 결과가 뒤늦게 도착	접수 → 완료 전이 불가로 거부 (상태 전이 가드)
335초	재시도 5회 소진 후 격리 큐	접수 (그대로 잔류)

여기서 문제는 이 결제 한 건에 그치는 것이 아니라, 같은 파티션에서 순서를 기다리던 다른 결제들도 함께 멈추게 됐다.

• 뒤에 대기 중인 결제는 이 거부와 무관한 정상 건
• 소비가 5초 지연되면 그만큼 다른 결제의 회신도 늦어짐
• 회신이 늦어진 결제가 다시 복구 배치의 기준을 초과

문제가 심화되는 구조

flowchart TD
    A["부하 지속 - 확정 결과 회신이 기준 시간 초과"] --> B["복구 배치가 진행 중 결제를 접수로 복원"]
    B --> C["뒤늦게 도착한 승인 결과"]
    C -->|" '접수' 상태에서는 완료 전이 불가 "| D["도메인 거부"]
    D -->|" 재시도 예외 목록에 미등록 "| E["1초 간격 5회 재시도"]
    E --> F["레코드당 5초 스레드 점유"]
    F -->|" 회신 지연 심화 "| A

21:55:14  기준 시간 초과 발견   965건 → 접수로 복원
21:55:39  기준 시간 초과 발견 1,879건 → 접수로 복원    (25초 만에 2배)

진행 중 상태로 기준 시간 5분을 넘긴 결제가 계속해서 증가하는 결과가 나왔고, 그만큼 병목이 발생하게 됐다.

• 배치가 옮긴 결제가 늘면 그만큼 뒤늦은 승인이 거부될 대상도 늘어남
• 거부가 늘면 소비가 더 막히고, 막히면 기준 시간을 넘기는 결제가 다시 늘어남

항목	값
결제 요청	42,281
완료	25,539 (60%)
접수 상태로 복원되어 멈춘 결제	16,742

벤더 승인은 정상적으로 처리됐지만, 결제는 완료로 넘어가지 못하는 상태 불일치 현상과 더불어, 상태가 스스로 복구되지 않는 문제가 발생했다.

주요 원인

5초 점유하는 주체

메시지 소비 중 예외가 발생하면 에러 핸들러가 백오프를 두고 같은 레코드로 리스너를 재호출한다. (설정은 1초 간격 5회)

현상	실제 관계
오프셋 커밋 안 됨	예외로 트랜잭션이 abort 되어 발생하는 결과
뒤 메시지 대기	재시도 백오프가 리스너 스레드를 점유해서 발생
공통 원인	스레드가 5초간 다음 레코드로 못 넘어감

결과적으로 5초는 거부된 결제 하나의 손실이 아니라, 동일 파티션에서 대기 중인 정상 결제 전부에 영향을 미친다.

도착 상태와 완료 가드

완료 전이는 진행 중 상태에서만 허용되는데, 복구 배치로 인해 접수 상태로 돌아간 결제에 승인이 도착하면 이 가드에서 거부된다.

public void done(Instant approvedAt, Instant lastStatusChangedAt) {
    if (this.status != PaymentEventStatus.IN_PROGRESS) {
        throw PaymentStatusException.of(PaymentErrorCode.INVALID_STATUS_TO_SUCCESS);
    }
    ...
}

설계 결정: 도착 상태 선택

위 주요 원인을 바탕으로 다음 두 가지를 검토했다.

방안	장점	단점
접수 상태에서 완료 전이 허용	코드 변경 최소, 상태 추가 없음	확정에 들어온 적 없는 결제가 승인으로 완료
결과 대기 상태 신규 도입	거부 자체가 사라지고, 남은 건도 끝낼 길이 생김	상태가 늘어 판정하는 곳들이 함께 늘어남

접수 상태는 결제 승인 요청을 의미하므로 여기서 완료를 허용하면 상태의 정의가 무너지게 되므로, 두 번째 방안을 선택했다.

stateDiagram-v2
    state "결과 대기" as AW
    [*] --> 접수: 결제 생성
    접수 --> 진행중: 확정 진입
    진행중 --> 완료: 승인 결과
    진행중 --> 실패: 실패 결과
    진행중 --> AW: 복구 배치 1차 기준 초과
    AW --> 완료: 늦은 승인
    AW --> 실패: 늦은 실패
    AW --> 격리: 늦은 격리 또는 2차 기준 초과
    접수 --> 만료: 만료 배치
    격리 --> 실패: 운영자 안전 종결

종결 보장: 2차 기준과 기준 시각

회신이 영구히 도착하지 않는 결제를 방치하면 결제 잔류 문제가 발생하기 때문에, 2차 기준을 넘기면 격리로 옮겨 운영자가 확인하게 했다.

• 벤더가 승인했는지 모르는 채로 끝내면 실제 청구와 기록이 어긋남
• 판단 보류는 이 시스템에서 격리가 담당하는 역할
• 운영자가 벤더 상태를 조회한 후 안전 종결 수행

@Scheduled(fixedDelayString = "${reconciler.fixed-delay-ms:120000}")
public void scan() {
    Instant now = clock.instant();
    resetStaleInFlightRecords(now);              // 1차: 진행 중 → 결과 대기
    quarantineStaleAwaitingResultRecords(now);   // 2차: 결과 대기 → 격리
}

검증

1차 — 운영 기본값 그대로

기준 시간 5분을 그대로 두고 측정했다.

항목	수정 전	수정 후 (1차)
결제 요청	42,281	52,530
완료	25,539 (60%)	52,530 (100%)
끝나지 못한 결제	16,742	0
상태 예외	838	0
격리 큐 유입	분당 3건	0

40%가 끝나지 못한 채 남던 이전과 달리, 요청한 결제가 전부 완료나 실패에 도달했다.

1차에서 확인되지 않은 것

수치는 좋지만 로그에 기준 시간을 넘긴 결제가 한 건도 없었다.

지표	값	의미
기준 시간 초과	0건	복구 배치가 걸러낸 결제 없음
상태 예외	0건	거부 경로에 들어가지 않음
격리 큐 유입	0건	격리까지 간 결제 없음

• 부하 구간 동안 아직 끝나지 않은 결제가 4만 건 넘게 쌓임
• 도착률이 처리 능력을 넘었다는 뜻

부하 자체는 충분했으나, 기준 시간을 넘긴 결제가 없었던 이유는 개별 결제가 끝나기까지 걸린 시간이 기준 시간 (5분)에 도달하지 않았기 때문이다.

2차 — 기준 시간을 넘기게 만든 조건

경로까지 보기 위해 조건을 바꿔 기준 시간을 5분에서 30초로 낮췄다.

• 정상 처리도 그 시간을 넘기게 되어 배치가 대량으로 걸러냄
• 되돌아간 결제에 뒤늦은 승인이 도착하는 상황이 만들어짐

항목	수정 전 (5분 기준)	수정 후 (30초 기준)
결제 요청	42,281	51,704
완료	25,539 (60%)	51,704 (100%)
끝나지 못한 결제	16,742 (영구)	0
상태 예외	838	0
격리 큐 유입	분당 3건	0

기준 시간을 넘긴 결제가 44,999건 나왔으나, 전부 무사히 결제 처리가 마무리되었다.

정리

안전장치가 장애의 원인이 된 경로

복구 배치는 멈춘 결제를 되살리려고 넣은 장치인데, 판단 근거가 경과 시간 하나뿐이라 처리가 느릴 뿐인 결제와 실제로 멈춘 결제를 구분하지 못했다.

• 부하가 이어지자 정상 처리 중인 결제까지 접수 상태로 되돌아감
• 되돌아간 자리는 승인 결과를 받을 수 없어, 뒤늦게 도착한 승인이 전부 거부됨
• 거부 예외가 재시도 대상으로 분류되어 레코드 한 건이 5초간 파티션을 점유
• 그만큼 회신이 더 늦어지고, 기준 시간을 넘기는 결제가 다시 늘어남

안전장치가 스스로 부하를 키우는 구조로, 장애가 난 구간이 없는데도 처리 정지가 발생했다.

접수 대신 결과 대기로

결과 대기라는 새 상태를 추가해, 늦게 도착한 승인을 거부 없이 그대로 수용하도록 했다.

상황	기존	변경 후
진행 중인 결제가 기준 시간을 넘김	접수 상태로 되돌림	결과 대기 상태로 옮김
그 뒤 승인이 도착	완료 전이가 거부되어 재시도 5회 소진	그대로 완료 처리
승인이 끝내 오지 않음	완료도 만료도 되지 못한 채 남음	2차 기준을 넘기면 격리

• 부하 구간에서 40%가 끝나지 못한 채 남던 결과가 전건 종결로 바뀜
• 함께 쌓이던 상태 예외와 격리 큐 유입도 0
• 접수 상태가 결제 요청 시점에만 생기게 되어, 만료 배치가 매 주기 집어 들었다가 그냥 넘기던 결제도 사라짐

Tags:

• Payment Platform Project

재고 선차감 캐시 분해 — Redis 샤딩을 전제로 원자성 경계 조정

2026. 8. 22. - Last update: 2026. 9. 5.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.4.4, MySQL 8.0, Kafka (KRaft), Redis, Docker Compose

도입

MSA 전환 이후 결제 서비스와 상품 서비스는 서로 다른 데이터베이스를 사용한다.

• 재고 잔고는 상품 서비스에서 관리
• 외부 벤더 (PG) 승인이 완료된 결제만 최종적으로 재고를 차감

이 분리된 구조에서는 외부 벤더 승인 과정의 네트워크 지연이 문제가 된다.

• 승인 왕복에 길게는 수 초가 소요
• 대기 시간 동안 동일 상품에 대한 다른 결제 요청이 지속적으로 유입
• 실제 잔고는 승인 시점에 감소하므로, 그 사이 초과 판매가 발생할 위험 존재

초과 판매를 막기 위해 결제 진입 시점에 Redis 캐시에서 재고를 미리 빼두는 ‘선차감 게이트’를 구축했다.

flowchart TB
    A["결제 확정 요청"] --> B["게이트 - Redis 재고 선차감"]
    B -->|" 부족 "| C["즉시 거절"]
    B -->|" 충분 "| D["벤더 승인 요청"]
    D -->|" 승인 "| E["상품 서비스 재고 잔고 차감"]
    D -->|" 실패 "| F["게이트 재고 복구"]

결제 상태 정의

시스템 내에서 결제는 다음 세 가지 최종 상태를 가진다.

• 완료: 벤더 승인이 나고 실제 재고 잔고까지 차감된 상태
• 실패: 벤더가 거절했거나 선차감 단계에서 재고가 부족해 거절된 상태
• 만료: 완료나 실패로 전이되지 못한 채 일정 시간이 지나 시스템 배치가 강제 종료한 결제

기존 구현: 스크립 하나로 전체 처리

초기 구조에서는 Redis Lua 스크립트 하나가 주문에 담긴 모든 상품의 재고를 원자적으로 처리했다.

• 단일 스레드로 동작하는 Redis 특성상 스크립트 실행 중에는 다른 명령이 끼어들 수 없음
• 검증과 차감이 하나의 트랜잭션처럼 동작

-- 결제 단위 재고 선차감 스크립트
-- KEYS[1]       = decrement:done:{orderId}  (차감 완료 마커)
-- KEYS[2..N+1]  = stock:{productId}         (N개 상품 재고 키)
-- ARGV[1..N]    = 차감 수량 N개
-- ARGV[N+1]     = 마커 수명 (초, P8D = 691200)

local dedup_key = KEYS[1]
local n = #KEYS - 1

-- 1. 중복 요청 차단 (마커 선점)
local set_result = redis.call('SETNX', dedup_key, '1')
if set_result == 0 then
    return 'ALREADY_DONE'
end
redis.call('EXPIRE', dedup_key, tonumber(ARGV[n + 1]))

-- 2. 모든 상품 재고 검증
for i = 1, n do
    local stock = tonumber(redis.call('GET', KEYS[i + 1]) or '0')
    if stock < tonumber(ARGV[i]) then
        redis.call('DEL', dedup_key)  -- 재시도 가능하게 표시 삭제
        return 'INSUFFICIENT'
    end
end

-- 3. 전체 차감 실행
for i = 1, n do
    redis.call('DECRBY', KEYS[i + 1], ARGV[i])
end

return 'OK'

이 접근 방식은 두 가지 강력한 보장을 제공했다.

• 원자성 보장: 상품 중 하나라도 재고가 부족하면 어떠한 데이터도 변경하지 않음
• 동시성 제어: 주문 ID를 키로 사용하는 마커 (decrement:done)를 통해 동일 주문의 중복 요청을 즉시 차단

결제가 실패하여 차감했던 재고를 복구할 때도 별도의 복구 완료 마커 (compensation:done)를 남겨 동일 주문에 대한 중복 롤백을 방지했다.

문제 인식: Redis 샤딩 제약

단일 Redis 인스턴스에서는 효율적인 방식이나, 클러스터 환경으로 확장할 경우 구조적 한계에 부딪힌다.

• Redis Cluster는 데이터를 여러 노드의 해시 슬롯으로 분산 저장
• Lua 스크립트 내부에서 접근하는 모든 키는 동일한 슬롯에 존재해야 실행 가능
• 기존 방식은 주문 내 여러 상품의 키를 동시에 참조하므로, 키들이 서로 다른 슬롯에 흩어질 확률이 높음

키의 특정 부분을 중괄호로 묶는 해시태그 ({}) 기능을 활용하여 연관된 키들을 같은 슬롯에 모으기 위한 기준을 결정해야 했다.

기준	장점	단점
주문	주문 전체를 스크립트 한 번에 처리 가능	같은 상품의 재고가 여러 주문 슬롯으로 파편화되어 총량 관리 불가
사용자	특정 사용자 트래픽 분산 용이	동일 상품 재고 관리가 분산되어 정합성 유지 불가
상품	단일 상품의 재고 데이터를 한 곳에서 일관성 있게 관리 가능	여러 상품이 포함된 주문을 스크립트 하나로 처리할 수 없음

재고의 근본적인 정합성을 지키기 위해서 상품을 기준으로 슬롯을 할당하는 방법을 채택하였다.

트레이드오프와 원칙 설정

상품 단위로 차감 스크립트를 분리하면, 중간 단계에서 실패가 발생할 수 있다.

• 상품 A, B는 차감에 성공했으나 상품 C에서 재고 부족 발생 시 결제는 거절
• 이 때 게이트에는 롤백 전까지 상품 A와 B의 차감 기록이 잔존
• 스크립트가 알아서 해주던 부분 실패 롤백을 애플리케이션 로직으로 직접 구현 필요

부분 실패 시 발생하는 오차의 수용 여부를 결정하기 위해 게이트의 역할을 재정의했다.

• 미회수 차감이 남으면 실제 잔고보다 게이트 재고가 적게 표시됨
• 과소 평가 오차: 판매 가능한 물건을 일시적으로 못 파는 기회비용으로 한정
• 과대 평가 오차: 실제 재고를 초과하여 판매하게 되므로 절대 허용 불가
• 오차의 회복: 롤백되지 않은 차감분은 추후 백그라운드 배치를 통해 복구

이 전제를 바탕으로 정합성 훼손을 원천 차단하고 일시적인 과소 평가 오차를 수용하는 방향으로 수정했다.

구조 개편: 상품 단위 분할

상품 번호 (productId)를 해시태그로 감싸, 단일 상품과 관련된 키가 항상 동일한 슬롯에 배치되도록 구성을 변경했다.

키	용도
stock:{productId}	해당 상품의 남은 게이트 재고 잔량
decrement:done:{productId}:orderId	특정 주문이 해당 상품을 차감했음을 증명하는 완료 마커
compensation:done:{productId}:orderId	특정 주문이 해당 상품을 복구했음을 증명하는 완료 마커

Lua 스크립트 역시 한 번에 하나의 상품만 다루도록 축소했다.

-- 상품 단위 재고 선차감 스크립트
-- KEYS[1] = decrement:done:{productId}:orderId
-- KEYS[2] = stock:{productId}
-- ARGV[1] = 차감 수량 / ARGV[2] = 마커 수명(초)

local dedup_key = KEYS[1]
local stock_key = KEYS[2]
local qty = tonumber(ARGV[1])

local set_result = redis.call('SETNX', dedup_key, '1')
if set_result == 0 then
    return 'ALREADY_DONE'
end
redis.call('EXPIRE', dedup_key, tonumber(ARGV[2]))

local stock = tonumber(redis.call('GET', stock_key) or '0')
if stock < qty then
    redis.call('DEL', dedup_key)
    return 'INSUFFICIENT'
end

redis.call('DECRBY', stock_key, qty)
return 'OK'

이제 애플리케이션 코드가 주문에 포함된 상품 목록을 순회하며 차감 스크립트를 개별적으로 호출한다.

• 도중에 재고 부족 등 예외가 발생하면 즉각 순회를 중단
• 순회가 멈춘 시점까지 성공적으로 차감된 상품들만 역순으로 롤백 스크립트 호출

private StockDecrementResult decrementEachProduct(String orderId, List<PaymentOrder> paymentOrderList) {
    List<PaymentOrder> decrementedThisCall = new ArrayList<>();

    for (PaymentOrder order : paymentOrderList) {
        StockDecrementAtomicResult result = stockCachePort.decrementAtomic(orderId, order);

        if (result == StockDecrementAtomicResult.INSUFFICIENT) {
            rejectDecrementedProducts(orderId, decrementedThisCall);
            return StockDecrementResult.REJECTED;
        }

        if (result == StockDecrementAtomicResult.OK) {
            decrementedThisCall.add(order);
        }
    }
    return StockDecrementResult.SUCCESS;
}

결과적으로 단일 스크립트가 통제하던 보장 사항들이 애플리케이션 로직으로 분산 이관되었다.

기존 스크립트의 보장 범위	변경 후 애플리케이션 처리 방식
원자적 전체 차감	개별 반복 호출 및 예외 발생 시 애플리케이션 주도 롤백
동시 요청 제어	주문 단위 분산 락(Lock)을 통한 진입 제어
롤백 완결성 보장	미결 기록 기반의 비동기 백그라운드 복구 배치 도입

하단 섹션에서는 이관된 기능 중 동시성 제어와 사후 복구를 애플리케이션 단에서 어떻게 재구현했는지 구체적으로 다룬다.

동시성 제어 복원: 주문 단위 락

기존 구조에서는 락 (Lock) 없이도 차감 마커 하나를 선점하는 행위가 동일 주문의 중복 요청을 완벽히 통제했지만, 상품 단위 분할로 더이상 보장하지 못하게 됐다.

sequenceDiagram
    participant A as 요청 1
    participant G as 게이트(Redis)
    participant B as 요청 2
    A ->> G: 상품 1 차감 시도
    G -->> A: 성공 (OK)
    B ->> G: 상품 1 차감 시도
    G -->> B: 이미 처리됨 (ALREADY_DONE)
    B ->> G: 상품 2 차감 시도
    G -->> B: 성공 (OK)
    A ->> G: 상품 2 차감 시도
    G -->> A: 이미 처리됨 (ALREADY_DONE)
    Note over A: 상품 2를 이미 확보했다고 판단
    B ->> G: 상품 3 차감 시도
    G -->> B: 재고 부족
    B ->> G: 자신이 확보한 상품 2 롤백
    Note over A,B: 타 결제 취소로 상품 3 재고 반환
    A ->> G: 상품 3 차감 시도
    G -->> A: 성공 (OK)
    Note over A,G: 요청 1은 결제를 통과시키지만 상품 2는 이미 롤백됨

요청 1은 모든 상품 확보에 성공했다고 간주하여 결제를 속행하지만, 게이트 상에서 상품 2의 재고는 요청 2의 롤백으로 인해 이미 반환된 상태가 된다.

• 반환된 상품 2의 재고를 제3의 사용자가 구매하게 되면 초과 판매 발생
• 동일한 결제 건에 대해 요청 2는 사용자에게 거절을 응답하고 요청 1은 결제를 진행하는 불일치 결과 발생

이 결함을 제거하기 위해 상품 순회를 시작하기 전 주문 식별자 기반의 락 선점 로직을 도입했다.

public StockDecrementResult decrementStock(String orderId, List<PaymentOrder> paymentOrderList) {
    Optional<String> lockToken = stockCachePort.acquireOrderLock(orderId);
    if (lockToken.isEmpty()) {
        return StockDecrementResult.ALREADY_PROCESSING;
    }
    try {
        return decrementEachProduct(orderId, paymentOrderList);
    } finally {
        stockCachePort.releaseOrderLock(orderId, lockToken.get());
    }
}

락 획득에 실패한 요청은 결제 상태를 오염시키지 않고 즉시 ALREADY_PROCESSING을 반환하며 물러난다.

• 이 결과를 일반 재고 부족 거절과 동일하게 취급하면, 앞선 정상 요청의 결제 상태가 실패로 덮어씌워질 위험 존재
• 거절과 실패를 명확히 구분하는 별도 상태로 정의하여 분기 처리

락 해제 시에는 선점 당시 발급받은 토큰이 동일한지 검증하는 스크립트를 사용한다.

if redis.call('GET', lock_key) == token then
    return redis.call('DEL', lock_key)
else
    return 0
end

토큰 검증이 누락될 경우 락 타임아웃과 맞물려 재고 정합성 문제가 발생한다.

sequenceDiagram
    participant A as 요청 A
    participant Redis as Redis 락
    participant B as 요청 B
    participant C as 요청 C
    A ->> Redis: 락 획득 시도 (TTL 30초)
    Redis -->> A: 성공 (토큰 A)
    Note over A: 대규모 GC Pause 등<br/>30초 이상 지연 발생
    Note over Redis: TTL 만료로 락 자동 해제
    B ->> Redis: 락 획득 시도
    Redis -->> B: 성공 (토큰 B)
    Note over B: 차감 로직 진입
    Note over A: 지연 회복 후<br/>finally 블록 진입
    A ->> Redis: 명시적 해제 호출<br/>(토큰 검증 없는 DEL)
    Note over Redis: 요청 B의 락이 무단 삭제됨
    C ->> Redis: 또 다른 재시도 인입 및 락 획득 시도
    Redis -->> C: 성공 (토큰 C)
    Note over C: 차감 로직 진입
    Note over B,C: 요청 B와 C가 동시에 상품 반복문을 실행 (동시성 문제 발생)

동시다발적으로 반복문이 순회되면서 동시성 문제가 발생하는 것을 원천 차단하기 위해 발급받은 고유 토큰 (UUID) 대조 방어 로직을 스크립트에 반드시 포함했다.

2중 방어 체계: 중복 및 재시도 요청 차단

재시도 요청이 유입되어 새로운 UUID를 발급받더라도, 2중 방어 체계를 통해 중복 차감을 차단한다.

1단계: 주문 락 (동시 진입 차단)

락의 키 (Key)는 주문 번호이며, UUID는 값 (Value)으로 할당한다.

• 진입 차단: 같은 주문에 대한 재시도 요청이 와도 키가 이미 점유되어 있어 락 획득 실패
• UUID 역할: 락을 풀 때 본인의 락만 해제할 수 있도록 검증하는 서명

2단계: Dedup 마커 (완료 후 재진입 차단)

선행 요청이 완료되어 락이 풀린 뒤 재시도 요청이 들어오면 락을 통과하지만, 차감 스크립트 내부의 멱등성 검증에 가로막힌다.

local dedup_key = KEYS[1]  -- decrement:done:{productId}:{orderId}

if redis.call('SETNX', dedup_key, '1') == 0 then
    return 'ALREADY_DONE'
end

• 선행 요청 처리 시 남긴 완료 마커 (Dedup)로 인해 후행 요청의 SETNX 검사 실패
• 재고 차감 없이 안전하게 종료

사후 복구: 서버 다운 및 네트워크 단절 대비

애플리케이션이 직접 롤백을 수행하는 구조는 프로세스 강제 종료나 네트워크 단절 발생 시 심각한 상태 불일치를 유발한다.

• 상태 불일치: Redis 차감은 성공했으나 데이터베이스에 결과를 기록하기 직전 서버가 다운되면 결제는 미완료 상태로 방치
• 고아 재고 발생: 롤백을 실행해야 할 애플리케이션 스레드가 증발하면 해당 재고는 복구되지 못한 상태로 유지

이러한 유실을 막기 위해 차감 시도 전 데이터베이스에 미결 상태 레코드를 먼저 기록하고, 백그라운드 스케줄러가 남은 고아 내역을 찾아 회수하는 2차 방어선을 구축했다.

아키텍처 요약: 트랜잭션 생명주기와 자원 효율화

세부 구현을 살펴보기 앞서 1차 방어선 (Redis 락)과 2차 방어선 (데이터베이스 미결 기록)이 결합된 전체 트랜잭션 생명주기를 요약하면 다음과 같다.

sequenceDiagram
    participant O as 결제 오케스트레이터
    participant DB as 결제 데이터베이스
    participant Redis as Redis 캐시
    Note over O,Redis: 1. 분산 락 획득 (데이터베이스 커넥션 미사용)
    O ->> Redis: 결제 요청(주문 단위) 제어권 획득 (동시 요청 방어)

    loop 주문에 포함된 각 상품마다 반복
        Note over O,DB: 2. 단기 트랜잭션 (TX 1)
        O ->> DB: 차감 이력 사전 기록 (상태: 미결/차감 중)
        DB -->> O: 즉시 커밋 후 DB 커넥션 반납
        Note over O,Redis: 3. 네트워크 통신 (DB 커넥션 반납 상태)
        O ->> Redis: 상품 단위 캐시 재고 차감 시도
    end

    O ->> Redis: 분산 락 해제
    Note over O,DB: 4. 메인 트랜잭션 (TX 2)
    O ->> DB: 결제 진행 상태(IN_PROGRESS) 갱신 및 차감 이력 확정 처리
    DB -->> O: 최종 커밋 후 DB 커넥션 반납

트랜잭션 구간을 분리한 구조는 다음 아키텍처 이점을 제공한다.

• 사후 복구 보장: Redis 통신 중 프로세스가 종료되더라도 디스크에 선행 커밋된 미결 레코드를 근거로 스케줄러가 누락된 롤백 수행
• 커넥션 점유 최소화: TX 1 커밋 및 반납 -> Redis I/O -> TX 2 커밋 및 반납 순서로 외부 통신 지연이 데이터베이스 커넥션 풀에 미치는 영향 차단

추적 기록을 Redis가 아닌 RDB에 남기는 이유

차감 연산은 초고속 인메모리인 Redis에 위임하면서도, 의도와 결과의 기록 (Log)은 영속성이 보장되는 데이터베이스에 남긴 데에는 다음과 같은 공학적 근거가 있다.

• 분산 트랜잭션 회피: 추후 PG사 승인이 완료될 때, 결제 최종 상태 (DONE) 갱신과 장부 확정 (COMMITTED) 처리를 동일한 트랜잭션으로 묶어 원자성을 보장
• 단일 진실 공급원 (SSOT): 사후 복구에 필요한 결제 최종 상태를 외부 네트워크 조회 없이 일관되게 확인 가능

이러한 설계 원칙에 따라 데이터베이스에 기록되는 레코드의 구조는 다음과 같다.

CREATE TABLE stock_hold_record
(
    id         BIGINT       NOT NULL AUTO_INCREMENT,
    order_id   VARCHAR(100) NOT NULL,
    product_id BIGINT       NOT NULL,
    quantity   INT          NOT NULL,
    status     VARCHAR(20)  NOT NULL,
    UNIQUE INDEX uk_stock_hold_record_order_product (order_id, product_id),
    INDEX idx_stock_hold_record_status (status)
);

특정 주문에 포함된 개별 상품마다 하나의 행이 생성되며, 클라이언트 재시도로 인해 동일 내역이 중복 기록되지 않도록 복합 유니크 키 (order_id, product_id)를 설정했다.

상태	식별 값	의미
미결	NOISE	차감 시도 직전 데이터베이스에 기입한 초기 상태
복구	REVERTED	정상적으로 롤백이 수행되었거나 롤백할 내역이 없어 닫힌 상태
확정	COMMITTED	벤더 승인이 완료되어 실제 매출로 이어진 상태

상태의 전이는 결제의 성공 및 시스템 장애 여부에 따라 두 가지 명확한 경로로 갈라진다.

정상 결제 흐름 (Success Path)

결제가 무사히 벤더 승인까지 마치면 결제 완료 트랜잭션과 함께 장부 상태가 확정된다.

• 차감 전: NOISE 상태로 초기 기록됨
• 결제 완료: COMMITTED 상태로 갱신되며 사후 복구 대상에서 영구히 배제됨

시스템 장애 및 사후 복구 흐름 (Recovery Path)

결제 도중 서버가 다운되면 장부는 COMMITTED로 전이되지 못하고 NOISE 상태로 방치되며, 스케줄러가 이를 발견하여 다음 순서로 원복을 수행한다.

1. 타겟 수집: 상태가 NOISE인 레코드를 데이터베이스에서 조회
2. 종결 검증: 해당 결제가 완전히 실패하거나 만료되었는지 확인 (진행 중인 결제의 재고를 탈취하는 초과 판매 방지)
3. 재고 원복: 검증을 통과하면 Redis에 접근해 차감되었던 quantity만큼 재고 잔량 복구
4. 장부 마감: 복구가 끝난 레코드는 REVERTED 상태로 닫아 이중 복구를 차단

stateDiagram-v2
    direction TB
    [*] --> NOISE: 차감 시도 전 기록
    NOISE --> COMMITTED: 결제 성공 시 갱신 (복구 제외)
    NOISE --> REVERTED: 서버 다운 방치 건 배치가 원복 후 마감
    COMMITTED --> COMMITTED: 무시 (이미 판매된 재고)

사후 복구 정합성을 지키는 세부 제어 기법

기본 상태 전이 흐름이 분산 환경에서 안전하게 동작하도록 다음 세 가지 방어 로직을 추가로 적용했다.

• 불필요 롤백 차단: 결제 성공 시 메인 트랜잭션 내에서 장부를 COMMITTED로 확정하여, 배치가 기판매 재고를 롤백하는 현상을 원천 배제
• 스케줄러 모니터링: 배치 구동 카운터와 미결 잔량 게이지를 지표로 구성하여 복구 지연 현상을 시각화

서버 크래시 시나리오 수렴 검증

어느 지점에서 장애가 발생하더라도 시스템은 두 개의 방어선을 통해 정상 상태를 회복할 수 있게 됐다.

• 1차 방어선: 주문 단위 분산 락
• 2차 방어선: 미결 레코드 기반 사후 복구 로직

flowchart TB
    subgraph Crash [극한의 서버 장애 발생 지점]
        direction TB
        E1[다건 재고 차감 중 프로세스 종료]
        E2[벤더 결제 승인 중 네트워크 단절]
        E3[애플리케이션 롤백 중 서버 다운]
    end

    subgraph State [장애 직후 방치된 데이터 상태]
        direction LR
        REDIS[("Redis\n기차감 마커 잔존")]
        DB[("RDB\n미결(NOISE) 장부 방치")]
    end
    Crash --> State

    subgraph Healing [정합성 자가 치유 경로]
        direction TB
        R1{클라이언트의\n동일 주문 재시도 유입 여부}
        R1 -->|재시도 유입| D1_1["[1차 방어선] 주문 단위 분산 락 획득"]
        D1_1 --> D1_2["Redis에 잔존한 '기차감 마커' 대조"]
        D1_2 --> D1_3["이미 차감된 상품은 스킵 (멱등성 보장)"]
        D1_3 --> D1_4["누락된 잔여 상품만 추가 차감 진행"]
        R1 -->|재시도 미발생| D2_1["결제 만료 배치의 결제 영구 실패 처리"]
        D2_1 --> D2_2["[2차 방어선] 사후 복구 배치 스케줄러 가동"]
        D2_2 --> D2_3["RDB에 방치된 'NOISE 장부' 수집 및 종결 검증"]
        D2_3 --> D2_4["활성 결제 탈취 방어 후 유령 재고 안전 원복"]
    end

    State --> R1
    C1(((정상: 결제 완료)))
    C2(((정상: 결제 실패 및 재고 원복)))
    D1_4 --> C1
    D2_4 --> C2

클라이언트의 자동 재시도와 백그라운드 배치가 경합하거나 연쇄 장애가 발생하더라도, 각 방어선에 내장된 안전장치를 통해 정합성이 완벽히 유지된다.

• 클라이언트의 동일 주문 재시도 유입 시 (1차 방어선 작동)
  • 네트워크 지연 등으로 동일한 order_id 요청이 다시 유입될 경우, Redis의 과거 차감 마커를 대조하여 멱등성 보장
  • 이미 차감된 상품은 안전하게 건너뛰고 누락된 상품만 추가 차감하여 결제 완료
• 재시도 미발생 및 결제 만료 시 (2차 방어선 작동)
  • 클라이언트가 이탈하여 활성 결제가 타임아웃 처리되면, 초과 판매를 막기 위해 결제의 최종 실패 여부를 선제 검증
  • 검증을 통과한 미결 상태 (NOISE)의 유령 재고만 찾아내어 안전하게 원복
• 복구 도중 연쇄 장애 발생 시
  • 롤백 중 서버가 다시 다운되더라도 DB의 장부 상태가 닫히지 않고 열려 있음
  • 데이터베이스 영속성에 의해 다음 배치 주기에 누락 없이 재조회되어 복구를 완수

다양한 장애 지점에 대한 시스템의 최종 수렴 경로는 다음과 같다.

장애 시나리오	직면한 시스템 상태	최종 수렴 경로
다건 차감 중 프로세스 종료	일부 상품만 Redis에서 차감된 채 결제 중단	결제 타임아웃 처리 후 2차 방어선(배치)이 기차감분을 찾아 회수
애플리케이션 롤백 중 서버 다운	예외 발생 후 롤백 스레드가 증발하여 원복 중단	원복되지 못한 재고가 미결 장부에 남아 다음 배치 주기에 일괄 회수
사후 복구 스케줄러 다운	2차 방어선이 중지되어 유령 재고가 방치됨	RDB 영속성에 기반하여 스케줄러 재기동 시 누락 없이 회수

구현 중 발생한 트러블슈팅

장부 재오픈 순서와 데드락

장부는 동일한 조합에 대해 한 행만 유지하므로, 데이터가 없으면 삽입하고 있으면 상태를 갱신하는 방식으로 구현했다.

• 초기에는 갱신 (Update)을 시도하고 대상이 없으면 삽입 (Insert)하는 순서로 작성
• 갱신 대상이 없을 경우 0건 처리와 함께 갭 락 (Gap Lock)을 점유
• 이후 삽입을 시도할 때 이미 점유한 갭 락과 삽입 의도 락 (Insert Intention Lock)이 충돌
• 동시 다발적인 트랜잭션이 서로 갭 락을 쥔 채 대기하며 데드락 유발

이를 해결하기 위해 삽입을 먼저 시도하도록 순서를 변경했다.

public String openHold(String orderId, PaymentOrder paymentOrder) {
    // ...
    Optional<String> inserted = tryInsertAsNoise(orderId, productId, quantity);
    if (inserted.isPresent()) {
        return inserted.get();
    }

    Optional<String> reopened = tryReopenAsNoise(orderId, productId, quantity);

    // ...
}

• 데이터가 없을 때의 삽입은 갭 락 없이 단일 레코드 락만 점유하여 충돌 회피
• 삽입이 유일 키 제약조건 위반으로 실패하면 대상 행이 존재한다는 의미이므로, 이후의 갱신은 갭 락 없이 수행됨

다중 복구 주체 경합 방어

사후 복구 배치와 애플리케이션 예외 처리기가 동시에 롤백을 시도할 경우 다음과 같은 두 가지 결함이 발생할 수 있다.

• 이중 롤백 문제: 단일 취소 건에 대해 다수의 주체가 재고를 증가시켜 총 재고 초과 복구
• 무한 루프 문제: 롤백이 이미 완료된 사실을 인지하더라도 DB 장부를 닫지 않으면, 스케줄러가 해당 건을 영구적으로 재수집

결함을 해결하기 위해 Redis 멱등성 마커와 RDB 장부 종결 처리를 결합한 이중 방어선을 구축했다.

sequenceDiagram
    participant App as 예외 처리기
    participant Batch as 복구 배치
    participant Redis as Redis
    participant DB as RDB
    Note over App,DB: [As-Is] 다중 주체 경합 시 문제 발생 시나리오
    App ->> Redis: 재고 복구 (+1)
    Batch ->> Redis: 후행 주체의 재고 복구 시도 (+1)
    Note over Redis: 단일 취소 건에 대해 재고가 2번 증가
    Batch ->> DB: 미결(NOISE) 장부 상태 검사
    Note over Batch,DB: 롤백이 불필요하다고 판단하여 상태 방치
    Note right of DB: 다음 배치 주기에 동일 장부가 중복 수집
    Note over App,DB: [To-Be] 멱등성 보장 및 무한 루프 방어 시나리오
    App ->> Redis: 복구 마커 생성 및 재고 복구 (+1)
    Note over App,Batch: App의 DB 종결 처리 지연 시간 동안 Batch가 동시 진입 (경합 상태)
    Batch ->> Redis: 후행 주체의 복구 스크립트 실행
    Redis -->> Batch: 이미 롤백됨 (ALREADY_DONE 반환)
    Note over Batch: 복구 마커를 통해 이중 롤백 완벽 차단
    Batch ->> DB: Redis가 무시했더라도 장부는 반드시 REVERTED 상태로 종결 처리
    App ->> DB: 선행 주체의 지연된 장부 종결 처리 (안전한 멱등성 보장)

• Redis 방어선: 복구 시 compensation:done 마커를 검증하여, 마커가 존재할 경우 재고 증가를 무시하고 ALREADY_DONE 반환
• RDB 방어선: Redis로부터 ALREADY_DONE을 반환받더라도 예외를 발생시키지 않고 반드시 DB 장부를 REVERTED 상태로 종결하여 미결 상태 해소

회고

단일 분산 락에 의존하던 아키텍처를 개편하여, 1·2차 방어선이 독립적으로 정합성을 맞추는 유연한 구조를 완성했다.

• 복구: 클라이언트 재시도 (1차)와 사후 복구 배치 (2차)를 결합해 자가 복구 시스템 구축
• 동시성 제어: Redis 멱등성 마커와 RDB 종결 처리로 다중 주체의 롤백 경합 제어

현재 한계점

견고한 방어선을 구축하기 위해 단일 스크립트에 의존하던 로직을 여러 단계로 쪼개면서, 애플리케이션과 Redis 간의 통신 횟수가 구조적으로 증가하는 단점이 발생했다.

• 잦은 네트워크 왕복: 재고 차감, 마커 생성, 상태 검증 등이 개별적인 요청으로 분리되어 주문당 발생하는 Redis 통신 (Round-Trip) 비용 크게 증가함
• 레이턴시 (Latency) 누적: 여러 번의 네트워크 I/O가 동기적으로 실행되며 전체적인 결제 처리 지연 시간에 영향을 미침

현재 아키텍처에서는 이러한 오버헤드 증가를 시스템의 장애 복원력을 얻기 위한 합리적인 트레이드오프로 수용했으며, 부하 테스트를 거쳐 구조적인 최적화 필요 여부를 점검할 예정이다.

개선 방향

이후 부하 테스트 등을 거쳐 병목이 확인된다면 다음과 같은 튜닝 기법을 Next Step으로 고려해 볼 수 있다.

• 미결 장부 Bulk Insert 및 트랜잭션 병합 적용
  • 현재는 루프 내에서 상품마다 DB 커넥션을 맺고 단건 INSERT (TX 1)를 수행함
  • 이를 개선하여, 루프 진입 전 주문에 담긴 모든 상품의 미결 레코드 (NOISE)를 1번의 Bulk Insert로 밀어 넣는 방식으로 흐름을 개편함
• 개선된 프로세스 흐름
  • Redis 분산 락 획득 (주문 단위)
  • 단기 트랜잭션 (TX 1): 전체 상품 차감 이력을 미결 상태로 한 번에 Bulk Insert 후 커넥션 반납
  • Redis 네트워크 통신: 개별 상품 캐시 차감 (실패 시 기차감분 롤백 및 에러 반환)
  • 메인 트랜잭션 (TX 2): 결제 상태 확정 및 커넥션 반납
  • Redis 분산 락 해제

Tags:

• Payment Platform Project

결제 시스템 MSA 전환기 — 분산 환경의 제약조건과 아키텍처 의사결정

2026. 8. 9.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.4.4, MySQL 8.0, Kafka (KRaft), Redis, Docker Compose

배경

Payment Platform 시리즈에서 결제 시스템을 단계별로 개선해왔다.

• 토스 결제 연동: 결제 위젯과 서버 검증 연동
• 트랜잭션 범위 최소화: 외부 API를 트랜잭션 밖으로 분리
• 결제 복구 시스템: 재시도 로직으로 장애 복구
• 보상 트랜잭션 실패 대응: 작업 테이블로 최종적 일관성 확보
• Checkout 멱등성: 중복 결제 이벤트 생성 방지
• 비동기 결제 플로우: Outbox 패턴과 LinkedBlockingQueue Worker
• 결제 복구 상태 모델: 장애 내성을 갖춘 상태 전이

직전까지 만든 구조는 Outbox 테이블에 발행 의도를 적고, 인메모리 채널로 즉시 처리하며, 폴링 Worker가 누락분을 회수하는 과정을 거쳤다.

---

전환의 동기

PG 연동 특성상 외부 의존이 강한데 그 변동을 이쪽에서 통제할 수 없다.

• 결제 도메인은 외부 의존성이 강함
• 외부 변동을 내부 시스템에서 통제 불가
• PG 벤더 외부 왕복 시간 장기화 (평균 1~3초, p99 5초 초과)
• 내부 배포 주기와 무관한 벤더 API 스펙 변경 발생

운영 위험	모놀리스에서의 문제	분리 후
벤더 호출 지연 (p99 5초 초과)	스레드·커넥션 고갈이 상품·사용자 호출 지연까지 전파	벤더 호출 자원이 pg-service으로 한정
벤더 스펙 변경	hot-fix가 다른 도메인까지 함께 배포	pg-service만 수정하고 배포
도메인별 부하 패턴 차이	알람과 지표가 한 갈래 — 인스턴스 수 조정이 서로 묶임	도메인별로 독립 조정 가능

이번 분리 작업의 범위는 다음과 같이 잡았다.

• 성능 절대 수치는 목표로 삼지 않음
  • 로컬 Docker의 I/O 한계 때문에 수치 자체에 의미를 두기 어려움
• 성공 조건은 장애 주입 후 최종 정합성 복원 여부로 판단

---

분리 기준

경계는 도메인을 기준으로 분리했다.

모듈	역할	분리 근거
payment-service	결제 도메인 본체	결제 생명주기의 주인, 상태의 진실의 원천
pg-service	PG 벤더 호출 격리	외부 의존이 강한 영역, 회복성 정책을 한 곳에 모음
product-service	상품 + 재고 도메인	결제와 다른 생명주기 (상품 등록, 재고 운영)
user-service	사용자 도메인	결제와 다른 생명주기 (사용자 등록, 조회)
gateway	외부 단일 진입점	분리된 서비스 앞단에 라우팅을 단일화
eureka-server	서비스 디스커버리	인스턴스 위치 변동 추적

flowchart TB
    Browser["브라우저"]

    subgraph Edge["엣지"]
        GW["gateway"]
        E["eureka"]
    end

    subgraph Apps["비즈니스 4서비스"]
        Pay["payment-service"]
        Pg["pg-service"]
        Prod["product-service"]
        Usr["user-service"]
    end

    subgraph Stores["저장소"]
        MyP[("mysql-payment")]
        MyG[("mysql-pg")]
        MyPr[("mysql-product")]
        MyU[("mysql-user")]
        RedD[("redis-dedupe")]
        RedS[("redis-stock")]
    end

    K[("Kafka")]
    Browser -->|HTTP| GW
    GW --> Pay & Prod & Usr
    Pay & Pg & Prod & Usr -.->|heartbeat| E
    Pay --> MyP
    Pg --> MyG
    Prod --> MyPr
    Usr --> MyU
    Pay --> RedD & RedS
    Pay <-->|" 명령 발행 / 결과 수신 "| K
    K <--> Pg
    K --> Prod
    Pg -->|HTTP| Vendor["Toss / NicePay"]
    Pay -->|HTTP 조회| Prod & Usr

통신 방식은 호출자가 응답을 기다려야 하는지를 기준으로 구분했다.

• 결과를 받아야 다음을 진행할 수 있으면 HTTP: 결제 검증에 필요한 상품·사용자 조회
• 처리 시간이 길거나 책임을 넘기고 끝나면 Kafka: 벤더 호출, 재고 확정 통지

payment와 pg 사이는 Kafka를 통해 양방향으로 통신한다.

• 명령 토픽과 결과 토픽 별도 운용
• 벤더 API 호출이 지연되어도 payment 스레드 차단 방지

---

결제 한 건이 도는 경로

승인이 정상적으로 끝나는 경우의 전체 흐름이다.

sequenceDiagram
    participant Browser as 브라우저
    participant Pay as payment-service
    participant K as Kafka
    participant Pg as pg-service
    participant Vendor as PG 벤더
    participant Prod as product-service
    Browser ->> Pay: POST /checkout (멱등키)
    Pay ->> Pay: 상품/사용자 검증 후 결제 대기 저장
    Pay -->> Browser: 201 Created
    Browser ->> Vendor: 결제창 인증
    Browser ->> Pay: POST /confirm
    Pay ->> Pay: 재고 선차감 + 발행 대기 행 커밋
    Pay -->> Browser: 202 Accepted
    Pay ->> K: 확정 명령 발행
    K ->> Pg: 명령 수신
    Pg ->> Pg: 수신함에 적재 후 워커에 위임
    Pg ->> Vendor: 승인 호출
    Vendor -->> Pg: 승인 응답
    Pg ->> K: 결과 이벤트 발행
    K ->> Pay: 결과 수신
    Pay ->> Pay: 멱등 마킹 + 결제 완료 전이
    Pay ->> K: 재고 확정 통지 발행
    K ->> Prod: 재고 확정 수신
    Prod ->> Prod: 중복 검사 + 누적 차감
    Browser ->> Pay: GET /status 폴링
    Pay -->> Browser: DONE

구간별로 정리하면 다음과 같다.

구간	하는 일	경계
주문 생성	멱등키로 중복 진입을 막고 상품·사용자를 검증해 결제 대기 상태로 저장	HTTP 동기
확정 진입	위변조 검사 후 재고를 우선 차감하고 발행 대기 행과 함께 커밋	HTTP 동기 + 202
명령 발행	발행 대기 행을 선점해 확정 명령을 내보냄	Kafka
벤더 호출	리스너가 수신함에 적고 빠지면 워커가 선점해 벤더 API를 호출하고 결과를 반영	HTTP 외부
결과 확정	결제 상태를 완료로 변경하고 재고 확정 통지를 같은 단위로 발행	Kafka EOS
결과 조회	브라우저가 최종 상태를 폴링으로 확인	HTTP 동기

• 수신함: pg가 받은 명령을 RDB에 적어 두는 테이블
  • 같은 명령을 두 번 벤더에 보내지 않기 위한 장치이자 발행 측 Outbox의 수신 측 대응
• Kafka EOS (Exactly-Once Semantics): 소비 오프셋 커밋과 다음 메시지 발행을 단일 트랜잭션으로 묶는 모드 (결정 2에서 상술)

브라우저는 확정 요청에 202를 응답받고 폴링으로 결과를 기다린다.

• 벤더 응답 대기 구간을 요청 스레드 외부로 분리
• 벤더 연동 지연 시에도 시스템의 새로운 요청 처리 능력 유지

---

결정 1 — DB를 서비스마다 두고 단일 트랜잭션을 포기

한 인스턴스 안에서 스키마만 나누지 않고, 서비스마다 MySQL 인스턴스를 따로 뒀다.

선택	결과
인스턴스 분리 (채택)	서비스 경계에서 스키마 결합 차단, cross-service 조인 자체가 불가능
스키마만 분리	같은 인스턴스를 공유해 조인이 가능하지만 서비스간 결합도 해소가 불가능

DB 분리로 기존 단일 DB가 제공하던 강한 일관성 이점을 다른 방식으로 대체해야 했다.

• 분산 트랜잭션 배제: 두 도메인 데이터를 단일 트랜잭션으로 수정 불가
• 원자적 처리 불가: 결제 상태 변경과 재고 차감을 하나의 원자적 작업으로 묶기 어려움

---

결정 2 — 멱등성을 서비스마다 다르게 구현

분산 환경에서 메시지 전달 보장은 아래 세 가지가 존재한다.

모델	의미	비용
at-most-once	최대 한 번, 손실 가능, 중복 없음	단순하지만 메시지 유실 위험
at-least-once	최소 한 번, 손실 없음, 중복 가능	소비 측 멱등성이 필수
exactly-once	정확히 한 번, 손실도 중복도 없음	발행자·브로커·소비자 3자 협력, 운영 비용 큼

메시지 전달 보장 모델은 소비 측에서 중복을 방지하는 at-least-once를 채택했다.

• at-most-once 배제: 결제 데이터 유실 위험 존재
• exactly-once 배제: 참여자가 늘어날수록 분산 합의 (coordination) 비용 급증

멱등 처리는 서비스별 소비 조건에 따라 다른 방식을 적용했다.

• 메시지 소비 후의 추가 발행 여부
• 외부 API 호출 여부

서비스	소비 후 하는 일	적용한 멱등 방식
payment	RDB 상태 전이 + 다음 메시지 발행	Kafka EOS + RDB 멱등 INSERT
pg	RDB 수신함 전이 + 외부 벤더 호출	수신함 UNIQUE + 상태 조건부 선점
product	RDB 재고 차감만	RDB 단일 검사 (재고 차감과 동시에)

payment — 발행과 소비를 한 단위로 묶음

결과 이벤트를 수신하면 결제 상태를 완료로 변경하고 재고 확정 통지를 발행한다.

• 외부 API 연동 없음
• 소비 오프셋 커밋과 메시지 발행을 단일 Kafka 트랜잭션으로 통합 처리

sequenceDiagram
    participant K as Kafka
    participant Pay as payment-service
    participant DB as RDB (payment)
    K ->> Pay: 결과 이벤트 수신
    Pay ->> Pay: Kafka 트랜잭션 시작
    Pay ->> DB: 결제 조회
    alt 이미 종결된 결제
        Note over Pay,DB: 종결 가드로 차단 후 종료
    else 아직 진행 중
        Pay ->> DB: 멱등 마킹 INSERT
        alt 신규
            Pay ->> DB: 결제 완료 전이
            Pay ->> K: 재고 확정 통지 발행
        else 이미 처리한 이벤트
            Note over Pay,DB: 아무것도 하지 않음
        end
    end
    Pay ->> DB: RDB 커밋
    Pay ->> K: 소비 오프셋을 Kafka 트랜잭션에 추가
    Pay ->> K: 한 번에 커밋

RDB와 Kafka는 서로 다른 자원이므로 단일 트랜잭션으로 묶일 수 없지만, 다음과 같이 처리할 수 있었다.

• DB 커밋 완료 후 Kafka 커밋 직전에 서버 장애 시 메시지 재전송 발생
• RDB 중복 처리가 발생할 수 있는 문제는 멱등 마킹으로 방지

pg — 수신과 벤더 호출을 다른 스레드로 분리

외부 벤더 API를 호출을 메시지 소비와 하나로 묶으면 외부 지연에 의해 다음 메시지를 소비하지 못하므로, 수신과 호출을 분리했다.

• 리스너 트랜잭션: 수신함에 PENDING 행 INSERT + 채널 적재 이벤트 발행까지만 수행 (timeout 5초)
• 워커 (가상 스레드): 채널에서 꺼내 선점 → 벤더 API 호출 → 결과 반영을 각각 별도 트랜잭션으로 처리

sequenceDiagram
    participant K as Kafka
    participant L as pg 리스너
    participant DB as RDB (pg)
    participant W as 워커 (가상 스레드)
    participant Vendor as PG 벤더
    K ->> L: 명령 수신
    L ->> DB: 수신함 PENDING INSERT
    DB -->> L: 커밋
    L ->> W: 채널 적재 (커밋 이후)
    L -->> K: ack 후 다음 메시지 수신
    W ->> DB: PENDING 행 선점 (별도 트랜잭션)
    W ->> Vendor: 승인 호출 (트랜잭션 외부)
    Vendor -->> W: 응답
    W ->> DB: 결과 반영 (별도 트랜잭션)

• 벤더 지연이 소비 속도 지연으로 이어지지 않음
• 채널 내용이 유실되거나 서버가 죽으면 폴링 워커가 미처리 행을 회수

멱등성 보장 방법

멱등성 보장의 핵심은 수신함 테이블에 있다.

• order_id UNIQUE: 같은 주문의 명령이 다시 들어와도 INSERT가 충돌하고 기존 행을 그대로 사용
• 상태 조건부 선점: 워커가 PENDING인 행만 IN_PROGRESS로 전이하므로 채널에 중복 적재돼도 벤더 호출은 1회
• 종결 상태 재수신: 저장해 둔 결과를 다시 발행할 뿐 벤더를 호출하지 않음

product — 하나의 트랜잭션으로 종료

product 서비스는 재고 차감이 단일 목적이며 이후 발행할 메시지가 없다.

• 중복 검사와 후속 상태 변경이 동일한 RDB에서 처리됨
• 검증 계층을 여러 단계로 분리할 필요 없음

sequenceDiagram
    participant K as Kafka
    participant Prod as product-service
    participant DB as RDB
    K ->> Prod: 재고 확정 수신
    Prod ->> DB: 트랜잭션 시작
    Prod ->> DB: 중복 테이블 INSERT IGNORE
    alt 이미 처리한 이벤트
        DB -->> Prod: 반영 행 0
        Prod ->> DB: 커밋 (차감 건너뜀)
    else 신규
        DB -->> Prod: 반영 행 1
        Prod ->> DB: 재고 차감
        Prod ->> DB: 커밋
    end

중복 마킹과 차감이 한 트랜잭션이라 둘 중 하나가 실패하면 같이 롤백된다.

중복 기록의 보존 기간

멱등 마킹 기록의 보존 기간은 Kafka 메시지 보관 기간과 연동하여 고정했다.

• 무한정 보존 시 테이블 크기 팽창 문제 발생
• 단기 보존 시 마킹 기록 선삭제로 인한 중복 결제 위험 노출

세 값을 부등식으로 묶어 고정했다.

값	기간	근거
Kafka 보관 기간	7일	브로커가 메시지를 버리는 시점
멱등 기록 보존	8일	보관 기간 + 복구 버퍼 1일
결과 처리 실패 격리 토픽 보관	10일	격리된 메시지를 되돌릴 수 있는 기간이 멱등 기록보다 길게 설정

---

결정 3 — 벤더 호출 재시도 방식

벤더 호출 실패 시 재시도를 수행하게 된다.

• pg-service는 기존에 왔던 동일 토픽으로 명령을 다시 발행해 재시도
• 재시도 한도 초과 시 격리 토픽 (DLQ)으로 전송

sequenceDiagram
    participant K as Kafka
    participant Pg as pg-service
    participant Vendor as PG 벤더
    participant Dlq as 격리 컨슈머
    K ->> Pg: 명령 수신 (1회차)
    Pg ->> Vendor: 승인 호출
    Vendor -->> Pg: 5xx 또는 타임아웃
    Pg ->> K: 명령 재발행 (2회차, 다음 시도 시각 지정)
    Note over Pg: 2, 3회차 같은 패턴
    K ->> Pg: 명령 수신 (4회차)
    Pg ->> Vendor: 승인 호출
    Vendor -->> Pg: 5xx
    Pg ->> K: 격리 토픽으로 발행
    K ->> Dlq: 격리 수신
    Dlq ->> Pg: 수신함을 격리 상태로 전이
    Pg ->> K: 결과 이벤트 발행 (격리)

• 수신함 테이블의 재시도 횟수 컬럼을 진실의 원천 (Single Source of Truth)으로 설정
• 메시지 재발행이나 중복 배달 시에도 해당 주문의 누적 재시도 횟수 정확히 유지

---

결정 4 — 공통 모듈 미채택

공통 모듈은 프로젝트 초기에 편리함을 주지만 변경에 있어 병목 지점이 된다고 판단했다.

• 단일 변경점 발생: 특정 서비스의 요구사항으로 공통 DTO 수정 필요
• 배포 결합도 증가: 모듈에 의존하는 모든 서비스의 연쇄 빌드 및 배포 유발
• 독립성 훼손: 독립적 배포를 위한 마이크로서비스 분리 목적 퇴색

위의 단점들로 인해 관리의 어려움이 더 커진다고 판단하여 코드 중복을 감수하는 방식을 택했다.

• 토픽 이름 상수: 세 서비스가 각자 자기 클래스에 동일한 문자열 선언
• 컨텍스트 전파 헬퍼: 가상 스레드 컨텍스트 전파 유틸리티를 서비스별 개별 유지

// payment-service — PaymentTopics.java
public static final String COMMANDS_CONFIRM = "payment.commands.confirm";
public static final String EVENTS_CONFIRMED = "payment.events.confirmed";
public static final String EVENTS_STOCK_COMMITTED = "payment.events.stock-committed";

통합 테스트로 잠재적 위험을 보완하고 서비스 간 코드 의존성을 제거했다.

• 하드코딩된 이름 불일치 시 메시지 전송 실패로 테스트 단계에서 발견하여 방지
• 동일 코드 3곳 이상 복제 또는 동시다발적 변경 시 공통화 재검토 기준 마련

---

traceId가 끊기는 자리들

MSA 전환 후 가장 까다로워진 부분은 디버깅이다.

• 기존 단일 콜스택 파악 방식 사용 불가
• 여러 서비스 홉 (hop)과 토픽을 거치는 실행 흐름 발생
• 사후 추적을 위해 분산된 모든 시스템 로그에 동일한 traceId 기록 필수

W3C Trace Context 표준의 traceparent 헤더 적용 시 자동 전파 구간과 수동 전파 구간으로 나뉘었다.

경계	끊기는 이유	대응
서블릿 요청 진입	유지됨	Spring Boot 자동 설정
Kafka 경계	관측(Observation) 설정이 기본으로 비활성화	프로듀서·리스너 설정 추가
HTTP 어댑터	유지됨	Spring Cloud 자동 설정
가상 스레드	trace 정보가 스레드 로컬(ThreadLocal)에 저장되어 새 가상 스레드 생성 시 유실	캡처·복원 헬퍼로 이중 래핑
인메모리 채널	큐에 적재하는 스레드와 소비하는 스레드가 다름	작업 객체에 컨텍스트를 동봉하여 전달
폴링 Worker	주기적인 스케줄러로 진입하므로 원래 요청 메시지의 컨텍스트가 없음	DB 수신함에 저장해 둔 traceparent 값으로 복원

Kafka 경계

Kafka 경계는 설정 두 줄로 발행 시 현재 컨텍스트의 traceparent가 메시지 헤더에 실리고, 수신 시 이를 꺼내 복원하도록 할 수 있었다.

spring:
  kafka:
    template:
      observation-enabled: true
    listener:
      observation-enabled: true

스레드 전환 케이스

구현이 까다로웠던 부분은 스레드 컨텍스트가 전환되는 경계다.

• 분산 추적 (trace) 정보는 스레드 로컬 (ThreadLocal)에 저장됨
• 스레드가 바뀌는 지점마다 명시적인 복원 처리 필요

1. 인메모리 채널 (가상 스레드 전환)

• 새 가상 스레드 생성 시 기존 컨텍스트 미전달
• 미조치 시 벤더 API 호출 구간이 원래 흐름과 단절된 별도 트레이스로 기록됨

큐 적재 시점과 꺼내는 시점에 컨텍스트를 캡처 및 복원하는 구조를 적용했다.

flowchart TB
    Consumer["Kafka 컨슈머 스레드 (trace 정보 보유)"] -->|적재 시점에 캡처| Channel["인메모리 채널 (작업 객체에 컨텍스트 동봉)"]
    Channel -->|꺼낼 때 복원| Worker["가상 스레드 Worker"]
    Worker -->|복원된 컨텍스트로| Pub["다음 hop 발행"]

2. 폴링 Worker (백그라운드 스케줄러)

• 서버 장애 시 폴링 Worker가 DB에서 미처리 건 회수
• 백그라운드 스케줄러 진입으로 원본 메시지의 trace 정보 부재
• 미조치 시 복구 작업이 부모 (parent trace) 없는 고립된 트레이스로 기록됨

수신함 데이터 삽입 시에 traceparent 문자열을 함께 저장하는 방식으로 해결했다.

• 회수 시점에 DB에서 식별자를 읽어 컨텍스트 복원
• 복원된 부모 트레이스 아래에 새로운 하위 작업 생성

---

결론

전환 비용과 트레이드오프

도메인 분리 작업 자체보다 정합성과 일관성 보장 장치를 재구축하는 데 더 많은 설계 고민과 구현 비용이 소요되었다.

• 트랜잭션 제어권 상실: 단일 JVM과 단일 DB가 기본 제공하던 원자적 상태 변경 불가
• 복잡성 증가: 분산 환경에 맞춘 새로운 상태 관리 메커니즘 설계 비용 발생

단일 시스템의 이점	분산 환경의 대안
원자적 상태 변경	Outbox 패턴 + 소비 측 멱등성 + 보상 경로
중복 없는 전달	at-least-once + 서비스마다 다른 멱등 구현
끊기지 않는 실행 흐름	traceparent 전파 + 스레드 경계 복원
즉시 드러나는 실패	격리 토픽 + 지표 + 알람 규칙

전환으로 얻은 이점

높은 복잡성 비용을 지불하여 얻은 핵심은 장애 격리와 의존성 통제다.

• 외부 장애 격리: 벤더사 응답 지연 발생 시 호출 자원을 pg-service에 한정하여 타 서비스의 커넥션 고갈 방지
• 비동기 장애 복구: 일시적 연동 실패 시 큐와 워커로 재시도하고 한계 도달 시 격리 토픽 (DLQ)으로 이관하여 유실 방지
• 생명주기 독립: 결제 로직과 무관한 외부 PG 스펙 및 상품 재고 정책의 배포 일정을 분리

실패를 전제한 설계

결제 시스템의 안정성은 단일 트랜잭션 의존을 벗어나 실패 지점을 격리하고 최종적 일관성을 맞추는 데 있다.

• 네트워크 단절 대비: 일시적 통신 실패 시 재시도와 보상 트랜잭션으로 상태 동기화
• 메시지 중복 도달 대비: 서비스별 특성에 맞춘 소비 측 멱등성 구현

Tags:

• Payment Platform Project

결제 복구 상태 모델 설계 — 장애 내성을 갖춘 상태 전이

2026. 4. 10. - Last update: 2026. 4. 11.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.4.4, MySQL 8.0

배경

최근 비동기 결제 처리 아키텍처를 도입하면서, 기존 상태 모델이 새 아키텍처를 충분히 표현하지 못하는 문제가 드러났다.

• 재시도 대상과 완전 실패 건의 구분이 모호하여 복구 대상을 정확히 추적의 어려움
• 고정 간격 재시도로 인해 PG 장애 시 부하가 집중 위험 가능

이 글에서는 이러한 상태 모델의 구조적 한계를 분석하고, 장애 내성을 갖춘 상태 전이 체계를 재설계한 과정을 다룬다.

** 비동기 결제 아키텍처 자체의 도입 배경과 구현은 이전 글에서 다루므로, 여기서는 상태 모델과 복구 로직에 집중한다.

비동기 결제 플로우 요약

본론에 앞서, 이 글의 전제가 되는 비동기 결제 구조를 간략히 정리한다.

1. 클라이언트의 결제 승인 요청(confirm)과 실제 PG(Payment Gateway, 결제 대행사) 승인 API 호출을 기술적으로 분리
2. 서버는 PG 응답을 기다리지 않고 즉시 202 Accepted를 반환
3. 실제 승인은 백그라운드에서 처리하며, 클라이언트는 승인 상태를 조회하여 최종 결과를 확인

sequenceDiagram
    participant C as 클라이언트
    participant S as 서버
    participant PG as PG사
    C ->> S: 결제 승인 요청
    S -->> C: 202 Accepted
    Note over S, PG: 백그라운드 처리
    S ->> PG: PG 승인 요청
    PG -->> S: 승인 결과
    C ->> S: 승인 상태 조회
    S -->> C: 최종 결과

이 구조에서 핵심이 되는 세 가지 개념이 있다.

• PaymentEvent: 결제 1건의 생명주기를 추적하는 도메인 엔티티
  • READY → IN_PROGRESS → DONE/FAILED 등 상태 전이를 관리
• PaymentOutbox: Outbox 패턴을 적용한 작업 큐 역할의 테이블
  • PENDING(대기) → IN_FLIGHT(처리 중) → DONE/FAILED(종결) 상태 전이를 관리
  • Outbox 패턴: 비동기로 처리할 작업을 같은 DB 트랜잭션(TX) 안에 기록하여, 서버가 중간에 죽더라도 처리 대상이 유실되지 않도록 보장하는 기법
• Worker: Outbox 레코드를 읽어 실제 PG 승인을 수행하는 백그라운드 처리기
  • 즉시 처리기(TX 커밋 직후 즉시 처리)와 폴링 복구기(주기적 폴링으로 누락 건 재처리) 두 트랙으로 구성

---

기존 설계의 한계

위 비동기 구조에서 기존 상태 모델에 네 가지 구조적 한계가 있었다.

한계 1 - 불명확한 UNKNOWN 상태와 분산된 스케줄러

기존 상태 머신의 IN_PROGRESS와 UNKNOWN 두 상태 모두 재시도 대상이었고, 실패가 반복되면 FAILED로 전이되었다.

stateDiagram-v2
    [*] --> READY: checkout 완료
    READY --> IN_PROGRESS: PG 승인 요청 수신
    READY --> EXPIRED: 만료 (30분)
    IN_PROGRESS --> DONE: PG 승인 성공
    IN_PROGRESS --> FAILED: 실패 (non-retryable 또는 재시도 소진)
    IN_PROGRESS --> UNKNOWN: 재시도 가능 에러 발생
    UNKNOWN --> DONE: 재시도 성공
    UNKNOWN --> FAILED: 재시도 소진
    UNKNOWN --> UNKNOWN: 재시도 계속

또한 여러 스케줄러가 돌아가고 있고, 이를 관리하는 복구 사이클이 분산되어 있었다.

한계 2 - 하드코딩된 재시도 정책 및 부하 집중 위험

재시도 한도가 PaymentEvent와 PaymentOutbox 양쪽에 RETRYABLE_LIMIT = 5로 중복 하드코딩되어 있었다.

• 고정된 폴링 간격마다 모든 건에 요청하면서 일시적 장애 시 PG에 부하 집중될 수 있음
• PaymentOutbox에 nextRetryAt 개념이 없어 고정 간격(FIXED) 이외의 Backoff 전략을 지원할 수 없음
• 한도를 변경하려면 두 클래스를 동시에 수정해야 하는 구조

한계 3 - 예외 기반 실패 분류의 이중 구조

도메인 결과값(PaymentConfirmResult)이 이미 실패 유형을 분류하고 있음에도, 예외 타입으로 변환하여 catch 블록에서 분기하는 이중 구조가 존재했다.

한계 4 - PG 상태 미조회와 무조건 재승인

복구 사이클이 PG 상태를 조회하지 않고 무조건 승인 요청을 재발행하는 구조였다.

• 멱등성 키(동일 요청을 여러 번 보내도 결과가 한 번만 적용되도록 보장하는 고유 키)로 중복 결제라는 심각한 문제는 방지
• 재승인 요청 직전 상태를 알 수 없는 구조

---

재설계

위 네 가지 한계를 해결하기 위해, 상태 모델 재정의 → 재시도 정책 도메인 객체화 → 복구 결정 로직 집중 → 동시성 안전장치 순서로 재설계를 진행했다.

솔루션	대응하는 한계
상태 모델 재정의	한계 1 - 불명확한 UNKNOWN, 분산 스케줄러
RetryPolicy	한계 2 - 하드코딩된 재시도 정책, 부하 집중
RecoveryDecision	한계 3, 4 - 실패 분류 이중 구조, PG 미조회
원자적 선점 / 재고 복구 가드	동시성 안전장치 (신규)

상태 모델 재정의 - RETRYING, QUARANTINED 도입과 UNKNOWN 제거

한계 1 해결: 불명확한 UNKNOWN 상태 제거, 분산 스케줄러 통합

기존 UNKNOWN 상태를 RETRYING으로 변경하여 “재시도 대기 중”이라는 의미를 명확히 부여하고, 한도 소진 시 복구 사이클에서 영구 이탈시키는 QUARANTINED(격리) 상태를 도입했다.

stateDiagram-v2
    classDef ready fill: #D6EAF8, color: #1B4F72, stroke: #2E86C1
    classDef inprogress fill: #FEF9E7, color: #7D6608, stroke: #F1C40F
    classDef retrying fill: #FEF5E7, color: #7E5109, stroke: #F39C12
    classDef done fill: #D5F5E3, color: #0E6251, stroke: #28B463
    classDef failed fill: #FADBD8, color: #7B241C, stroke: #E74C3C
    classDef quarantined fill: #F3E5F5, color: #4A148C, stroke: #7B1FA2
    [*] --> READY: checkout 완료
    READY --> IN_PROGRESS: PG 승인 요청 수신
    READY --> EXPIRED: 만료 (30분)
    IN_PROGRESS --> DONE: PG 승인 성공
    IN_PROGRESS --> FAILED: non-retryable 오류
    IN_PROGRESS --> RETRYING: retryable 오류 (첫 실패)
    IN_PROGRESS --> QUARANTINED: 판단 불가 + 한도 소진
    RETRYING --> DONE: 재시도 성공
    RETRYING --> FAILED: non-retryable 오류 또는 재시도 소진
    RETRYING --> RETRYING: 재시도 또 실패 (한도 내)
    RETRYING --> QUARANTINED: 판단 불가 + 한도 소진
    class READY ready
    class IN_PROGRESS inprogress
    class RETRYING retrying
    class DONE done
    class FAILED,EXPIRED failed
    class QUARANTINED quarantined

• UNKNOWN → RETRYING: “알 수 없는 상태”가 아니라 “재시도 대기 중”이라는 의미를 명확히 부여
• RETRYING → RETRYING: 한도 내에서 반복 실패 시 self-loop
• RETRYING → DONE / FAILED: 재시도 성공 또는 소진 시 종결
• IN_PROGRESS / RETRYING → QUARANTINED: 한도 소진 후에도 PG 상태를 판단할 수 없으면 격리 (관리자 개입 전까지 자동 복구 사이클에서 영구 이탈)
  • PG 측에서 이미 승인이 완료되었을 가능성 고려

이를 위해 기존 상태 전이 가드도 업데이트했다.

전이	기존 허용 source	변경 후 허용 source
승인 완료 전이	IN_PROGRESS, DONE	IN_PROGRESS, RETRYING, DONE
실패 처리 전이	READY, IN_PROGRESS	READY, IN_PROGRESS, RETRYING
재시도 전환	(신규)	READY, IN_PROGRESS, RETRYING
격리	(신규)	READY, IN_PROGRESS, RETRYING

RetryPolicy 도메인 객체 추가 및 nextRetryAt 필드 추가로 재시도 시점 제어

한계 2 해결: 하드코딩된 재시도 정책, 부하 집중 위험

중복 하드코딩된 재시도 한도를 RetryPolicy 도메인 객체로 분리했다.(설정은 application.yml로 외부화)

public record RetryPolicy(
        int maxAttempts,
        BackoffType backoffType,
        long baseDelayMs,
        long maxDelayMs
) {

    public boolean isExhausted(int retryCount) {
        return retryCount >= maxAttempts;
    }

    public Duration nextDelay(int retryCount) {
        return switch (backoffType) {
            case FIXED -> Duration.ofMillis(baseDelayMs);
            case EXPONENTIAL -> Duration.ofMillis(
                    Math.min(baseDelayMs * (1L << retryCount), maxDelayMs)
            );
        };
    }
}

• maxAttempts: 최대 재시도 횟수
• BackoffType: FIXED(고정 간격) 또는 EXPONENTIAL(지수 증가)
• baseDelayMs / maxDelayMs: Backoff 계산의 기본값과 상한

추가적으로 PaymentOutbox에 nextRetryAt 필드를 도입하여, 재시도 시점을 동적으로 제어할 수 있도록 했다.

RecoveryDecision 값 객체

한계 3, 4 해결: 예외 기반 실패 분류 → 도메인 결과값 기반, PG 상태 선행 조회 도입

기존의 예외 타입을 통한 실패 분류 대신, 복구 결정 로직을 순수 도메인 값 객체에 집중시켰다.

Decision	의미	판단 기준	후속 처리
COMPLETE_SUCCESS	PG 승인 완료	PG 조회 결과 = DONE	로컬 DONE 전이
COMPLETE_FAILURE	PG 종결 실패 (취소/중단/만료 등)	PG 조회 결과 = CANCELED/ABORTED/EXPIRED 등	보상 TX (재고 복원 + FAILED)
ATTEMPT_CONFIRM	PG에 기록 없음	PG 조회 결과 = NOT_FOUND	PG 승인 요청 후 결과 재평가
RETRY_LATER	PG 조회 오류 또는 진행 중 (한도 내)	PG 조회 실패(타임아웃/5xx) 또는 PG 처리 중 + 한도 미소진	RETRYING + nextRetryAt 설정
QUARANTINE	한도 소진 + 판단 불가	한도 소진 + PG 상태 판단 불가(타임아웃/매핑 불가)	QUARANTINED (자동 복구 이탈)
REJECT_REENTRY	로컬이 이미 종결 상태	로컬 PaymentEvent = DONE/FAILED/CANCELED 등	Outbox만 멱등 종결

RecoveryDecision decision = RecoveryDecision.decide(
        pgStatus,           // PG 상태 조회 결과
        localEventStatus,   // 로컬 PaymentEvent 상태
        retryCount,         // 현재까지 재시도 횟수
        retryPolicy         // RetryPolicy 설정
);

Spring 의존 없이 순수하게 테스트할 수 있으며, 모든 복구 분기가 한 곳에 집중된다.

원자적 선점

같은 건을 여러 Worker가 동시에 처리하는 것을 막기 위해, Outbox 상태를 PENDING(대기)에서 IN_FLIGHT(Worker가 선점하여 처리 중)로 원자적으로 전환하는 선점 메커니즘을 도입했다.

UPDATE payment_outbox
SET status       = 'IN_FLIGHT',
    in_flight_at = :now
WHERE order_id = :orderId
  AND status = 'PENDING'
  AND (next_retry_at IS NULL OR next_retry_at <= :now)

• WHERE 절에 status = 'PENDING' 조건이 포함되어 있으므로, 두 Worker가 동시에 같은 건을 선점하려 해도 하나만 UPDATE에 성공
• 실패한 Worker는 영향 행 수가 0이므로 즉시 포기하고, 성공한 Worker만 이후 복구 로직 진행

재고 복구 가드

보상 트랜잭션은 재고를 복원하는 되돌릴 수 없는 작업이므로, 실행 전에 데이터가 정상 상태인지 이중 조건 가드로 확인한다.

• 정상 흐름에서는 원자적 선점이 중복 진입을 원천 차단
• 비정상 데이터(타임아웃 복구 후 상태 불일치 등)가 보상 TX까지 도달했을 때 재고를 함부로 건드리지 않기 위한 안전망

flowchart TD
    classDef check fill: #FEF9E7, color: #7D6608, stroke: #F1C40F
    classDef skip fill: #F5F5F5, color: #616161, stroke: #9E9E9E
    classDef exec fill: #FADBD8, color: #7B241C, stroke: #E74C3C
    A["보상 트랜잭션 진입"] --> C{"1. 대기열이 처리 중인가?\n(현재 사이클에서 선점한 건)"}:::check
    C -- " NO " --> D["재고 복원 건너뜀\n대기열/결제 종결만 수행"]:::skip
    C -- " YES " --> E{"2. 결제가 아직 미종결인가?\n(아직 실패/완료 아닌 건)"}:::check
    E -- " NO " --> D
    E -- " YES " --> F["재고 복원 수행\n+ 대기열 → 실패\n+ 결제 → 실패"]:::exec

TX 시작 시점에 Outbox와 PaymentEvent를 DB에서 다시 조회하여, 두 조건 모두 충족할 때만 재고 복원을 실행한다.

• Outbox가 IN_FLIGHT가 아닌 경우: 다음 두 가지 경로로 이 상태에 도달
  • 다른 Worker가 복구를 먼저 완료하여 Outbox가 DONE 또는 FAILED로 전이된 경우
  • IN_FLIGHT 타임아웃 복구에 의해 Outbox가 PENDING으로 초기화된 뒤, 다른 Worker가 재선점하여 현재 Worker의 IN_FLIGHT가 무효화된 경우
  • 어느 쪽이든 현재 Worker의 선점이 유효하지 않으므로 재고 복원 skip
• PaymentEvent가 이미 종결 상태(DONE/FAILED/CANCELED 등)인 경우: 다른 경로에서 보상 TX가 이미 커밋되었으므로 재고 복원을 skip

격리 전 최종 확인

재시도 중 마지막 요청이 성공했을 수도 있으므로, 격리 직전에 PG 상태를 한 번 더 조회하여 최종 확인한다.

flowchart TD
    classDef success fill: #D5F5E3, color: #0E6251, stroke: #28B463
    classDef failure fill: #FADBD8, color: #7B241C, stroke: #E74C3C
    classDef quarantine fill: #F3E5F5, color: #4A148C, stroke: #7B1FA2
    classDef action fill: #EBF5FB, color: #21618C, stroke: #3498DB
    A["한도 소진 시점"] --> B["PG 상태 1회 최종 재확인"]:::action
    B -->|" 승인 완료 "| C["성공 확정 (승격)"]:::success
    B -->|" PG 종결 실패\n(취소/중단/만료 등) "| D["실패 확정 (재고 복원)"]:::failure
    B -->|" PG 기록 없음/타임아웃/매핑 불가\n(판단 불가) "| F["격리 (관리자 개입 대기)"]:::quarantine

---

복구 처리기 구성

시나리오에 앞서, 복구 처리를 담당하는 세 구성 요소의 역할을 정리한다.

구성 요소	트리거	역할
즉시 처리기	채널 수신 즉시	PG 승인 요청 직후 Outbox에 발행된 건을 즉시 처리
폴링 복구기	5초 주기 폴링	IN_FLIGHT 타임아웃 복구 / PENDING 건 배치 조회 후 복구 처리 위임
만료 스케줄러	5분 주기	30분 이상 READY 상태인 만료 건을 EXPIRED로 전이

폴링 복구기는 매 틱마다 두 단계를 순서대로 수행한다.

1. IN_FLIGHT 상태가 일정 시간(기본 5분) 이상 지속된 건을 PENDING으로 복구: Worker가 처리 중 비정상 종료하거나 응답이 느려진 경우를 대비한 안전장치
   • 5분은 PG 승인 API의 최대 응답 시간(통상 수십 초)에 충분한 여유를 두되, 복구 지연이 과도하게 길어지지 않도록 설정한 값으로 설정
2. PENDING 건을 배치 조회하고, 각 건에 대해 PENDING → IN_FLIGHT 원자적 선점 후 복구 처리 시작

타임아웃 복구와 배치 조회를 별도 단계로 분리한 이유

한 쿼리로 합치면 “정상 처리 중인 IN_FLIGHT”와 “죽은 IN_FLIGHT”를 구분할 수 없기 때문이다.

• 먼저 시간 기준으로 죽은 건만 PENDING으로 확정
• 이후 원자적 선점이 PENDING → IN_FLIGHT 단일 전이만 경쟁하도록 하여 선점 보장을 단순하게 유지

---

엣지 케이스 검증

위 설계가 실제 장애 상황을 어떻게 방어하는지, 구체적인 시나리오로 확인한다.

1. PG 승인 완료인데 로컬이 모르는 경우

서버가 PG 승인 응답을 받은 직후, DB에 반영하기 전에 죽는 상황이다.

sequenceDiagram
    participant S as 서버
    participant DB as DB
    participant PG as PG사
    S ->> PG: PG 승인 요청
    PG -->> S: 승인 완료
    Note over S: 서버 장애 발생 (DB 커밋 전)
    Note over DB: 결제 = 진행 중, 대기열 = 처리 중
    Note over S: 5분 후 타임아웃 복구 → 대기
    S ->> PG: PG 상태 조회
    PG -->> S: 승인 완료
    S ->> DB: [TX] 결제 완료 + 대기열 종결

PG 상태를 먼저 조회함으로써 승인 재요청 없이 로컬에 바로 동기화하게 된다.

2. Worker 타임아웃으로 동시 처리 발생

W1이 처리 중 느려져서 타임아웃이 발생하고, W2가 같은 건을 다시 선점하는 상황이다.

sequenceDiagram
    participant W1 as 워커 1 (느림)
    participant DB as DB
    participant W2 as 워커 2
    participant PG as PG사
    W1 ->> DB: 원자적 선점 (대기 → 처리 중)
    Note over W1: 처리 지연...
    Note over DB: 타임아웃 복구
    DB ->> DB: 대기열 → 대기 복원
    W2 ->> DB: 원자적 재선점 (대기 → 처리 중)
    W2 ->> PG: PG 상태 조회
    PG -->> W2: 취소됨 (PG 종결 실패)
    W2 ->> DB: [보상 TX] 재고 복원 + 결제 실패 + 대기열 실패
    Note over W1: 뒤늦게 보상 TX 시도
    W1 ->> DB: [보상 TX] 가드 검사
    Note over DB: 대기열 = 실패 (처리 중 아님) → 가드 차단
    W1 ->> DB: 재고 복원 건너뜀

W2가 먼저 보상 TX를 커밋한 뒤, W1이 뒤늦게 같은 건에 보상 TX를 시도했지만, 재고 복구 가드가 “Outbox가 IN_FLIGHT가 아님”을 감지하여 재고 이중 복원을 차단한다.

• Worker가 IN_FLIGHT 타임아웃(5분)을 초과하는 현실적인 시나리오
  • Worker 스레드 혹은 프로세스가 비정상 종료(OOM, 예기치 않은 예외 등)되어 응답 자체를 반환하지 못하는 경우를 가정
  • IN_FLIGHT 타임아웃은 이처럼 Worker가 처리 도중 사라진 건을 복구하기 위한 안전장치

3. 한도 소진 직전 PG 승인 완료

4번째 재시도까지 타임아웃이 반복되다가, 5번째(마지막) 시도 직전에 PG가 승인을 완료한 경우다.

sequenceDiagram
    participant W as 워커
    participant DB as DB
    participant PG as PG사
    Note over DB: 결제 = 재시도 중 (4회 실패)
    Note over DB: 대기열 = 대기 (재시도 시점 도달)
    W ->> DB: 원자적 선점
    W ->> PG: PG 상태 조회
    PG -->> W: 타임아웃 (5번째 실패)
    Note over W: 한도 소진 → 격리 전 최종 확인
    W ->> PG: PG 상태 1회 최종 재확인
    PG -->> W: 승인 완료
    W ->> DB: [TX] 결제 완료 + 대기열 종결

이 확인이 없었다면 5회 소진 시점에 QUARANTINED 또는 FAILED로 처리되어, 이미 승인된 결제의 재고가 복원될 수 있었지만, 마지막 getStatus 조회가 성공으로 승격시켜준다.

---

최종 상태 다이어그램

모든 개선을 반영한 PaymentEventStatus의 최종 상태 전이는 다음과 같다.

stateDiagram-v2
    classDef ready fill: #D6EAF8, color: #1B4F72, stroke: #2E86C1
    classDef inprogress fill: #FEF9E7, color: #7D6608, stroke: #F1C40F
    classDef retrying fill: #FEF5E7, color: #7E5109, stroke: #F39C12
    classDef done fill: #D5F5E3, color: #0E6251, stroke: #28B463
    classDef failed fill: #FADBD8, color: #7B241C, stroke: #E74C3C
    classDef quarantined fill: #F3E5F5, color: #4A148C, stroke: #7B1FA2
    [*] --> READY: checkout 완료
    READY --> IN_PROGRESS: PG 승인 요청 수신
    READY --> EXPIRED: 만료 (30분)
    READY --> RETRYING: 복구 사이클 재진입
    IN_PROGRESS --> DONE: PG 승인 성공
    IN_PROGRESS --> FAILED: non-retryable 오류
    IN_PROGRESS --> RETRYING: retryable 오류
    IN_PROGRESS --> QUARANTINED: 한도 소진 + 판단 불가
    RETRYING --> DONE: 재시도 성공
    RETRYING --> FAILED: non-retryable 또는 한도 소진 + 확정 실패
    RETRYING --> RETRYING: 한도 내 재시도
    RETRYING --> QUARANTINED: 한도 소진 + 판단 불가
    class READY ready
    class IN_PROGRESS inprogress
    class RETRYING retrying
    class DONE done
    class FAILED,EXPIRED failed
    class QUARANTINED quarantined

복구 사이클 전체 플로우

복구 사이클의 최종 구조를 플로우차트로 정리하면 다음과 같다.

• 원자적 선점 성공 → 로컬 종결 여부 확인 → PG 상태 선행 조회 순서로 진입
• PG 조회 결과에 따라 즉시 종결(DONE/FAILED), 재시도(RETRY_LATER), 승인 요청(ATTEMPT_CONFIRM) 중 하나로 분기
• 한도를 소진하면 격리 전 최종 확인을 거쳐 QUARANTINE 또는 종결로 분기
• 보상 TX 실행 전에는 항상 재고 복구 가드가 이중 조건을 검증

flowchart TD
    classDef success fill: #D5F5E3, color: #0E6251, stroke: #28B463
    classDef retryable fill: #FEF5E7, color: #7E5109, stroke: #F39C12
    classDef failure fill: #FADBD8, color: #7B241C, stroke: #E74C3C
    classDef quarantine fill: #F3E5F5, color: #4A148C, stroke: #7B1FA2
    classDef action fill: #EBF5FB, color: #21618C, stroke: #3498DB
    classDef check fill: #FEF9E7, color: #7D6608, stroke: #F1C40F
    classDef skip fill: #F5F5F5, color: #616161, stroke: #9E9E9E
    A["복구 틱"] --> CL["원자적 선점\n대기 → 처리 중"]:::action
    CL -->|" 선점 실패 "| SKIP["다른 워커가 처리 중 → 포기"]:::skip
    CL -->|" 선점 성공 "| LC{"결제 종결 여부 검사\n완료/실패/취소 등"}:::check
    LC -->|" 이미 종결\n(완료/실패/취소 등) "| REENTRY["재진입 거부\n대기열만 멱등 종결"]:::skip
    LC -->|" 비종결\n(대기/진행 중/재시도 중) "| GS["PG 상태 선행 조회"]:::action
    GS -->|" 승인 완료 "| SUCCESS["성공 확정"]:::success
    GS -->|" 취소/중단/만료 등\nPG 종결 실패 "| FAILURE["실패 확정"]:::failure
    GS -->|" PG 기록 없음 "| CONFIRM["PG 승인 요청"]:::action
    GS -->|" 타임아웃/5xx/매핑 불가\n+ 한도 미소진 "| RETRY["재시도 대기"]:::retryable
    SUCCESS --> TX_DONE["결제 완료\n대기열 종결"]:::success
    FAILURE --> GUARD{"재고 복구 가드\n대기열 처리 중?\n결제 비종결?"}:::check
    CONFIRM --> CF["PG 승인 요청"]:::action
    RETRY --> TX_RETRY["결제 → 재시도 중\n재시도 시점 설정\n대기열 → 대기"]:::retryable
    CF -->|" 승인 성공 "| TX_DONE
    CF -->|" 재시도 가능 + 한도 미소진 "| TX_RETRY
    CF -->|" 재시도 불가 "| GUARD
    CF -->|" 재시도 가능 + 한도 소진 "| FINAL
    TX_RETRY -->|" 한도 소진 "| FINAL
    FINAL["격리 전 최종 확인\nPG 상태 1회 재확인"]:::action
    FINAL -->|" 승인 완료 확인 "| TX_DONE
    FINAL -->|" PG 종결 실패 "| GUARD
    FINAL -->|" 판단 불가 "| QU["격리\n결제 → 격리 상태\n대기열 → 실패\n재고 복원 금지"]:::quarantine
    GUARD -->|" 조건 충족 "| TX_COMP["보상 트랜잭션 실행\n재고 복원\n결제 → 실패\n대기열 → 실패"]:::failure
    GUARD -->|" 조건 미충족 "| TX_SKIP["대기열 → 실패만\n재고 복원 건너뜀"]:::skip

---

마무리

상태 모델을 재정의하고 복구 결정 로직을 도메인 값 객체에 집중시킨 결과, 복구 사이클이 대응하는 전체 케이스를 다음과 같이 정리할 수 있다.

복구 사이클 내 케이스

복구 사이클은 PG 상태 조회 결과를 기준으로 종결 / 재시도 / 격리 중 하나를 결정하여 처리한다.

상황	Event	Outbox	재고
PG에서 승인이 정상 완료된 경우	→ DONE	→ DONE	점유 유지
PG에서 결제가 취소/중단/만료된 경우	→ FAILED	→ FAILED	복원
PG에 결제 기록 자체가 없는 경우	승인 결과에 따라 결정	승인 결과에 따라 결정	점유 유지
PG 조회가 일시적으로 실패한 경우 (한도 내)	→ RETRYING	→ PENDING (nextRetryAt)	점유 유지
PG에서 아직 처리 중인 경우 (한도 내)	→ RETRYING	→ PENDING (nextRetryAt)	점유 유지
위 재시도 케이스에서 한도를 소진한 경우	격리 전 최종 확인 결과에 따라 결정	격리 전 최종 확인 결과에 따라 결정	결과에 따라 결정
이미 로컬에서 종결 처리가 완료된 경우	변경 없음	→ DONE	변경 없음

스케줄러 및 선점

복구 사이클 뿐만 아니라, 동시성과 장애 상황에 대응하는 스케줄러와 선점 구조도 다음과 같이 정리할 수 있다.

상황	Event	Outbox	재고
Worker가 느려져서 다른 Worker가 먼저 처리를 완료한 경우	변경 없음	변경 없음	가드가 이중 복원 차단
Worker가 비정상 종료하여 처리가 중단된 경우	변경 없음	→ PENDING	점유 유지
다른 Worker가 이미 선점한 경우	변경 없음	변경 없음	변경 없음

Tags:

• Payment Platform Project

비동기 결제 처리 플로우 구현 — Outbox 패턴부터 LinkedBlockingQueue Worker까지

2026. 3. 31. - Last update: 2026. 4. 11.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.4.4, MySQL 8.0, k6

배경

지금까지 Payment Platform 시리즈에서 결제 시스템을 단계별로 개선해왔다.

• 토스 결제 연동: 결제 위젯과 서버 검증 연동
• 트랜잭션 범위 최소화: 외부 API를 트랜잭션 밖으로 분리
• 결제 복구 시스템: UNKNOWN 상태와 재시도 로직으로 장애 복구
• 보상 트랜잭션 실패 대응: 작업 테이블로 최종적 일관성 확보
• PG 독립 아키텍처: 전략 패턴으로 PG 교체 가능 구조
• 결제 이력 추적: 상태 변경 이력과 운영 지표 모니터링
• Checkout 멱등성: 중복 결제 이벤트 생성 방지

이전 트랜잭션 범위 최소화에서 외부 API 호출을 트랜잭션 밖으로 분리했지만, confirm 단계의 HTTP 스레드 점유 문제는 여전히 남아 있었다.

1. 외부 API 응답이 지연 시 그 시간만큼 Tomcat 스레드가 묶임
2. 요청이 몰리면서 스레드 풀 고갈

이 글은 그 문제를 비동기로 풀어보려 한 시도, 그리고 그 과정에서 마주친 실패와 재설계를 기록한다.

• Kafka 같은 외부 메시지 브로커나 WebFlux 기반 리액티브 전환 X
• 애플리케이션 내부 구조만으로 해결하는 방법에 집중

---

비동기 결제의 정의

본 포스팅에서 다루는 비동기 결제는 클라이언트의 결제 승인 요청(Confirm)과 실제 외부 PG사 승인 API 호출 프로세스를 기술적으로 분리하는 방식을 의미한다.

• 핵심 메커니즘: 서버가 PG사의 승인 응답을 대기하지 않고 요청 접수 후 즉시 202 Accepted 응답을 반환
• 처리 방식: 실제 승인 처리는 백그라운드 워커가 전담하여 수행
• 도입 목적: 외부 API 지연이 내부 HTTP 스레드 고갈로 전파되는 현상을 차단하여 시스템 가용성 확보

결제 프로세스의 특정 구간을 비동기로 전환함으로써, 클라이언트는 빠른 응답을 받고 서버는 한정된 자원을 효율적으로 관리할 수 있게 된다.

---

전체 결제 플로우

비동기 플로우를 이해하려면 먼저 전체 결제 흐름을 파악해야 한다.

sequenceDiagram
    participant Client as 클라이언트
    participant Server as 서버
    participant DB as DB
    participant PG as PG사
    Client ->> Server: 주문 생성 요청
    Server ->> DB: 결제 대기 생성
    Server -->> Client: 201 Created (주문 정보)
    Client ->> PG: 결제 위젯 — 카드 정보 입력 및 인증
    PG -->> Client: 인증 완료
    Client ->> Server: 결제 승인 요청
    Server ->> DB: 결제 진행 중 전환 + 처리 대기열 등록
    Server ->> PG: PG 승인 요청
    Note over Server: 이 단계가 핵심 개선 대상
    PG -->> Server: 승인 결과 (완료)
    Server ->> DB: 결제 완료 + 대기열 종결
    Server -->> Client: 200 OK / 202 Accepted

• 결제 플로우는 checkout → 인증 → confirm 세 단계
• confirm 단계는 서버 로직 내에서 직접 호출하면서 승인 완료하는 구조

승인 API 응답 시간은 외부 서비스에 달려 있고, 네트워크 지연 상황이 발생한다면 동기 방식에서 이 지연은 HTTP 스레드가 그대로 묶이게 된다.

---

실험 환경 및 핵심 용어 정의

본문에서 진행하는 벤치마크는 더욱 입체적인 분석을 위해 k6 상에서 두 가지 시나리오를 동시(Concurrent)에 실행하도록 구성되었다.

1. 테스트 환경의 두 가지 시나리오

• Open System 시나리오 (TPS 측정용): 초당 요청 발생률(Arrival Rate)을 고정하여 시스템의 최대 처리 용량을 확인하는 방식
  • 특징: 이전 요청의 완료 여부와 상관없이 설정된 속도대로 새로운 요청을 지속적으로 생성
  • 동기 방식 측정: /confirm 요청 후 200 OK를 받을 때까지 대기
  • 비동기 방식 측정: /confirm 요청 후 202 Accepted 응답을 수신 시 (순수하게 서버의 HTTP 수용 능력을 측정)
• Closed System 시나리오 (E2E Latency 측정용): 일정한 가상 사용자(VU)가 요청을 보내고 응답을 받은 뒤 다음 요청을 보내는 방식
  • 특징: 시스템 내의 동시 사용자 수를 일정하게 유지하며 개별 사용자의 체감 성능을 측정
  • 비동기 환경 테스트 시 이 시나리오에서는 결제가 단순 202 수신으로 끝내지 않음
  • 실제 상태가 DONE이 될 때까지 GET /payments/{orderId} API를 지속적으로 폴링(Polling)하며 대기 후 측정

2. 핵심 지표 정의 (TPS vs E2E Latency)

• TPS (Transactions Per Second): Open System 시나리오에서 성공적으로 처리한 초당 HTTP 응답 건 수
  • 비동기 환경에서는 서버가 클라이언트 요청을 거절하지 않고 인메모리 큐에 적재하여 ‘202 수락’ 처리를 완료한 초당 건수 의미
• 결제 완료 시간 (E2E Latency): Closed System 시나리오에서 수집된 지표
  • 최초 /confirm부터 최종적으로 DONE 상태를 받아볼 때까지 폴링에 소모된 모든 대기 시간과 네트워크 오버헤드를 완전히 포함한 물리적(체감) 소요 시간

3. 지연 환경 (Latency Environment)

결제 승인(Confirm) 시 호출하는 PG API(Toss Payments)의 특성에 맞추어 두 가지 시나리오로 나누어 테스트했다.

• 저지연(Low Latency): API 승인 응답이 100~300ms 내외로 즉시 반환되는 쾌적한 평상시 환경
• 고지연(High Latency): 트래픽 스파이크 또는 외부 시스템(카드/VAN사) 장애로 승인 응답이 2,000~3,500ms로 극심하게 지연되는 환경

---

동기 방식의 한계

동기 confirm 플로우를 시각화하면 다음과 같다.

sequenceDiagram
    participant Client as 클라이언트 (k6 VU)
    participant Tomcat as Tomcat 스레드 풀
    participant PG as PG API (2~3.5s 지연)
    Client ->> Tomcat: 결제 승인 요청 (VU 1)
    Tomcat ->> PG: PG 승인 요청 [스레드 점유 시작]
    Client ->> Tomcat: 결제 승인 요청 (VU 2)
    Tomcat ->> PG: PG 승인 요청 [스레드 점유]
    Note over Tomcat: ...스레드 200개 모두 점유...
    Client ->> Tomcat: 결제 승인 요청 (VU N)
    Note over Tomcat: ⚠️ 스레드 고갈 — 요청 대기 또는 거절
    PG -->> Tomcat: 응답 반환 (2~3.5초 후)
    Tomcat -->> Client: 200 OK

• Tomcat 기본 스레드 풀은 200개
• Toss API 평균 응답이 2.75초 가정
  • 스레드 하나가 2.75초씩 묶임 → 동시 처리 가능한 요청 수가 스레드 수에 영향

100 req/s 목표에서 TPS는 53에 그치고, Confirm(결제 승인 요청) p95는 36초에 달했다.

케이스	TPS	API 응답 med	API 응답 p95	부하 미수용
sync-high (2~3.5s 지연)	53.0	10,199ms	36,079ms	6,575

부하 미수용 (k6 dropped iterations): ramping-arrival-rate 모드에서 가용 VU가 없어 발사 트리거가 잘린 가상 요청 수. HTTP 스레드 점유로 직전 요청이 회수되지 않으면 다음 요청 슬롯이 누락되어 누적된다.

1. 100 req/s가 들어오면 1초 동안 100개의 스레드가 Toss API 대기 상태 진입 후 각 스레드가 평균 2.75초를 점유
2. 2~3초 뒤에는 동시에 200개 이상의 요청이 스레드를 점유하게 되어, Tomcat 스레드 풀(200개) 포화
3. 이 시점 이후 도착하는 요청은 빈 스레드가 생길 때까지 대기하거나 거절

---

Async + Outbox 패턴 도입

해결책은 confirm 요청이 들어오면 Toss API 호출 없이 즉시 202를 반환하고, 백그라운드에서 실제 승인을 처리하는 구조다.

• @Async로 비동기 시 인메모리 이벤트 한계로 서버 재시작이나 처리 실패 시 이벤트가 유실될 위험 존재
• 결제 데이터는 한 건도 빠져서는 안 되므로, DB에 PENDING 레코드를 남겨 안전망을 확보하는 Outbox 패턴 함께 도입

graph TB
%% 클래스 정의 (가독성 및 테마 대응 규칙 적용)
    classDef main fill: #E1F5FF,stroke: #0078D4,color: #000
    classDef pending fill: #FFF2CC,stroke: #D79B00,color: #000
    classDef success fill: #E8F5E9,stroke: #2E7D32,color: #000
    classDef external fill: #F5F5F5,stroke: #333,color: #000
    classDef recovery fill: #FADAD8,stroke: #B85450,color: #000
    classDef note fill: #FFFFFF,stroke: #333,color: #000

    subgraph SyncPath ["결제 승인 핵심 경로 — 단일 TX"]
        direction TB
        A["결제 승인 요청"]:::external --> B["결제 진행 중 전환"]:::main
        B --> C["처리 대기열 등록"]:::pending
        C --> D["커밋 후 이벤트 발행"]:::main
        D --> E["202 Accepted 즉시 반환"]:::note
    end

    subgraph Polling ["클라이언트 상태 폴링"]
        direction TB
        P1["결제 상태 조회"]:::external --> P2{"결제 상태 확인"}:::pending
        P2 -- " 진행 중 " --> P3["일정 시간 대기"]:::note
        P3 -.->|재조회| P1
        P2 -- " 완료 " --> P4["최종 결제 완료 처리"]:::success
    end

    subgraph Background ["백그라운드 처리"]
        direction TB
        F["커밋 후 이벤트 수신"]:::main --> G["PG 승인 요청"]:::external
        G --> H["결제 완료"]:::success
        H --> I["대기열 종결"]:::success
    %% 폴백 및 복구 로직
        J["폴링 복구기 (주기 폴백)"]:::recovery --> K["미처리 건 배치 조회"]:::pending
        K --> G
    end

%% 컴포넌트 간 연결 로직
    E -->|" 202 응답 후 폴링 시작 "| P1
    D -.->|" 커밋 후 이벤트 전달 "| F
    C -.->|" 서버 장애 시 미처리분 복구 "| J

Outbox 패턴은 두 가지 처리 경로를 만든다.

• Fast Path: TX 커밋 직후 ApplicationEvent가 발행되어 즉시 처리
• Safety Track: OutboxWorker가 주기적으로 PENDING 레코드를 폴링하여 누락 건 처리

OutboxWorker(폴링)가 안전망 역할을 맡기 때문에, Fast Path가 실패해도 결제 데이터는 유실되지 않고, PENDING 레코드가 DB에 남아 있는 한 최종 처리가 보장된다.

---

1차 구현 - @Async + 동시 실행 제한 없음

Fast Path의 첫 번째 구현은 @Async와 @TransactionalEventListener의 조합이었다.

// OutboxImmediateEventHandler.java (1차)
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
@Async
public void handle(PaymentConfirmEvent event) {
    outboxProcessingService.process(event.getOrderId());
}

• @TransactionalEventListener(AFTER_COMMIT)은 TX가 커밋된 이후에만 이벤트를 처리해, 미커밋 PENDING 레코드를 Worker가 조회하는 경쟁 조건을 방지
• @Async는 처리를 별도 스레드로 위임해 HTTP 스레드 해제

첫 구현에는 동시 실행 제한(concurrencyLimit)은 설정하지 않고 진행했다.

HikariCP 커넥션 풀 고갈

제한 없이 벤치마크를 돌리자 정상 처리가 불가능한 상태에 빠졌다.

graph TD
%% 클래스 정의 (가독성 및 장애 단계 구분)
    classDef main fill: #E1F5FF,stroke: #0078D4,color: #000
    classDef pending fill: #FFF2CC,stroke: #D79B00,color: #000
    classDef external fill: #F5F5F5,stroke: #333,color: #000
    classDef recovery fill: #FADAD8,stroke: #B85450,color: #000
    A["결제 승인 요청"]:::external --> B["비동기 핸들러 동시 실행"]:::main
    B --> C["각 처리기: DB 커넥션 점유"]:::main
%% 장애 가속 구간
    C --> D["DB 커넥션 풀 한계 도달"]:::pending
    D --> E["신규 승인 요청도 DB 커넥션 대기"]:::pending
%% 최종 장애 상태
    E --> F["에러율 80%, TPS ≈ 0<br/>(시스템 장애)"]:::recovery
%% 위험 흐름 강조
    linkStyle 2,3,4 stroke: #FF3333,stroke-width: 2px

원인은 Backpressure(생산 속도가 소비 속도를 초과할 때 생산을 억제하는 메커니즘) 부재였다.

1. 202를 빠르게 반환하는 만큼 ImmediateHandler 동시 실행 수가 폭발적으로 증가
2. 각 핸들러가 Toss API 호출 중 DB 커넥션을 점유하면서 HikariCP 고갈
3. 커넥션이 바닥나면서 confirm 요청 TX 자체도 커넥션을 확보하지 못해 연쇄 실패

HTTP 스레드가 빠르게 이벤트를 쏟아내는 반면 Toss API 호출이 느려 소비가 따라가지 못하면서, 동시 실행 수를 제한하지 않은 구조에서 공유 자원(DB 커넥션)이 순식간에 바닥난 것이다.

---

2차 구현 - setConcurrencyLimit 추가

HikariCP 고갈을 막기 위해 SimpleAsyncTaskExecutor에 동시 실행 상한을 설정했다.

// AsyncConfig.java (2차)
@Bean
public AsyncTaskExecutor immediateHandlerExecutor(
        @Value("${outbox.immediate.concurrency-limit:200}") int concurrencyLimit,
        @Value("${outbox.immediate.virtual-threads:true}") boolean virtualThreadsEnabled) {
    SimpleAsyncTaskExecutor executor = new SimpleAsyncTaskExecutor("outbox-immediate-");
    executor.setVirtualThreads(true);
    executor.setConcurrencyLimit(concurrencyLimit);  // N = 10, 50, 100, 200, 250으로 실험
    return executor;
}

N(동시 실행 상한)을 다양하게 바꿔가며 벤치마크를 돌렸을 때, 예상과 다른 결과가 나왔다.

케이스	TPS	부하 미수용
동시 제한 10 / 저지연	8.1	11,022
동시 제한 100 / 저지연	23.8	10,472
동시 제한 200 / 저지연	26.7	10,096
동시 제한 200 / 고지연	24.0	10,434

동시 제한을 걸었을 때 부하 미수용이 폭발적으로 늘어나면서, 비동기로 전환했는데 기대한 성능이 나오지 않는 상황이 발생했다.

원인 분석 - ConcurrencyThrottleSupport

SimpleAsyncTaskExecutor는 ConcurrencyThrottleSupport를 상속하며, setConcurrencyLimit(N)을 설정하면 내부에서 다음 로직이 실행된다.

// Spring ConcurrencyThrottleSupport 내부 (Spring Framework 6.2.x)
private final Lock concurrencyLock = new ReentrantLock();
private final Condition concurrencyCondition = this.concurrencyLock.newCondition();

protected void beforeAccess() {
    if (this.concurrencyLimit > 0) {
        this.concurrencyLock.lock();
        try {
            while (this.concurrencyCount >= this.concurrencyLimit) {
                this.concurrencyCondition.await();  // ← 호출 스레드가 여기서 블로킹
            }
            this.concurrencyCount++;
        } finally {
            this.concurrencyLock.unlock();
        }
    }
}

슬롯이 없으면 호출 스레드 자체를 await()으로 블로킹하여, 큐에 적재하고 즉시 반환하는 것이 아니라, 빈 슬롯이 생길 때까지 호출자를 직접 잠그는 방식으로 동작한다.

sequenceDiagram
    participant HTTP as HTTP 스레드
    participant AFTER_COMMIT as AFTER_COMMIT 훅
    participant Executor as 비동기 실행기
    participant Worker as 처리 슬롯 N개
    HTTP ->> Hook: 커밋 후 이벤트 핸들러 실행
    Hook ->> Executor: 작업 위임 요청
    Note over Executor: 슬롯 N개 모두 점유 중
    Executor ->> HTTP: 빈 슬롯 대기 — 블로킹!
    Note over HTTP: HTTP 응답을 보내지 못한 채 대기
    Worker -->> Executor: 슬롯 반환
    Executor ->> HTTP: 대기 해제
    HTTP -->> Hook: 완료
    HTTP -->> HTTP: 202 응답 전송 (수백~수천 ms 지연)

• executor.execute(task)를 호출한 쪽, 즉 AFTER_COMMIT 훅을 실행 중인 HTTP 플랫폼 스레드 블로킹
• Tomcat의 HTTP 스레드(플랫폼 스레드, max=200)가 슬롯 대기에 묶이므로, Executor 내부에서 가상 스레드를 사용하더라도 HTTP 응답 지연 문제 발생

클라이언트 입장에서는 confirm 요청을 보낸 후 응답을 받지 못한 채 대기하게 되고, 요청 적체 → 처리 불가 요청 폭발로 이어진다.

요약 - 1차/2차 구현의 문제점

구현	문제
제한 없음 (1차)	Backpressure 부재 → HikariCP 고갈 → 에러율 80%
setConcurrencyLimit(N) (2차)	호출 스레드 직접 블로킹 → HTTP 응답 지연 → 부하 미수용 폭증

N(동시 처리 수)을 아무리 키워도 구조적 한계가 있었으며, 고지연 환경에서는 동시에 처리해야 할 요청 수가 N을 쉽게 넘어서고, N을 무한히 키우면 1차와 같은 자원 고갈이 재현된다.

---

최종 해결 - LinkedBlockingQueue + Worker 가상 스레드

문제는 작업을 위임하는 과정에서 HTTP 스레드가 자유롭지 못하다는 것이다.

• 1차: 동시 실행 수를 제한하지 않아 DB 커넥션이 고갈
• 2차: 동시 실행 수를 제한하자 슬롯 대기가 HTTP 스레드를 묶음

이 전제를 깨기 위해, AFTER_COMMIT 훅이 하는 일을 극도로 가볍게 만들어 큐에 넣는 방식으로 재설계하는 방향을 탐색했다.

핵심 아이디어

API 요청을 받은 HTTP 톰캣 스레드는 이벤트를 큐에 넣은 후 즉시 결과를 반환하고, 별도 Worker 가상 스레드들이 큐에서 이벤트를 꺼내 처리한다.

Before: HTTP 스레드 → execute(task) → await() → [블로킹] → 응답 지연
After:  HTTP 스레드 → queue.offer(orderId) → [즉시 반환] → 202 응답
                                ↓
                         Worker VT-1 → queue.take() → Toss API → markDone()
                         Worker VT-2 → queue.take() → Toss API → markDone()
                         Worker VT-N → queue.take() → (큐 Empty → 대기)

아키텍처

graph TB
%% 클래스 정의 (역할별 색상 구분 및 가독성 확보)
    classDef http fill: #E1F5FF,stroke: #0078D4,color: #000
    classDef queue fill: #FFF2CC,stroke: #D79B00,color: #000
    classDef worker fill: #E8F5E9,stroke: #2E7D32,color: #000
    classDef fallback fill: #FADAD8,stroke: #B85450,color: #000
    classDef external fill: #F5F5F5,stroke: #333,color: #000
    classDef response fill: #FFFFFF,stroke: #333,color: #000

    subgraph SyncPath ["HTTP 경로 — 빠른 반환"]
        direction TB
        A["결제 승인 요청"]:::external --> B["결제 승인 처리 (단일 TX)"]:::http
        B --> C["처리 대기열 등록"]:::queue
        C --> D["커밋 후 이벤트 발행"]:::http
        D --> E["커밋 후 이벤트 핸들러"]:::http
        E --> F["처리 큐에 등록<br/>(비블로킹)"]:::http
        F --> G["202 Accepted (즉시)"]:::response
    end

    subgraph Channel ["처리 큐 (인메모리 버퍼)"]
        H["처리 큐"]:::queue
        F --> H
    end

    subgraph WorkerPath ["워커 경로 — 비동기 처리 (가상 스레드)"]
        direction TB
        I["실시간 워커"]:::worker
        I --> J["워커 1: 큐에서 수신"]:::worker
        I --> K["워커 2: 큐에서 수신"]:::worker
        I --> L["워커 N: 큐에서 수신"]:::worker
        J --> M["결제 복구 처리"]:::worker
        K --> M
        L --> M
        M --> N["PG 승인 요청 + 결제 완료 처리"]:::external
    end

    subgraph FallbackPath ["폴백 경로 (배치 복구)"]
        O["폴링 복구기"]:::fallback
        O --> P["미처리 건 배치 조회 → 복구 처리"]:::queue
        P --> M
    end

%% 컴포넌트 간 상호작용
    G -->|" 202 응답 후 폴링 시작 "| CP1["결제 상태 조회"]:::external
    H --> J
    H --> K
    H --> L
    C -.->|" 큐 오버플로우 시 대기 유지 "| O
%% 연결선 스타일
    linkStyle 13,14,15 stroke: #333,stroke-width: 2px
    linkStyle 16 stroke: #FF3333,stroke-dasharray: 5 5

PaymentConfirmChannel

public class PaymentConfirmChannel {

    private final LinkedBlockingQueue<String> queue;

    public boolean offer(String orderId) {
        return queue.offer(orderId);  // 비차단: 큐 가득 차면 false 즉시 반환
    }

    // ...
}

offer()는 큐가 가득 찼을 때 false를 반환하면서, HTTP 스레드는 블로킹되지 않게 된다.

OutboxImmediateEventHandler — 단순화

1차 / 2차에서 @Async + OutboxProcessingService.process() 호출이었던 핸들러가 channel.offer() 한 줄로 단순화됐다.

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void handle(PaymentConfirmEvent event) {
    boolean offered = channel.offer(event.getOrderId());
    if (!offered) {
        log.warn("PaymentConfirmChannel 오버플로우 — OutboxWorker가 처리 예정");
    }
}

@Async가 제거되고, offer()는 비차단이므로 AFTER_COMMIT 훅 안에서 호출해도 HTTP 스레드가 블로킹되지 않는다.

@TransactionalEventListener(AFTER_COMMIT) 유지 이유

• TX 커밋 전에 Worker가 queue.take()로 PENDING 레코드를 조회하면 미커밋 상태의 레코드를 보게 되는 경쟁 조건 발생
• AFTER_COMMIT을 보장함으로써 Worker가 조회하는 시점에 PENDING 레코드가 DB에 확실히 존재 보장

OutboxImmediateWorker

Worker의 핵심은 SmartLifecycle을 구현해 Spring 컨테이너의 start/stop 훅에 연동하고, 고정 수의 가상 스레드가 take() → process() 루프를 돌리게 된다.

@Component
@RequiredArgsConstructor
public class OutboxImmediateWorker implements SmartLifecycle {

    private final PaymentConfirmChannel channel;
    private final OutboxProcessingService outboxProcessingService;

    @Value("${outbox.channel.worker-count:200}")
    private int workerCount;

    // ...

    // start()에서 workerCount개의 가상 스레드 기동
    // 각 스레드는 아래 루프를 실행
    private void workerLoop() {
        while (!Thread.currentThread().isInterrupted()) {
            try {
                String orderId = channel.take();
                outboxProcessingService.process(orderId);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }
    }

    // ...
}

• Spring 컨테이너가 종료될 때 stop() 훅이 호출되면, 진행 중인 작업을 마무리한 뒤 Worker 스레드를 interrupt로 정리하는 Graceful Shutdown 수행
• 강제 종료 등 시나리오: 큐에 남아있던 이벤트는 DB에 PENDING 레코드로 이미 저장되어 있으므로 OutboxWorker 폴링이 재시작 후 이어서 처리
  • 재요청 되더라도 멱등키를 포함한 confirm 요청으로, 중복 결제 방지

Worker 가상 스레드 적용 이점

가상 스레드는 아래 두 가지 구간 모두 캐리어 스레드(OS 스레드)를 반납하고 unmount된다.

1. 큐가 비었을 때 queue.take() 대기
2. Toss API 호출 시 HTTP I/O 대기

플랫폼 스레드였다면 300개의 Worker가 각각 OS 스레드를 점유하지만, 가상 스레드는 실제 작업 중인 소수만 OS 스레드를 사용한다.

sequenceDiagram
    participant Queue as 처리 큐
    participant VT as Worker 가상 스레드
    participant OS as OS 스레드 (캐리어)
    participant PG as PG API
    Note over VT: 큐가 비어있는 상태
    VT ->> Queue: 큐에서 대기
    Queue -->> VT: 대기 (큐 비어있음)
    VT -->> OS: 캐리어 반납 (unmount)
    Note over OS: 다른 가상 스레드가 사용 가능
    Note over Queue: 이벤트 도착
    Queue ->> VT: 이벤트 도착 → 깨어남
    OS ->> VT: 캐리어 할당 (mount)
    VT ->> PG: PG 승인 요청 (I/O 대기)
    VT -->> OS: 캐리어 반납 (unmount)
    PG -->> VT: 응답 수신
    OS ->> VT: 캐리어 재할당
    VT ->> VT: 결제 완료 처리

JDBC Pinning 문제와 해결

Worker가 DB 작업(claimToInFlight, markDone)을 수행할 때 한 가지 문제점이 존재했다.

• 문제: MySQL Connector/J 8.x는 JDBC 처리 경로에 synchronized 블록을 사용하여, 가상 스레드가 캐리어 스레드 고정(Pinning)
• 영향: 가상 스레드의 확장성 이점이 DB 작업 구간에서 무력화
• 해결: Spring Boot를 3.3.3에서 3.4.4로 업그레이드 → Connector/J 9.1.0이 자동 포함되며, synchronized가 ReentrantLock으로 교체되어 Pinning 해소

안전망 - 이중 트랙 구조

ConfirmImmediateWorker 하나로 처리하는 것이 아니라, OutboxWorker라는 폴백 경로를 두어, 이상 상황에서도 PENDING 레코드가 남아 있는 한 최종 처리가 보장되는 구조로 설계했다.

graph LR
%% 클래스 정의 (가독성 및 테마 대응 규칙 적용)
    classDef entry fill: #F5F5F5,stroke: #333,color: #000
    classDef data fill: #FFF2CC,stroke: #D79B00,color: #000
    classDef fast fill: #E1F5FF,stroke: #0078D4,color: #000
    classDef safety fill: #FADAD8,stroke: #B85450,color: #000
    classDef success fill: #E8F5E9,stroke: #2E7D32,color: #000
    A["결제 승인 요청"]:::entry --> B["DB: 대기열 등록"]:::data
    B --> C{"큐 등록"}:::data
%% Fast Track: 실시간성 보장
    C -- " 성공 " --> D["실시간 경로<br/>(워커 즉시 처리)"]:::fast
%% Safety Track: 안정성 보장 (Backpressure)
    C -- " 실패 (큐 가득 참) " --> E["대기열 유지"]:::safety
    E --> F["복구 경로<br/>(폴링 복구기 3초 주기)"]:::safety
%% 장애 복구 트리거
    H["서버 재시작"]:::entry --> F
%% 최종 결과
    D --> G["결제 완료"]:::success
    F --> G
%% 연결선 스타일
    linkStyle 2 stroke: #0078D4,stroke-width: 2px,color: #0078D4
    linkStyle 3 stroke: #FF3333,stroke-width: 2px,color: #FF3333

• OutboxImmediateWorker(Fast Track): 메모리 채널(LinkedBlockingQueue)에서 이벤트를 꺼내 즉시 처리하는 성능 가속기(정상 상황에서 대부분의 이벤트에 해당)
• OutboxWorker(Safety Track): DB에 남아있는 PENDING 레코드를 3초 간격으로 폴링하여 처리하는 최후 방어선
  • 큐 오버플로우, 서버 재시작, Worker 처리 실패 등 이상 상황에서의 결제 데이터 유실을 방지

Fast Track 인메모리 큐의 서버 종료 시 소실된다는 단점을 Safety Track으로 결제 데이터의 최종 처리를 보장하는 이중 트랙 구조로 보완했다.

---

벤치마크 — 아키텍처 성능 검증 및 최적화

아홉 차례 이상의 실험을 통해 초기 아키텍처의 한계를 진단하고, 시스템 경합 상황을 거쳐 최종적인 성능 최적화 수치를 도출하는 과정을 4단계로 정리하면 다음과 같다.

전체 벤치마크 리포트

1단계: 초기 @Async 방식의 구조적 한계

LinkedBlockingQueue 도입 전, @Async와 ConcurrencyThrottleSupport 조합의 한계를 확인했다.

• 자원 고갈: 동시 실행 제한이 없을 경우 HikariCP 커넥션 풀이 즉각 고갈되어 에러율 80%
• 응답 지연: 동시 실행 제한(N) 적용 시 호출 스레드 자체가 블로킹되어 HTTP 응답 시간이 Toss API 지연 시간과 동기화됨
• 결론: 큐 적체 기능이 없는 단순 비동기 처리는 고부하 상황에서 안전장치 역할을 수행할 수 없음

2단계: LBQ + Worker 아키텍처 효과 정량 확인

@Async 1차(제한 없음) / 2차(setConcurrencyLimit) 한계를 해소한 LinkedBlockingQueue + Worker 가상 스레드 구조에서 100 req/s 고부하 측정을 진행했다. 측정 정밀도를 위해 confirm_ms Trend를 별도 도입해 checkout 노이즈가 섞이지 않은 순수 confirm 응답 시간을 분리 수집했다.

지연 환경	케이스	TPS	Confirm med	Confirm p95	부하 미수용
고지연 (2.0~3.5s)	동기	57.7	5,098ms	7,191ms	2,689
고지연 (2.0~3.5s)	비동기	64.4	15ms	1,189ms	99

• HTTP 스레드 즉시 해방 검증: Confirm med 약 340배 차이 — 비동기 측은 채널 offer 후 즉시 202 반환으로 외부 PG 지연을 흡수하지 않음
• 부하 미수용 96% 감소: Tomcat 스레드 200개가 외부 PG 대기에 묶이지 않아 신규 요청 수용 능력 확보
• 백프레셔 검증: 1차 / 2차 구현에서 발생한 HikariCP 고갈 또는 HTTP 응답 블로킹 없이 안정적 처리

3단계: 환경 변동성 격리 + 클린 환경 베이스라인

반복 측정에서 라운드별 수치 변동을 관찰하여 두 종류로 분리했다.

• 시스템 변경에 의한 변동: 메트릭 분리, 자원 파라미터 조정 등 의도된 차이
• 측정 환경에 의한 변동: Mac CPU thermal, Docker VM 자원 경합 등 노이즈

후자를 격리하기 위해 백그라운드 프로세스 최소화 및 온도 안정 상태에서 동일 조건 3회 반복 측정으로 평균을 산출했다.

지연 환경	케이스	TPS	API 응답 med	결제 완료 med	부하 미수용
고지연 (2.0~3.5s)	동기	54.3	6,118ms	3,221ms	1,934
고지연 (2.0~3.5s)	비동기	71.2	7ms	2,872ms	0
저지연 (0.1~0.3s)	동기	107.3	212ms	213ms	0
저지연 (0.1~0.3s)	비동기	84.1	8ms	308ms	0

• 재현성 확보: 3회 모두 일관된 평균값 도출, 부하 미수용 0건 수렴
• 환경 변동성 입증: 이전 측정의 부하 미수용 변동이 환경 노이즈였음이 클린 환경에서 입증
• 가용성 격차 확인: 고지연 환경에서 비동기는 응답 7ms 내외로 스레드를 즉시 해방, 부하 미수용 0건 달성

4단계: 최종 최적화 및 임계 성능 도출

반복 실험을 통해 도출한 최적 파라미터 조합(HikariCP 30 / Worker 300 / Batch Size 100)을 적용하여 최종 성능을 확정했다.

지연 환경	케이스	TPS	API 응답 med	결제 완료 med	결제 완료 p95	부하 미수용
고지연 (2.0~3.5s)	sync-high	54.1/s	6,157ms	3,190ms	9,343ms	1,945
고지연 (2.0~3.5s)	outbox-high	79.8/s	5.3ms	2,820ms	3,423ms	0
저지연 (0.1~0.3s)	sync-low	106.4/s	210ms	211ms	299ms	0
저지연 (0.1~0.3s)	outbox-low	93.5/s	6.3ms	305ms	321ms	0

• 성능 향상: 고지연 환경에서 동기 전략 대비 약 47.5%의 TPS 향상 달성
• 자원 효율성: 커넥션 풀을 30으로 최적화하여 컨텐션 비용을 줄이고 시스템 안정성을 강화
• 고가용성: 부하 미수용 1,945건 → 0건 (-100%)

결론

단순한 동기 confirm 플로우에서 안전한 비동기 Outbox 패턴으로 아키텍처를 진화시키며, 다음 세 가지 인사이트를 얻을 수 있었다.

1. 비동기 아키텍처에서의 Backpressure 중요성

• 동시 실행 제한 없이 @Async 적용 시 HikariCP 고갈(에러율 80%) 발생 및 제한 시 HTTP 스레드 블로킹(부하 미수용 10,000건 이상) 유발
• LinkedBlockingQueue 용량 상한과 Worker 수를 통해 생산 및 소비 속도의 균형을 맞추는 구조 필요

2. 인메모리 채널 기반 메시지 발행의 위험성

• 서버 재시작, 큐 오버플로우, Worker 처리 실패 등 메시지 유실 가능성이라는 단점 존재
• OutboxImmediateWorker(Fast Track)가 성능 / OutboxWorker(Safety Track)가 안전을 담당하는 이중 트랙 구조로 보완

3. 비동기 결제 패턴의 핵심 가치 - 시스템 가용성 확보

외부 API 지연이 스레드 고갈로 전파되는 것을 격리하는 역할이며, 클린 환경 최종 검증에서 이를 확인했다.

핵심 지표	동기 방식	비동기(Outbox)
고지연 부하 미수용	1,945건	0건 (-100%)
고지연 결제 응답성 (Confirm med)	6,157ms (마비)	7ms
고지연 전체 처리량 (TPS)	54.1	79.8 (+47%)
상시 저지연 결제 완료 시간	213ms (우위)	308ms

• 아키텍처 트레이드오프: 저지연 환경에서 Sync가 유리한 것은 자연스러운 결과
• 안전장치로서의 가치: Outbox 패턴은 외부 API 장애 시 시스템이 무너지지 않도록 지탱하는 가치를 데이터로 입증

Tags:

• Payment Platform Project

Checkout API 멱등성 보장 — Caffeine 캐시와 TOCTOU 경쟁 조건 해결

2026. 3. 25.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.4.x, MySQL 8.0

배경

결제 플랫폼의 POST /checkout API는 호출마다 새 orderId를 발급하고 PaymentEvent를 생성한다. UI 중복 클릭, 클라이언트 네트워크 재시도, 버그로 인한 반복 호출이 발생하면 각 요청이 독립적인 PaymentEvent를 생성해 DB에 READY 상태의 유효하지 않은 주문이 누적된다.

설계 고민

멱등성 구현 방식 선택

프로젝트는 단일 서버 벤치마크 환경이므로 별도 인프라 없이 구현 가능한 Caffeine을 선택했다.

방식	장점	단점
클라이언트 멱등성 키	Stripe 등 표준 패턴, 의미 명확	클라이언트 협력 필요
DB Unique Constraint	추가 인프라 불필요, 트랜잭션 정합성 보장	예외 흐름 제어, TTL 관리 필요
Redis SETNX EX	원자적, TTL 자동, 다중 서버 지원	Redis 인프라 필요
Caffeine 인메모리 캐시	인프라 불필요, 구현 단순, 원자적 API 지원	서버 재시작 시 소실, 단일 서버만 가능

단, 추후 Redis로 교체할 수 있도록 IdempotencyStore를 outbound port 인터페이스로 추상화해 구현체를 분리했다.

멱등키 전략

키 전략은 두 가지 방식을 모두 지원하도록 설계했다.

• 클라이언트가 Idempotency-Key 헤더를 제공하면 해당 값을 우선 사용
• 헤더가 없으면 서버가 SHA-256(userId + sortedProductIds + quantities)로 body hash를 자동 파생
  • productId 기준 정렬을 적용한 이유: 상품 순서가 달라도 동일 요청으로 판단

HTTP 응답은 최초 생성 시 201 Created, 중복 요청 시 200 OK로 구분해 클라이언트가 신규/기존 여부를 판단할 수 있도록 했다.

1단계 구현 — getIfPresent + put

포트 인터페이스를 먼저 정의하고 구현체를 infrastructure 레이어에 두는 포트-어댑터 패턴을 적용했다.

public interface IdempotencyStore {

    Optional<CheckoutResult> getIfPresent(String key);

    void put(String key, CheckoutResult result);
}

• 서비스는 캐시 적중 여부를 확인 후 없으면 생성, 있으면 isDuplicate=true를 붙여 반환하는 흐름으로 구현
• 단위 테스트용 FakeIdempotencyStore는 HashMap 기반으로 구현

코드 리뷰에서 발견된 문제 — TOCTOU 경쟁 조건

구현 후 코드 리뷰를 진행하면서 근본적인 문제가 발견되었다.

sequenceDiagram
    participant A as Thread A
    participant B as Thread B
    participant Cache
    A ->> Cache: get("key") → miss
    B ->> Cache: get("key") → miss
    A ->> A: create() → PaymentEvent#1
    B ->> B: create() → PaymentEvent#2
    A ->> Cache: put("key", result#1)
    B ->> Cache: put("key", result#2)
    Note over Cache: ⚠️ 중복 생성 발생

• getIfPresent와 put 사이에 원자성이 보장되지 않음
• 두 스레드가 동시에 miss를 확인하면 둘 다 PaymentEvent를 생성하는 TOCTOU(Time-Of-Check-Time-Of-Use) 경쟁 조건이 발생

단일 스레드로 실행되는 단위 테스트는 HashMap 기반 Fake로 문제없이 통과하면서, 테스트가 구현 결함을 검증하고 못하고 있었다.

2차 개선 — getOrCreate 원자적 패턴으로 재설계

TOCTOU를 해결하는 세 가지 방식을 검토했고, 이 중 getOrCreate 방식을 선택했다.

옵션	장점	단점
getOrCreate(key, supplier)	포트 계약이 원자성 표현, 구현체 교체 용이	동일 키 동시 요청에서 후발 스레드 블록
DB Unique Constraint	영구 저장, 분산 환경 안전	스키마 변경 필요, 예외 흐름 제어
Fail-fast (409)	블로킹 없음	클라이언트 retry 복잡도 증가, UX 저하

블로킹 트레이드오프

getOrCreate의 단점은 동일 키 동시 요청에서 후발 스레드가 블로킹 되지만, 큰 리스크가 없다고 판단했다.

• 블로킹은 동일 키를 가진 요청 사이에만 발생하여 다른 키를 가진 요청은 영향을 받지 않음
• 클라이언트에서 두 번의 요청(따닥)이 연속해서 오고, 실패 처리를 하게 되면 아예 재요청해야하는 것보다 이미 생성된 값을 주는 것이 낫다고 판단

sequenceDiagram
    participant A as Thread A
    participant B as Thread B
    participant Cache as Caffeine Cache
    A ->> Cache: get("key", loader)
    Cache -->> A: (lock acquired, loader 실행 중)
    A ->> A: create() → PaymentEvent#1
    B ->> Cache: get("key", loader)
    Cache -->> B: (동일 키 → lock wait)
    A ->> Cache: 결과 저장 후 lock 해제
    Cache -->> B: hit → PaymentEvent#1 반환 (loader 미실행)
    Note over Cache: ✅ 중복 생성 없음

인터페이스 재설계

단순히 구현체만 바꾸는 것이 아니라 포트 인터페이스 시그니처도 변경했다.

IdempotencyResult<CheckoutResult> getOrCreate(String key, Supplier<CheckoutResult> creator);

• 기존: getIfPresent + put 구조에서 포트는 두 메서드를 노출하고, 원자성을 어떻게 보장할지 호출자에게 책임 발생
• 개선: getOrCreate로 변경하면 포트 계약 자체가 원자적 수행 표현하여, 호출자는 원자성 구현 방식을 알 필요 없이 구현체만 교체 가능

테스트

동시성 E2E 통합 테스트 — PaymentCheckoutConcurrencyIntegrationTest

단위 테스트만으로는 실제 경쟁 조건을 재현하기 어렵다고 판단하여, MySQL + MockMvc 환경의 멀티 스레드 테스트를 진행했다.

시나리오	검증 내용
동일 키, N개 스레드 동시 요청	payment_event 1개만 생성, 모든 요청 2xx
동일 키, 순차 2회 요청	첫 번째 201 Created, 두 번째 200 OK, DB 레코드 1개
서로 다른 키, N개 동시 요청	payment_event N개 독립 생성, 모두 201 Created

결론

getIfPresent + put 구조는 TOCTOU 경쟁 조건을 내포하는 것에서, getOrCreate 단일 원자적 메서드로 포트 계약을 재설계해 문제를 해결했다.

구현체	원자성 방법	적합 환경
IdempotencyStoreImpl	Cache.get(key, loader) — loader 1회 실행 보장	단일 JVM
RedisIdempotencyStore (미래)	SETNX 선예약 → 실행 → 결과 저장	다중 인스턴스
FakeIdempotencyStore (테스트)	ConcurrentHashMap.computeIfAbsent	테스트 환경

한계 및 향후 개선

• 서버 재시작 시 Caffeine 캐시 휘발 문제 존재
• 프로덕션 전환 시 다음 중 하나 고려
  • DB Unique Constraint: idempotency_key 유니크 제약으로 최후 제약 조건 추가
  • Redis 구현체: SETNX 기반 분산 원자적 처리로 포트 교체

Tags:

• Payment Platform Project

전략 패턴을 통한 결제 게이트웨이 추상화 및 확장성 확보

2025. 11. 22. - Last update: 2026. 4. 14.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.4.4

배경 및 문제 정의

초기 구현에서는 특정 PG(Toss Payments)에 강하게 결합된 구조로, 결제 시스템은 비즈니스 요구에 따라 PG를 유연하게 전환할 수 없는 구조였다.

• 도메인/애플리케이션 레이어에 Toss-specific 타입 직접 사용 (TossPaymentInfo, TossPaymentDetails)
• PG 변경 시 핵심 비즈니스 로직 수정 필요로 인한 높은 결합도
• 여러 PG 동시 지원 불가능으로 비즈니스 확장성 제약

해결 방향

이러한 문제를 해결하기 위해 전략 패턴과 포트-어댑터 패턴을 결합하여 PG 독립적인 아키텍처를 구축하고, 실제로 NicePay를 두 번째 PG로 추가하여 멀티 PG 운영을 달성했다.

목표	달성 방법
도메인 모델 PG 독립화 (PG 변경 시 비즈니스 로직 무수정)	포트-어댑터 패턴으로 경계 분리
새로운 PG 추가 시 기존 코드 무영향 (OCP)	전략 패턴으로 구현체 캡슐화
PG마다 다른 멱등성 처리를 상위 레이어에 노출하지 않음	구현체 내부에서 에러 감지 및 보상

핵심은 추상화를 통한 의존성 역전으로, 도메인 레이어는 구체적인 PG 구현체가 아닌 추상화된 인터페이스에만 의존하도록 설계했다.

아키텍처 설계

레이어 구조

애플리케이션 레이어는 구체적인 구현이 아닌 Port 인터페이스에만 의존하며, 실제 PG 통신 로직은 Infrastructure 레이어의 Strategy 구현체에서 처리된다.

• 현재 Toss와 NicePay 두 전략 구현
• 결제건마다 gatewayType으로 올바른 PG를 라우팅

graph TB
    subgraph "Application Layer"
        Service[OutboxAsyncConfirmService]
        UseCase[PaymentCommandUseCase]
        Port[PaymentGatewayPort<br/>Interface]
    end

    subgraph "Infrastructure Layer"
        Adapter[InternalPaymentGatewayAdapter<br/>Port 구현체]
        Factory[PaymentGatewayFactory<br/>전략 선택]
        Strategy[PaymentGatewayStrategy<br/>Interface]

        subgraph "Strategy Implementations"
            Toss[TossPaymentGatewayStrategy]
            Nicepay[NicepayPaymentGatewayStrategy]
        end
    end

    subgraph "External Systems"
        TossAPI[Toss Payments API]
        NicepayAPI[NicePay API]
    end

    Service -->|사용| UseCase
    UseCase -->|의존| Port
    Port -.->|구현| Adapter
    Adapter -->|위임| Factory
    Factory -->|선택| Strategy
    Strategy -.->|구현| Toss
    Strategy -.->|구현| Nicepay
    Toss -->|호출| TossAPI
    Nicepay -->|호출| NicepayAPI
    style Port fill: #e1f5ff, color: #000
    style Strategy fill: #e1f5ff, color: #000
    style Adapter fill: #fff4e1, color: #000
    style Factory fill: #fff4e1, color: #000
    style Toss fill: #e8f5e9, color: #000
    style Nicepay fill: #e8f5e9, color: #000

핵심 컴포넌트

1. PaymentGatewayPort(포트 인터페이스)

애플리케이션 레이어가 외부 PG와 통신하기 위한 추상 인터페이스로, 구체적인 PG 구현체가 이를 구현하는 의존성 역전 구조를 형성한다.

PaymentGatewayPort.java

public interface PaymentGatewayPort {

    PaymentStatusResult getStatus(String paymentKey, PaymentGatewayType gatewayType);

    PaymentStatusResult getStatusByOrderId(String orderId, PaymentGatewayType gatewayType);

    PaymentConfirmResult confirm(PaymentConfirmRequest request);

    PaymentCancelResult cancel(PaymentCancelRequest request);
}

• 모든 메서드는 PG-독립적인 DTO(PaymentStatusResult, PaymentConfirmRequest) 사용 — 특정 PG에 종속되지 않는 구조
• 예외도 벤더 중립(PaymentGatewayRetryableException, PaymentGatewayNonRetryableException)으로 통일
• getStatus, getStatusByOrderId는 gatewayType 파라미터를 받아 결제건에 기록된 PG로 조회
• PG별 데이터 변환은 Infrastructure 레이어에서 처리

2. InternalPaymentGatewayAdapter(어댑터 구현)

Port를 구현하고 전략 패턴으로 위임하는 중재 역할을 수행하며, 실제 PG 통신 로직은 Strategy 구현체에 위임한다.

InternalPaymentGatewayAdapter.java

@Component
@RequiredArgsConstructor
public class InternalPaymentGatewayAdapter implements PaymentGatewayPort {

    private final PaymentGatewayFactory factory;
    private final PaymentGatewayProperties properties;

    @Override
    public PaymentConfirmResult confirm(PaymentConfirmRequest request) {
        PaymentGatewayStrategy strategy = factory.getStrategy(request.gatewayType());
        return strategy.confirm(request);
    }

    // confirm/cancel은 요청의 gatewayType으로 전략 선택
    private PaymentGatewayType resolveGatewayType(PaymentGatewayType gatewayType) {
        return gatewayType != null ? gatewayType : properties.getType();
    }
}

• confirm/cancel: 요청 DTO에 포함된 gatewayType으로 전략 선택
• getStatus/getStatusByOrderId: PaymentEvent에 기록된 gatewayType 사용

3. PaymentGatewayStrategy(전략 인터페이스)

PG별 구현체가 구현해야 하는 공통 인터페이스를 정의하여, 모든 PG가 제공해야 하는 표준 작업(결제 승인, 취소, 조회)을 명시한다.

PaymentGatewayStrategy.java

public interface PaymentGatewayStrategy {

    boolean supports(PaymentGatewayType type);

    PaymentConfirmResult confirm(PaymentConfirmRequest request);

    PaymentCancelResult cancel(PaymentCancelRequest request);

    PaymentStatusResult getStatus(String paymentKey);

    PaymentStatusResult getStatusByOrderId(String orderId);
}

4. PaymentGatewayFactory(전략 선택 팩토리)

설정 기반으로 적절한 전략을 선택하고 반환하는 역할로, Spring의 의존성 주입을 활용하여 모든 Strategy 구현체를 자동으로 수집하고, 런타임에 설정값에 따라 적절한 구현체를 선택한다.

PaymentGatewayFactory.java

@Component
@RequiredArgsConstructor
public class PaymentGatewayFactory {

    private final List<PaymentGatewayStrategy> strategies;

    public PaymentGatewayStrategy getStrategy(PaymentGatewayType type) {
        return strategies.stream()
                .filter(strategy -> strategy.supports(type))
                .findFirst()
                .orElseThrow(() -> UnsupportedPaymentGatewayException.of(type));
    }
}

• Spring 자동 주입: 모든 PaymentGatewayStrategy 구현체가 자동으로 List에 주입
• 예외 처리: 지원하지 않는 PG 타입이 설정되면 명확한 예외(UnsupportedPaymentGatewayException)를 발생

구현체 내부에서의 멱등성 추상화

PG마다 다른 멱등성 보장 방식을 구현체 내부에서 캡슐화하여, Application 레이어에는 동일한 PaymentConfirmResult만 노출하게 구현했다.

문제 - PG마다 다른 멱등성 처리

결제 승인은 네트워크 장애, 타임아웃 등으로 중복 요청이 발생할 수 있는데, PG마다 멱등성 보장 방식이 다르다.

PG	멱등성 보장 방식	중복 요청 시 동작
Toss	Idempotency-Key 헤더 전송	PG가 같은 요청으로 인식, 정상 응답 반환
NicePay	멱등성 키 미지원	에러코드 2201 반환 (중복 승인 거절)

이러한 처리 방식의 차이를 Application 레이어에 노출하면 PG별 분기 로직이 비즈니스 레이어에 침투하게 된다.

해결 - 구현체 내부에서 에러를 감지하고 보상 처리

NicePay 전략 구현체는 중복 승인 에러(2201)를 내부에서 catch하고, 조회 API로 보상 처리한 뒤 정상 결과를 반환했다.

// NicepayPaymentGatewayStrategy.java (발췌)
private PaymentConfirmResult executeConfirmPayment(
        NicepayConfirmRequest confirmRequest,
        PaymentConfirmRequest request
) throws PaymentGatewayRetryableException, PaymentGatewayNonRetryableException {
    try {
        NicepayPaymentResponse response =
                nicepayGatewayInternalReceiver.confirmPayment(confirmRequest);
        return convertToPaymentConfirmResult(response, request);
    } catch (PaymentGatewayApiException e) {
        if (NICEPAY_ERROR_CODE_DUPLICATE_APPROVAL.equals(e.getCode())) {
            // 2201 중복 승인 → 조회 API로 보상 처리
            return handleDuplicateApprovalCompensation(request);
        }
        return classifyAndThrowConfirmException(e);
    }
}

이 구조에서 Application 레이어의 PaymentCommandUseCase는 PG가 Toss인지 NicePay인지, 멱등성 키를 헤더로 보내는지 보상 조회로 처리하는지 전혀 알지 못한다.

flowchart LR
    subgraph "Application Layer"
        UC[PaymentCommandUseCase]
    end

    subgraph "Infrastructure Layer"
        subgraph "Toss 전략"
            T1["confirm 요청\n+ Idempotency-Key 헤더"]
            T2["PG가 중복 인식\n→ 정상 응답"]
        end
        subgraph "NicePay 전략"
            N1["confirm 요청"]
            N2{"2201\n중복 승인?"}
            N3["tid로 PG 상태 조회"]
        end
    end

    UC -->|" confirm(request) "| T1
    UC -->|" confirm(request) "| N1
    T1 --> T2
    T2 -->|" PaymentConfirmResult\n(SUCCESS) "| UC
    N1 --> N2
    N2 -->|예| N3
    N2 -->|아니오| N5["에러코드 분류\n→ 예외"]
    N3 -->|" PaymentConfirmResult\n(SUCCESS) "| UC

두 경우 모두 동일한 PaymentConfirmResult(SUCCESS, ...) 를 받으면서, 로직을 수행할 수 있게 된다.

결론

전략 패턴과 포트-어댑터 패턴을 결합하여 PG 독립적인 아키텍처를 구축하고, 실제로 NicePay를 두 번째 PG로 추가함으로써 설계의 확장성을 검증했다.

1. PG 독립성 확보: 도메인/애플리케이션 레이어에서 PG-specific 타입 완전 제거
2. 확장 가능한 구조: PaymentGatewayStrategy 구현 + @Component 등록만으로 새 PG 추가 가능, Factory 코드 수정 불필요
3. 멱등성 차이 캡슐화: PG마다 다른 멱등성 보장 방식(헤더 vs 보상 조회)을 구현체 내부에서 처리하여 상위 레이어에 동일한 결과 타입만 노출

Tags:

• Payment Platform Project

보상 트랜잭션 실패 상황 극복 가능한 결제 플로우 설계

2025. 11. 2. - Last update: 2026. 3. 12.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.3.3

[!CAUTION] 이 글은 작성 시점의 구현을 기준으로 하며, 이후 보상 트랜잭션 실행 전 이중 조건 가드(Outbox IN_FLIGHT + Event 비종결 검사)가 추가되었고, 격리 전 최종 확인 단계가 도입되었다. 현재 설계는 결제 복구 상태 전이 설계를 참고한다.

배경 및 문제 정의

결제 로직은 내부 DB 자원(재고 차감)과 외부 API 자원(PG사 결제 요청)이라는 서로 다른 리소스를 하나의 비즈니스 프로세스로 처리한다.

기존 방식

기존에는 로직 수행 중 실패에 대해 보상 트랜잭션 방식을 채택했다.

• 재고 차감 먼저 수행
• 외부 결제가 실패 시 차감된 재고 복구

보상 트랜잭션의 한계

문제는 ‘차감된 재고를 복구하는 보상 트랜잭션’ 자체가 실패할 수 있다는 점이다.

1. PG사 결제 실패: 잔액 부족 등으로 인해 외부 결제 승인 API가 실패 응답 반환
2. 보상 로직 가동: 시스템은 차감했던 재고를 복구하기 위해 DB 업데이트 시도
3. 이차 장애 발생: 이 시점에 DB 데드락, 네트워크 타임아웃, 혹은 인스턴스 셧다운이 발생하여 복구 쿼리 유실

이러한 이중 장애가 발생하면 시스템은 아래와 같이 비즈니스 정합성이 깨지는 데이터 불일치 상태에 빠진다.

graph TD
    subgraph Problem ["보상 트랜잭션 실패 상황"]
        A[PG 결제 실패] -- " 1. 보상 트랜잭션 트리거 " --> B{재고 복구 시도}
        B -- " 2. DB 장애 / 서버 다운 " --> C((실패))
    end

    C -.-> D{{"데이터 불일치 발생"}}
    D --- E["결제 상태: <b>실패</b> (고객 미결제)"]
    D --- F["재고 상태: <b>차감됨</b> (복구 누락)"]
    style D fill: #ffcccc, stroke: #ff0000, stroke-width: 2px, color: #000
    style C fill: #000, color: #fff

결국, 단순한 보상 트랜잭션 로직만으로는 인프라 장애 시 발생하는 데이터 정합성 문제를 해결할 수 없어, 이를 극복하기 위해 시스템이 스스로 상태를 추적하고 회복할 수 있는 구조가 필요했다.

개발 목표 및 설계 원칙

이 실패 처리의 실패(Double Fault) 문제를 해결하기 위해, 다음과 같은 설계 원칙을 수립했다.

1. 상태 추적성 (Traceability): 모든 결제 과정을 ‘작업’으로 정의하고 상태를 별도 테이블에 기록하여, 장애 발생 시에도 중단된 지점을 명확히 식별
2. 최종적 일관성 (Eventual Consistency): 장애가 발생하더라도, 시스템 스스로 데이터 정합성 회복

기술적 결정 및 Trade-off

문제 해결을 위해 다음 세 가지 해결 방법을 검토했다.

1. Two-Phase Commit (2PC)
   • 모든 리소스(재고 DB, PG사)가 커밋에 동의해야 하는 강력한 일관성 모델
   • 한계: 외부 PG사가 2PC를 지원하지 않으며, 전체 시스템의 성능 저하와 블로킹(Blocking)을 유발
2. 메시지 큐와 Saga Pattern
   • 재고 차감, 결제 요청, 결과 처리를 별도의 트랜잭션으로 분리하고 메시지 큐(Kafka, RabbitMQ)로 연결하는 방식
   • 한계: 결합도는 낮지만 Kafka/RabbitMQ 도입이 필요해 현 규모에서는 오버엔지니어링으로 판단하여 제외
3. 선택: 작업 테이블 + Scheduler
   • ‘작업 테이블(payment_process)‘을 DB 내의 ‘메시지 큐(Outbox)‘처럼 활용하는 방식
   • 장점:
     • 단순성: 외부 인프라 의존성 없이, Spring 스케줄러와 DB만으로 ‘최종적 일관성’을 구현 가능
     • 트랜잭션 보장: 데이터 처리를 DB 트랜잭션 내에서 처리하여, 복잡한 트랜잭션 관리 불필요

아키텍처 - 3단계 트랜잭션 분리와 작업 테이블

기존 결제 로직을 3단계로 분리하고, 모든 과정을 PaymentProcess 작업 테이블에 기록하도록 설계했다.

작업 테이블 (payment_process) 스키마

컬럼명	타입	제약조건	설명
id	BigInt	PK, Auto-Increment	작업 고유 ID
order_id	String	Not Null	주문 고유 ID
status	Enum / Varchar	Not Null	작업 상태 (PROCESSING, COMPLETED, FAILED)
created_at	Timestamp	Not Null	생성 시각
updated_at	Timestamp	Not Null	수정 시각

이 테이블을 기반으로 결제 흐름은 다음과 같이 분리된다.

• 1단계 (Tx 1): 재고 차감 + 작업 생성 (PROCESSING)
• 2단계 (Non-Tx): 외부 PG사 결제 API 호출
• 3단계 (Tx 2): 결제 결과 반영 + 작업 상태 변경 (COMPLETED / FAILED)

이 구조의 핵심은 장애 발생 시 PROCESSING 상태가 DB에 남는다는 것이다.

graph TD
%% 클래스 정의 (가독성 및 테마 대응)
    classDef standard fill: #F5F5F5, stroke: #333, color: #000
    classDef process fill: #E1F5FF, stroke: #0078D4, color: #000
    classDef decision fill: #FFF2CC, stroke: #D79B00, color: #000
    classDef success fill: #E8F5E9, stroke: #2E7D32, color: #000
    classDef fail fill: #F8CECC, stroke: #B85450, color: #000

    subgraph sg1 ["1단계: 작업 생성 및 재고 차감 (Transaction 1)"]
        A["요청 시작"]:::standard --> B{"Tx START"}:::decision
        B --> C["1. payment_process 테이블에<br/>'PROCESSING' 상태로 작업(Job) INSERT"]:::process
        C --> D["2. stock 테이블 재고 차감"]:::process
        D --> E{"Tx COMMIT"}:::decision
    end

    E -- " 성공 " --> F["2단계: 외부 PG사 결제 처리"]:::standard
    F --> G{결제 성공?}:::decision

    subgraph sg3 ["3단계: 작업 완료 (Transaction 2)"]
        G -- " Yes " --> H_Success["Tx START"]:::decision
        H_Success --> I_Success["payment_process 상태 'COMPLETED'로 UPDATE"]:::success
        I_Success --> J_Success["orders 테이블 상태 '결제 완료'로 변경"]:::success
        J_Success --> K_Success["Tx COMMIT"]:::decision
        K_Success --> L_End["종료"]:::standard
        G -- " No " --> H_Fail["Tx START"]:::decision
        H_Fail --> I_Fail["payment_process 상태 'FAILED'로 UPDATE"]:::fail
        I_Fail --> J_Fail["[보상 트랜잭션]<br/>차감했던 재고 복구"]:::fail
        J_Fail --> K_Fail["Tx COMMIT"]:::decision
        K_Fail --> L_End
    end

    subgraph sg_recovery ["장애 복구 로직"]
        Z["복구 로직 시작"]:::standard --> Y["payment_process 테이블에서<br/>'PROCESSING' 상태인 작업 조회"]:::process
        Y --> X{"PG사에 실제 결제 성공 여부 조회 or 승인 요청"}:::decision
    %% 복구 로직 연동
        X -- " 결제 성공 상태 " --> H_Success
        X -- " 결제 실패 상태 " --> H_Fail
    end

%% 스타일 보정 (연결선 텍스트 강조)
    linkStyle 4,14,15 stroke: #333, stroke-width: 2px, color: #000

보상 트랜잭션 실패 흐름 시나리오

sequenceDiagram
    participant Client as 사용자
    participant Service as PaymentCoordinator
    participant DB as 데이터베이스 (JPA)
    participant Toss as Toss PG API
    Client ->> Service: 1. 결제 승인 요청
%% --- 1단계 (Tx 1) ---
    Service ->> DB: 2. [Tx 1 시작]
    Service ->> DB: 3. 재고(Stock) 차감
    Service ->> DB: 4. 작업(PaymentProcess) 생성 (상태: PROCESSING)
    Service ->> DB: 5. [Tx 1 커밋]
%% --- 2단계 (Non-Tx) ---
    Service ->> Toss: 6. 외부 결제 승인 API 호출
    Toss -->> Service: 7. 결제 실패 응답 (예: 한도 초과)
%% --- 3단계 (Tx 2) - 보상 트랜잭션 ---
    Service ->> DB: 8. [Tx 2 (보상) 시작]
    Service ->> DB: 9. 재고(Stock) 복구 시도
    Service ->> DB: 10. 작업(PaymentProcess) 상태 'FAILED' 변경 시도

    critical DB 장애 발생
        Service ->> DB: 11. [Tx 2 (보상) 롤백] (예: DB 데드락)
    end

    Service -->> Client: 12. 결제 실패 응답
    Note right of DB: [데이터 불일치 상태!]<br/>- 재고: 차감됨 (롤백 실패)<br/>- 작업 상태: PROCESSING (롤백됨)

11번 단계가 핵심인데, 보상 트랜잭션이 롤백되면서, 재고는 차감되었지만 작업 상태는 PROCESSING으로 남는 데이터 불일치 상태가 된다.

스케줄러를 통한 최종적 일관성 확보

문제를 해결하기 위해 PaymentRecoveryUseCase라는 스케줄러를 구현했다.

• 동작: PROCESSING 상태로 일정 시간 이상 방치된 작업을 조회
• 로직: 조회된 작업의 orderId로 Toss API에 실제 결제 상태를 다시 조회

sequenceDiagram
    participant Scheduler as PaymentRecoveryUseCase
    participant DB as 데이터베이스 (JPA)
    participant Toss as Toss PG API
    participant Service as PaymentCoordinator
    Scheduler ->> Scheduler: 1. 스케줄러 실행
    Scheduler ->> DB: 2. 'PROCESSING' 상태 작업 조회
    DB -->> Scheduler: 3. [Job (orderId-123)] 반환
    Scheduler ->> Toss: 4. Toss API로 결제 상태 재확인 (orderId-123)
    Toss -->> Scheduler: 5. 최종 상태 응답: "CANCELED" (실패)
    Scheduler ->> Service: 6. '결제 실패 보상 로직' 재실행
%% --- 3단계 (Tx 2) - 보상 트랜잭션 "재시도" ---
    Service ->> DB: 7. [Tx 2 (보상) 시작]
    Service ->> DB: 8. 재고(Stock) 복구
    Service ->> DB: 9. 작업(PaymentProcess) 상태 'FAILED' 변경
    Service ->> DB: 10. [Tx 2 (보상) 커밋]
    Note right of DB: [데이터 정합성 복구 완료!]<br/>- 재고: 정상 복구<br/>- 작업 상태: FAILED

결론

• 실패 처리의 실패(Double Fault) 해결: 데이터 불일치 시나리오에 대한 자동 복구 메커니즘 구축
• 최종적 일관성 확보: 스케줄러와 작업 테이블로 장애 발생 시에도 시스템이 스스로 정합성 회복

Tags:

• Payment Platform Project

결제 이력 추적 및 핵심 지표 모니터링 시스템 구현

2025. 9. 22. - Last update: 2026. 3. 12.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.3.3

배경 및 문제 정의

결제 복구 시스템을 구축하면서 상태 종류와 재시도 메커니즘이 늘어났고, 체계적인 상태 추적이 필요해졌다.

• 구조화되지 않은 로그 데이터로 인해 집계 및 분석이 어려움
• 트랜잭션 단위로 상태 변경의 정합성을 보장할 수 없음
• 수동 로그 해석에 따른 운영 효율성 저하
• 이상 데이터 탐지 및 모니터링 한계

구조화된 상태 변경 이력을 별도 테이블에 저장해 결제 이벤트를 시간순으로 추적할 수 있는 시스템이 필요했다.
단순 이력 추적을 넘어 외부 API 호출 시간, 특정 상태에 비정상적으로 머무는 결제 건수 등을 파악하는 실시간 모니터링 체계도 함께 추가했다.

개발 목표 및 설계 원칙

• 완전성: 모든 상태 전환이 누락 없이 기록
• 추적 가능성: 단일 결제 건의 모든 상태 전환을 시간순으로 연결·조회 가능
• 관심사 분리: 비즈니스 로직에 침투하지 않고 선언적으로 이력 추적 및 모니터링 기능 추가
• 운영 투명성: 외부 API 호출 성능 / 비정상 상태(5회 이상 재시도) 등 운영 지표 실시간 모니터링 기능 제공

기술 검토 및 설계 결정

두 가지 핵심 목표(이력 추적, 헬스 모니터링)를 달성하기 위해 다양한 기술적 대안을 검토했다.

결제 이력 추적(AOP + Spring Event 기반 설계)

결제 이력 추적 기능 구현을 위해 AOP + Spring Event을 사용하고, 커밋 직전(BEFORE_COMMIT)에 이력 저장을 수행하는 방안을 채택했다.

• AOP (Aspect-Oriented Programming)
  • 선정 이유: 상태 변경 기록은 전형적인 횡단 관심사 -> 서비스 코드 변경 최소화 가능
  • 장점: 어노테이션 기반 선언적 프로그래밍으로 적용 누락 최소화
    • 코드 내 직접 호출 대비 결합도 낮음
• Spring ApplicationEvent
  • 선정 이유: 프레임워크 내장 이벤트 시스템 활용 -> 외부 라이브러리 불필요
  • 장점: 이벤트 발행(서비스)과 처리(저장) 분리 -> 결합도 낮춤
    • 메시지 큐 대비 인프라 비용 추가 없이 구현 가능
• TransactionPhase.BEFORE_COMMIT
  • 선정 이유: 커밋 직전에 실행하여 비즈니스 상태와 이력 간 정합성 확보
  • 장점: 로직이 성공한 경우에만 기록
    • AFTER_COMMIT은 커밋 후 저장 실패하더라도, 비즈니스 로직이 이미 커밋된 상태가 되어 불일치 발생하는 문제 발생
    • 히스토리 테이블의 변경 이력 == 실제 비즈니스 상태 변경을 보장

모니터링

• AOP
  • 선정 이유: 기존 이력 추적 AOP와 동일한 메커니즘 활용 가능
  • 장점: 메서드 실행 시간(API 호출 시간) 측정 및 결제 상태 변경 감지 용이
• Scheduler DB 스캔
  • 선정 이유: 5회 이상 재시도 상태 등 장기 체류 결제 건 탐지 용이
  • 장점: 주기적으로 스캔하고, 이를 메트릭으로 노출하여 Grafana 대시보드에서 실시간 모니터링 가능

구현 세부 사항 1 - 결제 이력 추적

sequenceDiagram
    participant C as Caller
    box AOP Proxy Layer
        participant A as History Aspect
    end
    box Core Business Layer
        participant S as Service Method
    end
    participant E as Event Publisher
    participant L as @TransactionalEventListener
    participant DB as Database
    C ->> A: 메서드 호출 (@PublishPaymentHistory)
    activate A
    Note over A: [Before] 현재 DB 상태 스냅샷 캡처
    A ->> S: joinPoint.proceed() (실제 로직 위임)
    activate S
    S ->> DB: Payment 상태 변경 (UPDATE)
    S -->> A: 처리 결과 반환
    deactivate S
    Note over A: [After] 결과 분석 및 이벤트 발행 결정
    A ->> E: PaymentHistoryEvent 발행
    Note over E, DB: Transaction: BEFORE_COMMIT Phase
    E ->> L: 이벤트 전달
    L ->> DB: PaymentHistory 저장 (INSERT)
    A -->> C: 최종 결과 응답
    deactivate A
    Note over DB: Transaction Commit (Final)

1. 이력 추적 어노테이션 적용

비즈니스 서비스 메서드에 @PublishPaymentHistory 어노테이션을 선언하여, 해당 메서드 실행 시 자동으로 상태 변경 이력을 발행하도록 설정했다.

@Transactional
@PublishPaymentHistory(action = "changed")
public PaymentEvent markPaymentAsFail(
        PaymentEvent paymentEvent,
        @Reason String failureReason // 이력에 기록할 사유
) {
    // 순수한 비즈니스 로직 수행
    paymentEvent.fail(failureReason);
    return paymentEventRepository.saveOrUpdate(paymentEvent);
}

• @PublishPaymentHistory 어노테이션으로 이력 추적 대상 메서드 지정 및 action 속성으로 상태 변경 유형 전달
• @Reason 어노테이션으로 이력 기록에 포함할 변경 사유 전달

2. AOP Aspect - 상태 변경 감지

AOP Aspect에서는 메서드 실행 전의 상태를 저장하고, 변경 이력을 담은 이벤트를 발행한다.

@Around("@annotation(publishHistory)")
public Object publishHistoryEvent(ProceedingJoinPoint joinPoint, PublishPaymentHistory publishHistory)
        throws Throwable {
    // 1. 실행 전 상태 캡처
    Optional<PaymentEvent> beforeEventOpt = findPaymentEvent(joinPoint.getArgs());
    PaymentEventStatus beforeStatus = beforeEventOpt.map(PaymentEvent::getStatus).orElse(null);

    // 2. 이력에 기록할 사유 추출
    String reason = findReasonParameter(joinPoint);

    try {
        // 3. 비즈니스 로직 실행
        Object result = joinPoint.proceed();

        // 4. 실행 결과 기반으로 상태 변경 이벤트 발행
        processResultAndPublishEvent(beforeStatus, result, reason, publishHistory);

        return result;
    } catch (Exception e) {
        log.error("Error occurred while processing payment: {}", e.getMessage(), e);
        throw e;
    }
}

• findPaymentEvent 메서드로 현재 상태를 조회하여 이전 상태 저장
• findReasonParameter로 이력에 포함할 변경 사유 추출
• 비즈니스 로직 실행 후 action에 따라 적절한 이벤트 발행

3. 이벤트 리스너 - BEFORE_COMMIT 전략

Spring의 @TransactionalEventListener를 이용해, 트랜잭션 커밋 직전인 TransactionPhase.BEFORE_COMMIT 단계에서 이력 저장 로직을 실행한다.

@TransactionalEventListener(phase = TransactionPhase.BEFORE_COMMIT)
public void handlePaymentHistoryEvent(PaymentHistoryEvent event) {
    paymentHistoryService.recordPaymentHistory(event);
}

• BEFORE_COMMIT 단계는 트랜잭션이 성공적으로 커밋되기 직전에 실행되어, 비즈니스 상태 변경과 이력 기록이 동일 트랜잭션 내에서 처리되도록 보장
• 상태 변경과 이력 저장 간 불일치 문제를 방지하며, 데이터 정합성과 원자성을 확보

구현 세부 사항 2 - 모니터링

1. Toss API 메트릭 수집

외부 PG사인 Toss API 호출 시, AOP를 활용하여 호출 시간 및 성공/실패 여부를 메트릭으로 기록하도록 구현했다.

@Around("@annotation(tossApiMetric)")
public Object recordTossApiMetric(
        ProceedingJoinPoint joinPoint,
        TossApiMetric tossApiMetric
) throws Throwable {
    long startTime = System.currentTimeMillis();

    try {
        Object result = joinPoint.proceed();
        // 시간 측정
        long duration = System.currentTimeMillis() - startTime;

        // 성공 메트릭 기록
        handleSuccess(joinPoint, tossApiMetric, duration);

        return result;
    } catch (Exception e) {
        // ...
    }
}

private void handleSuccess(ProceedingJoinPoint joinPoint, TossApiMetric tossApiMetric, long duration) {
    switch (tossApiMetric.value()) {
        case SUCCESS:
            // 측정된 시간과 함께 메트릭 기록
            tossApiMetrics.recordTossApiCall(tossApiMetric.operation(), duration, true);
            break;
        // ...
    }
}

2. 스케줄러 기반 이상 징후 감지 (Gauge)

상태가 오랫동안 변경되지 않은 결제 건수, 알 수 없는 상태 건수, 최대 재시도 횟수에 도달한 건수 등은 주기적으로 DB에서 조회하여 Gauge 메트릭으로 기록하는 스케줄러를 구현했다.

@Scheduled(fixedDelayString = "${metrics.payment.health.polling-interval-seconds:10}000")
public void updateHealthGauges() {
    LocalDateTime now = localDateTimeProvider.now();

    // Stuck in progress
    LocalDateTime stuckThreshold = now.minusMinutes(stuckInProgressMinutes);
    long stuckInProgress = paymentEventRepository
            .countByStatusAndExecutedAtBefore(PaymentEventStatus.IN_PROGRESS, stuckThreshold);
    healthGauges.get("stuck_in_progress").set(stuckInProgress);

    // Unknown status
    long unknownStatus = paymentEventRepository.countByStatus()
            .getOrDefault(PaymentEventStatus.UNKNOWN, 0L);
    healthGauges.get("unknown_status").set(unknownStatus);

    // Max retry reached
    long maxRetryReached = paymentEventRepository
            .countByRetryCountGreaterThanEqual(maxRetryCount);
    healthGauges.get("max_retry_reached").set(maxRetryReached);

    log.debug("Health gauges updated - stuckInProgress={}, unknownStatus={}, maxRetryReached={}",
            stuckInProgress, unknownStatus, maxRetryReached);
}

주기적 DB 스캔의 위험성

주기적인 DB 스캔으로 간단하게 구현했으나, 운영 환경에서 다음과 같은 잠재적 위험이 존재한다.

• 트래픽이 많은 운영 환경에서 잦은 SELECT는 DB 부하 발생
• 헬스 체크 쿼리가 복잡해지거나 인덱스를 제대로 활용하지 못할 경우, 메인 비즈니스 로직의 트랜잭션 성능까지 영향 받을 수 있음

시스템 확장 시에는 다음과 같은 해결 방안을 고려해볼 수 있을 것으로 보인다.

1. 읽기 전용 복제(Read Replica) DB 활용: 모니터링 및 헬스 체크 쿼리를 읽기 전용 DB(Replica)로 분리하여, 다른 비즈니스 트랜잭션에 미치는 영향 최소화
2. 쿼리 최적화: 복합 인덱스를 적용하여 Full Table Scan 방지
3. 이벤트 기반 헬스 체크: DB 스캔 대신, 지연 큐(e.g., Redis, Kafka Streams)를 활용해 ‘5분 뒤 헬스 체크’ 이벤트를 발행하는 방식으로 DB 의존성 제거

결론

graph TD
    subgraph sg1 [API Request Flow]
        A[API 요청 수신] --> B{Trace ID 할당};
    end

    subgraph sg2 [비즈니스 로직]
        B --> C[결제 상태 변경 등<br/>비즈니스 로직 수행];
    end

    subgraph sg3 [AOP: 이력 저장 관심사 분리]
        C -- TransactionalEventListener --> D[PaymentStateChanged 이벤트 발생];
        D --> E{결제 상태 변경 이력 생성};
        E --> F[DB 트랜잭션 커밋 직전 이력 저장];
    end

    subgraph sg4 [AOP: 실시간 성능 측정 Timer]
        C -- AOP Pointcut --> M[외부 API 호출<br/>e.g. TossPayments 시간 측정];
        M --> N[수집];
    end

    subgraph sg5 [구조화된 로그]
        C --> L2[Trace ID + Order ID 기반<br/>로그 기록];
    end

    subgraph sg6 [데이터 저장 DB]
        F --> G[(DB: PaymentEvent,<br/>PaymentHistory)];
    end

    subgraph sg7 [헬스 모니터링 Scheduled Flow]
        H[Scheduled] -- 주기적 DB 스캔 --> G;
        H --> I{이상 징후 감지<br/>e.g., 5번 이상 시도한 결제};
        I --> J[수집];
    end

AOP, Spring Event, 스케줄러를 조합해 추적 가능하고 투명한 결제 시스템 기반을 구축했다.

• 복잡한 결제 상태 변경의 체계적 관리: 다양한 상태와 재시도 로직이 혼재하는 환경에서도 모든 상태 변경 내역을 누락 없이 기록해 장애 분석 및 추적 가능
• 비즈니스 로직 순수성 유지: 이력 추적 기능을 AOP 선언적 방식으로 분리해 기존 서비스 코드에 침투하지 않고 기능 추가
• 실시간 운영 투명성 확보: Toss API 호출 시간을 실시간 측정하고 스케줄러로 핵심 결제 상태 지표 모니터링

Tags:

• Payment Platform Project

Logger 성능 저하 방지와 구조화된 로깅 설계

2025. 8. 3. - Last update: 2026. 3. 12.

hyoguoo

Backend Engineer

로그를 단순히 println()으로 찍는 건 성능 이슈와 레벨을 구분할 수 없기 때문에, 개발 초기 테스트 외엔 적절하지 않다.

• 로그 레벨 구분이 없음 (debug, info, warn 등 불가능)
• 시간, 클래스, 스레드 정보가 출력되지 않음
• 로그 파일 관리 및 저장 불가
• 멀티스레드 환경에서 병목 발생 (System.out은 synchronized I/O)

로그는 문제를 추적하고 흐름을 분석하기 위해 많은 양의 데이터를 남기기 때문에, 구조화된 출력과 불필요한 연산 제어가 반드시 필요하다.

Logger 문자열 결합과 성능 문제

로그를 남길 때는 "Hello" + "World"와 같은 문자열 결합 방식이 아닌, "Hello {}"와 같은 포맷팅 방식을 권장하는데, 이는 성능에 영향을 미치기 때문이다.

private static void concatLog(Order order) {
    logger.trace("OrderId=" + order);
}

이 방식은 로그 레벨이 trace가 아니라면 출력도 안 되지만, order.toString() 호출과 문자열 결합은 그대로 발생하여, 출력은 안 되지만 연산은 수행되는 비효율이 생긴다.

// 1. 레벨을 직접 확인하는 방식
private static void checkConditionLog(Order order) {
    if (logger.isTraceEnabled()) {
        logger.trace("OrderId= " + order);
    }
}

// 2. 파라미터 포맷팅 방식
private static void paramLog(Order order) {
    logger.trace("OrderId={}", order);
}

이를 피하기 위해 두 가지 방식을 사용할 수 있다.

1. 로그 레벨을 직접 체크하는 방식
2. 파라미터 포맷팅 방식 ({} 사용)

1번 방식은 조건을 직접 해야하는 조건문을 작성해야 하므로 코드가 복잡해지고 가독성이 떨어져, 보통 2번 방식인 파라미터 포맷팅 방식을 사용한다.

로깅 방식별 성능 테스트

로깅 방식에 따른 성능 차이를 측정하기 위해, 멀티스레드 환경에서 다음과 같이 테스트를 작성하여 세 가지 방식에 대해 테스트를 진행했다.

1. 문자열 결합 방식 (+ 사용)
2. String.format() 방식
3. 파라미터 포맷팅 방식 ({} 사용)

LoggerTest.java

class LoggerTest extends IntegrationTest {

    private static final Logger logger = LoggerFactory.getLogger(LoggerTest.class);
    private static final int THREAD_COUNT = 10;
    private static final int TASK_COUNT = 100000;

    private static void logWithConcat(TestData testData) {
        logger.trace("[TEST] | TEST | testData=" + testData);
    }

    private static void logWithFormat(TestData testData) {
        logger.trace(String.format("[TEST] | TEST | testData=%s", testData));
    }

    private static void logWithParam(TestData testData) {
        logger.trace("[TEST] | TEST | orderId={}", testData);
    }

    @Test
    void testLogSpeed() throws InterruptedException {
        ExecutorService executor = Executors.newFixedThreadPool(THREAD_COUNT);
        TestData testData = new TestData(100);

        // 948ms
        runTest(executor, "String concatenation (+)", () -> logWithConcat(testData));
        // 886ms
        runTest(executor, "String.format()", () -> logWithFormat(testData));
        // 19ms
        runTest(executor, "Parameterized logging ({})", () -> logWithParam(testData));

        executor.shutdown();
    }

    private void runTest(ExecutorService executor, String label, Runnable task) throws InterruptedException {
        CountDownLatch latch = new CountDownLatch(THREAD_COUNT);
        long start = System.currentTimeMillis();
        for (int i = 0; i < THREAD_COUNT; i++) {
            executor.submit(() -> {
                for (int j = 0; j < TASK_COUNT; j++) {
                    task.run();
                }
                latch.countDown();
            });
        }
        latch.await();
        long end = System.currentTimeMillis();
        System.out.println(label + ": " + (end - start) + "ms");
    }

    static class TestData {

        private final List<String> data;

        public TestData(int size) {
            this.data = new ArrayList<>();
            for (int i = 0; i < size; i++) {
                data.add(UUID.randomUUID().toString());
            }
        }

        public String getTestDataString() {
            return data.stream().sorted().collect(Collectors.joining(","));
        }

        @Override
        public String toString() {
            return this.getTestDataString();
        }
    }
}

방식	소요 시간
문자열 결합 (+)	948ms
String.format() 사용	886ms
파라미터 포맷팅 ({})	19ms

• +, String.format() 연산자 방식은 로그 레벨에 관계없이 toString()이 호출되고 문자열 결합이 발생
• 파라미터 포맷팅({}) 방식은 로그 레벨이 활성화된 경우에만 포맷팅이 수행되어, toString() 호출이 발생하지 않음

파라미터 포맷팅 방식이 가장 빠르며, 문자열 결합/포맷은 로그 레벨이 비활성화되어 있어도 toString() 호출과 문자열 결합이 발생해 성능이 저하된다.

메서드 호출 문제

{} 포맷팅을 사용하면 문자열 결합 비용은 줄일 수 있지만, 메서드 호출 자체는 여전히 발생한다는 점에서 성능 이슈는 완전히 사라지지 않는다.

private static String getExpensiveDetail(Order order) {
    logger.trace("OrderId={}, detail={}", order.getId(), order.getExpensiveDetail());
}

위 코드처럼 로그 레벨과 무관하게 getExpensiveDetail()이 호출된다면, 불필요한 연산이 수행되어 성능 저하가 발생할 수 있다.

private static void logWithSupplier(Order order) {
    logger.trace("OrderId={}, detail={}", () -> order.getId(), () -> order.getExpensiveDetail());
}

Log4j2는 이를 해결하기 위해 Supplier 기반 지연 평가를 지원하지만, Slf4j는 해당 기능을 제공하지 않기 때문에 isTraceEnabled() 같은 조건문을 명시적으로 사용하여 방지할 수 있다.

메서드 호출 성능 테스트(SlF4J 환경)

위와 동일한 테스트 환경에서 메서드 호출을 포함한 로그 성능을 측정했다.

class LoggerTest extends IntegrationTest {

    private static void logConcatWithMethodCall(TestData testData) {
        logger.trace("[TEST] | TEST | testData=" + testData.getTestDataString());
    }

    private static void logFormatWithMethodCall(TestData testData) {
        logger.trace(String.format("[TEST] | TEST | testData=%s", testData.getTestDataString()));
    }

    private static void logParamWithMethodCall(TestData testData) {
        logger.trace("[TEST] | TEST | orderId={}", testData.getTestDataString());
    }

    private static void logParamWithCheck(TestData testData) {
        if (logger.isTraceEnabled()) {
            logger.trace("[TEST] | TEST | testData={}", testData.getTestDataString());
        }
    }

    @Test
    void testLogSpeedWithMethodCall() throws InterruptedException {
        ExecutorService executor = Executors.newFixedThreadPool(THREAD_COUNT);
        TestData testData = new TestData(100);

        // 1042ms
        runTest(executor, "String concat + method call",
                () -> logConcatWithMethodCall(testData));
        // 1092ms
        runTest(executor, "String.format + method call",
                () -> logFormatWithMethodCall(testData));
        // 947ms
        runTest(executor, "Param-style logging + method call",
                () -> logParamWithMethodCall(testData));
        // 14ms
        runTest(executor, "Level check logging + method call",
                () -> logParamWithCheck(testData));

        executor.shutdown();
    }
}

방식	소요 시간
문자열 결합 + 메서드 호출	1042ms
String.format + 메서드 호출	1092ms
파라미터 포맷팅 + 메서드 호출	947ms
로그 레벨 체크 후 포맷팅 + 메서드 호출	14ms

• 파라미터 포맷팅 방식은 로그 레벨과 관계없이 메서드 호출이 발생하여 성능 저하가 발생
• isTraceEnabled() 조건을 사용한 경우, 로그 레벨이 비활성화되어 있으면 해당 연산 자체가 수행되지 않아 성능 저하가 거의 없음

실전 대응 - 구조화된 포맷 + 연산 최소화

로그 포맷을 강제하고 싶었고, 동시에 로그 레벨이 꺼져 있을 때 불필요한 연산이 발생하지 않도록 막고 싶어, 직접 LogFmt 유틸 클래스를 만들어 사용했다.

• 로그의 도메인과 이벤트명을 명확하게 구분
• 로그 메시지는 Supplier<String>으로 감싸, 로그 레벨이 비활성화되었을 땐 메시지 연산 자체가 발생하지 않도록 처리
• Slf4j 환경이므로 isInfoEnabled() 등의 레벨 체크 사용

public void example() {
    LogFmt.info(
            logger,
            LogDomain.PAYMENT,
            EventType.PAYMENT_STATUS_TO_IN_PROGRESS,
            () -> String.format("orderId=%s", orderId)
    );
}

2025-08-03 12:56:56.129 ... - [3ce5fab6] [PAYMENT] | PAYMENT_STATUS_TO_IN_PROGRESS | orderId=55996af6-e5b5-47e5-ac3c-44508ee6fd6b

LogFmt 클래스

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public class LogFmt {

    private static final String INFO_LOG_FORMAT = "[{}] | {} | {}";
    private static final String INFO_LOG_FORMAT_NO_MESSAGE = "[{}] | {}";

    // ...

    public static void info(Logger logger, LogDomain logDomain, EventType event) {
        if (logger.isInfoEnabled()) {
            logger.info(INFO_LOG_FORMAT_NO_MESSAGE, logDomain.name(), event.name());
        }
    }

    public static void info(Logger logger, LogDomain logDomain, EventType event, Supplier<String> messageSupplier) {
        if (logger.isInfoEnabled()) {
            logger.info(INFO_LOG_FORMAT, logDomain.name(), event.name(), messageSupplier.get());
        }
    }

    // ...
}

불필요한 연산을 막고 도메인과 이벤트 타입을 명확히 구분해, 성능을 해치지 않으면서 흐름을 추적할 수 있는 구조화된 로그를 설계했다.

Tags:

• Payment Platform Project

결제 상태 전환 관리와 재시도 로직을 통한 결제 복구 시스템 구축

2024. 10. 14. - Last update: 2026. 3. 12.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.3.3

[!CAUTION] 이 글은 작성 시점의 구현을 기준으로 하며, 이후 상태 모델과 복구 로직이 전면 재설계되었다. UNKNOWN 상태는 RETRYING으로 대체되었고, QUARANTINED 상태가 추가되었다. 예외 기반 분기는 RecoveryDecision 값 객체로, 하드코딩된 재시도 한도는 RetryPolicy 도메인 객체로 전환되었으며, getStatus 선행 조회 패턴이 도입되었다. 현재 설계는 결제 복구 상태 전이 설계를 참고한다.

배경

최초 구상했던 결제 로직은 결제 정보 검증을 통해 안전한 결제 연동 시스템을 목표로 했지만, 예상치 못한 에러에 대한 처리 로직이 미흡했다.

이를 해결하기 위해 대규모 시스템 설계 기초 — 결제 시스템 파트의 재시도 방식을 참고해 시스템을 재설계하여, 이를 적용해보았다.

기존 프로젝트 문제점

기존 결제 시스템 구현에서 발생할 수 있던 문제점은 다음과 같았다.

1. 결제 승인 중 발생한 에러에 대한 명확한 처리 부재
   • 기존 코드에선 모든 에러에 대해 결제 실패로 처리하고 있었음
   • 그 중 재시도를 통해 해결될 수 있는 에러도 실패로 간주
2. API 지연으로 인한 결제 처리 오류
   • 토스 측에 결제 승인 요청을 보낸 후 응답이 지연되어 타임아웃 발생 가능성 존재
   • 서버 측에서는 지연으로 인해 실패 처리되었으나, 실제로는 토스 측에서 승인 완료하여 금액만 빠져나갈 수 있음
3. 결제 승인 요청 중 서버 중단
   • 결제 승인 요청이 토스 결제 서비스까지 전달되어 실제 결제가 완료되었으나, 서버가 중단되면서 결과를 반환하지 못함
   • 이로 인해 결제는 이미 이루어져 금액이 빠져나갔음에도 불구하고, 시스템에서는 결제가 완료되지 않은 상태로 남아있을 수 있음

해결 방법

1. 재시도 가능/불가능 에러 구분
2. 재시도 로직 구현
3. 결제 상태 전환 관리
4. 멱등키 사용

1. 재시도 가능/불가능 에러 구분

기존 코드에서는 어떤 에러가 발생하든지 동일하게 실패 처리했지만, 에러를 재시도 가능과 불가능 두 유형으로 구분했다.

• 재시도 가능한 에러: 일정 시간 후 재 시도를 통해 해결될 수도 있는 에러
  • 일시적인 네트워크 문제 / 외부 서비스 장애 / API 타임아웃 등
• 재시도 불가능한 에러: 재시도가 불가능한 근본적인 문제
  • 잘못된 요청, 상품 재고 부족 등

2. 재시도 로직 구현

재시도 가능한 에러에 대해 일정 횟수까지 재시도하는 스케줄러를 구현해 결제 성공으로 연결했다.

• 재시도 가능한 특정 결제 상태인 결제 요청에 대해 결제 재시도 요청
• 재시도가 너무 많아져 시스템에 부하가 걸리는 것을 방지하기 위해 재시도 횟수 제한

3. 결제 상태 전환 관리

기존 프로젝트에서는 시작 -> 진행 -> 완료/실패 -> 결제 취소로 순차적으로만 관리되었으나, 재시도 처리를 위한 디테일한 상태 관리가 필요했다.

stateDiagram-v2
    direction TB
%% 상태 정의
state DONE
    state FAILED
state UNKNOWN
state CANCELED

%% 전환 규칙
[*] --> READY
READY --> IN_PROGRESS: 결제 승인 요청 시작
IN_PROGRESS --> DONE: 결제 성공
IN_PROGRESS --> FAILED: 결제 실패
IN_PROGRESS --> UNKNOWN: 재시도 가능 에러 발생
UNKNOWN --> DONE: 재시도
UNKNOWN --> FAILED: 재시도
UNKNOWN --> UNKNOWN: 재시도(일정 횟수 까지만)
DONE --> CANCELED: 결제 취소

%% 스타일 정의 및 적용 (color:#000 추가로 가독성 확보)
classDef blue fill: #E1F0FF, stroke: #7EA6E0, color:#000
classDef red fill: #FADAD8, stroke:#B85450, color: #000
classDef orange fill:#FFE5CC, stroke: #D79B00, color: #000
classDef yellow fill: #FFF2CC, stroke: #D6B656,color: #000

class DONE blue
class FAILED red
class UNKNOWN orange
class CANCELED yellow

• READY: 결제 최초 생성 상태
• IN_PROGRESS: 결제 승인 요청 처리 시작한 상태
• DONE: 결제가 성공적으로 완료된 상태
• FAILED: 결제 실패한 상태
• CANCEL: 결제가 취소된 상태
• UNKNOWN: 에러가 발생하였으나, 재시도를 통해 해결 가능성이 있는 상태

UNKNOWN 상태를 도입해 모든 에러를 즉시 실패 처리하지 않고, 재시도를 통해 결제를 복구할 수 있도록 했다.

4. 멱등키 사용

알 수 없는 상태에 대한 결제 재시도로 인해 동일한 결제가 여러 번 이루어질 수 있어, 멱등키를 이용하여 중복 결제를 방지하여 정확히 한 번만 결제 금액이 빠져나가도록 했다.

• 멱등키 생성: 각 결제 요청 시 고유한 멱등키를 DB에 저장하고, 같은 결제에 대해 다시 요청하면 해당 키로 중복 결제 방지
• 재시도 시 동일 결과 보장: 이미 토스 측에 성공한 결제더라도, 같은 키를 통해 중복 결제 방지

결과

기존 프로젝트에서 발생하던 문제들을 다음과 같이 해결할 수 있었다.

1. 결제 승인 중 발생한 에러에 대한 명확한 처리 부재

모든 에러를 동일하게 처리하여 결제가 실패로 처리하던 부분을 재시도 가능한 에러와 불가능한 에러로 명확하게 구분하여 각각에 맞는 처리를 적용할 수 있게 되었다.

• 재시도 가능 에러: 재시도 로직을 통해 성공으로 처리
• 재시도 불가능한 에러: 근본적인 문제로 인한 에러는 즉시 결제 실패로 처리하여, 사용자에게 정확한 정보 전달

2. API 지연으로 인한 실패

API 응답 지연 시에는 결제를 UNKNOWN 상태로 변경하여, 재시도를 통해 최종적으로 결제 성공으로 이어질 수 있도록 처리할 수 있게 되었다.

• 응답 지연 시 재시도 처리: 토스 측 응답 지연으로 결제가 실패 처리되는 경우, 즉시 실패로 간주하지 않고 재시도할 수 있도록 함
• 중복 결제 방지: 이미 성공했으나 토스측에 결과만 못 받은 경우에도, 멱등키를 사용하여 중복해서 결제되지 않도록 함

3. 결제 승인 요청 중 서버가 중단되는 경우

서버 중단으로 인해 결제가 제대로 처리되지 못하거나 중복 결제가 발생할 수 있었으나, 재시도를 통해 올바른 결제 처리를 보장할 수 있게 되었다.

• 서버 중단 시 복구: IN_PROGRESS 상태로 남아있는 결제들에 대해 결제 요청을 다시 시도
• 중복 결제 방지: (토스 측에 요청을 보냈으나 반환되기 전에 서버가 중단 된 경우)성공한 결제에 대해 중복 결제 방지를 위해 멱등키 사용

세부 구현

1. 재시도 가능/불가능 에러 구분 + 3. 결제 상태 전환 관리

결제 승인 과정에서 발생하는 에러 유형에 따라 시스템이 다르게 처리한다.

flowchart TD
%% 노드 정의
    START([결제 승인 요청])
    STOCK[재고 감소 처리]
    STEP1{결제 시작 처리 성공}
    STEP2{결제 검증 성공}
    STEP3{토스 결제 승인 요청 성공}
    STEP4{재시도 가능 에러 여부}
    SUCCESS[성공]
    DB[(DB)]
%% 흐름 연결
    START --> STOCK
    STOCK -- " 재고 감소 " --> DB
    STOCK --> STEP1
    STEP1 -- " Yes " --> STEP2
    STEP1 -- " No " --> FAIL_PATH
    STEP2 -- " Yes " --> STEP3
    STEP2 -- " No " --> FAIL_PATH
    STEP3 -- " Yes " --> SUCCESS
    STEP3 -- " No " --> STEP4
    STEP4 -- " No " --> FAIL_PATH
    STEP4 -- " Yes " --> UNKNOWN_STATUS
    SUCCESS -- " DONE " --> DB
    UNKNOWN_STATUS["UNKNOWN"] -- " UNKNOWN " --> DB
    FAIL_PATH["FAILED + 재고 복구"] --> DB
%% 스타일링 (글자색 #000 고정 및 고대비 설정)
    classDef standard fill: #F5F5F5, stroke: #333, color: #000
    classDef db fill: #E5E5E5, stroke: #666, color: #000
    classDef white fill: #FFFFFF, stroke: #333, color: #000
    style STEP1 fill: #E1F0E1, stroke: #82B366, color: #000
    style STEP2 fill: #DAE8FC, stroke: #6C8EBF, color: #000
    style STEP3 fill: #FFE6CC, stroke: #D79B00, color: #000
    style STEP4 fill: #FFF2CC, stroke: #D6B656, color: #000
%% 경로 텍스트 가독성 확보 (다크모드에서도 선명한 채도 사용)
    style FAIL_PATH fill: none, stroke: none, color: #FF3333
    style UNKNOWN_STATUS fill: none, stroke: none, color: #D44040

TossPaymentErrorCode.java

토스 에러 코드를 Enum으로 정의하고 성공/재시도 가능 여부 판단 메서드를 구현했으며, 추가적으로 타임아웃 관련 에러 코드를 추가해 재시도 가능한 에러로 포함했다.

TossPaymentErrorCode.java

public enum TossPaymentErrorCode {

    ALREADY_PROCESSED_PAYMENT(400, "이미 처리된 결제 입니다."),
    // ...

    UNKNOWN_PAYMENT_ERROR(500, "결제에 실패했어요. 같은 문제가 반복된다면 은행이나 카드사로 문의해주세요."),
    UNKNOWN(500, "알 수 없는 에러입니다."),
    NETWORK_ERROR(500, "네트워크 오류가 발생했습니다. 잠시 후 다시 시도해주세요."); // 타임아웃 처리를 위한 별도로 추가한 에러

    //...

    public boolean isSuccess() {
        return this == ALREADY_PROCESSED_PAYMENT;
    }

    public boolean isRetryableError() {
        return switch (this) {
            case PROVIDER_ERROR, FAILED_PAYMENT_INTERNAL_SYSTEM_PROCESSING,
                 FAILED_INTERNAL_SYSTEM_PROCESSING, UNKNOWN_PAYMENT_ERROR,
                 UNKNOWN, NETWORK_ERROR -> true;
            default -> false;
        };
    }

    public boolean isFailure() {
        return !isSuccess() && !isRetryableError();
    }
}

PaymentProcessorUseCase.java

결제 결과를 성공/재시도 가능/실패로 판단하며, 호출부는 결과에 따라 성공 객체 또는 Checked Exception을 반환하도록 하였다.

PaymentProcessorUseCase.java

public class PaymentProcessorUseCase {

    // ...

    public TossPaymentInfo confirmPaymentWithGateway(PaymentConfirmCommand paymentConfirmCommand)
            throws PaymentTossRetryableException, PaymentTossNonRetryableException {

        // ... 토스 측에 결제 승인 요청 및 반환

        PaymentConfirmResultStatus paymentConfirmResultStatus = tossPaymentInfo.getPaymentConfirmResultStatus();

        // 상태에 따라 처리
        return switch (paymentConfirmResultStatus) {
            // 1. 성공
            case PaymentConfirmResultStatus.SUCCESS -> tossPaymentInfo;
            // 2. 재시도 가능한 에러 - Checked Exception
            case PaymentConfirmResultStatus.RETRYABLE_FAILURE ->
                    throw PaymentTossRetryableException.of(PaymentErrorCode.TOSS_RETRYABLE_ERROR);
            // 3. 재시도 불가능한 에러 - Checked Exception
            case PaymentConfirmResultStatus.NON_RETRYABLE_FAILURE ->
                    throw PaymentTossNonRetryableException.of(PaymentErrorCode.TOSS_NON_RETRYABLE_ERROR);
        };
    }

    // ...
}

PaymentConfirmServiceImpl.java

Checked Exception으로 호출부가 에러 처리를 강제받으며, 에러 유형별로 다음과 같이 처리했다.

예외 상황	재시도 가능	결제 상태 처리	재고 처리
1. 재고 차감 중 오류	X	실패 처리	복구 불필요
2. 이미 처리된 결제에 대한 중복 요청	X	실패 처리	재고 복구
3. 외부 결제사의 일시적인 오류	O	알 수 없음 상태로 변경	재고 유지
4. 외부 결제사의 복구 불가능 오류	X	실패 처리	재고 복구
5. 결제 검증 또는 기타 시스템 오류	X	실패 처리	재고 복구

PaymentConfirmServiceImpl.java

public class PaymentConfirmServiceImpl implements PaymentConfirmService {

    // ...

    @Override
    public PaymentConfirmResult confirm(PaymentConfirmCommand paymentConfirmCommand) {
        // 1. 결제 이벤트 조회
        PaymentEvent paymentEvent = paymentLoadUseCase.getPaymentEventByOrderId(
                paymentConfirmCommand.getOrderId()
        );

        try {
            // 2. 재고 차감 - 재고 부족 에러 발생 가능
            orderedProductUseCase.decreaseStockForOrders(paymentEvent.getPaymentOrderList());
        } catch (PaymentOrderedProductStockException e) {   // 에러 1: 재고 부족 에러 발생
            handleStockFailure(paymentEvent);               // FAIL 처리(재고 중 일어난 에러로, 감소가 일어나지 않았으므로 복구 필요 없음)
            throw PaymentTossConfirmException.of(PaymentErrorCode.ORDERED_PRODUCT_STOCK_NOT_ENOUGH);
        }

        try {
            // 3. 결제 시작 처리 - 결제 시작 상태 검증 중 에러 발생 가능
            paymentProcessorUseCase.executePayment(paymentEvent, paymentConfirmCommand.getPaymentKey());

            // 4. 결제 검증 - 결제 검증 중 에러 발생 가능
            // 5. 토스 결제 승인 요청 - 토스 측 재시도 가능/불가능한 에러 발생 가능
            // 6. 결제 완료 처리
            PaymentEvent completedPayment = processPayment(paymentEvent, paymentConfirmCommand);

            // 7. 결제 완료 결과 반환
            // ...
        } catch (PaymentStatusException e) {                // 에러 2: 이미 요청이 진행 된 건에 대한 요청
            handleNonRetryableFailure(paymentEvent);        // FAIL 처리 + 재고 복구
            throw e;
        } catch (PaymentTossRetryableException e) {         // 에러 3: 토스 측 재시도 가능한 에러 발생
            handleRetryableFailure(paymentEvent);           // UNKNOWN 상태로 변경 + 재고 그대로 유지
            throw PaymentTossConfirmException.of(PaymentErrorCode.TOSS_RETRYABLE_ERROR);
        } catch (PaymentTossNonRetryableException e) {      // 에러 4: 토스 측 재시도 불가능한 에러 발생
            handleNonRetryableFailure(paymentEvent);        // FAIL 처리 + 재고 복구
            throw PaymentTossConfirmException.of(PaymentErrorCode.TOSS_NON_RETRYABLE_ERROR);
        } catch (Exception e) {                             // 에러5: 결제 검증 중 에러 등 기타 에러 발생
            handleUnknownException(paymentEvent);           // FAIL 처리 + 재고 복구
            throw e;
        }
    }

    // ...
}

2. 재시도 로직 구현

재시도 가능으로 구분 된 에러에 대해, 재시도 로직을 구현하여 두 가지 상태에 대해 결제 성공으로 이어질 수 있도록 구현하였다.

1. UNKNOWN: 재시도 가능 에러 또는 타임아웃으로 결과를 받지 못한 상태
2. IN_PROGRESS: 결제 승인을 시작했지만 결과를 받지 못한 상태

PaymentRecoverServiceImpl.java

// PaymentRecoverServiceImpl
public class PaymentRecoverServiceImpl implements PaymentRecoverService {

    // 1. 재시도 가능한 결제 이벤트 조회 후 아래 로직 수행
    private void processRetryablePaymentEvent(PaymentEvent retryablePaymentEvent) {
        try {
            // 2. 재시도 가능 여부 횟수 검증 - 재시도 불가능 에러 발생 가능
            if (!retryablePaymentEvent.isRetryable(localDateTimeProvider.now())) {
                throw PaymentRetryableValidateException.of(PaymentErrorCode.RETRYABLE_VALIDATION_ERROR);
            }

            // 3. 재시도 횟수 증가
            paymentProcessorUseCase.increaseRetryCount(retryablePaymentEvent);

            // ...

            // 4. 토스 결제 승인 요청 재시도 후 완료 처리 - 토스 측 재시도 가능/불가능한 에러 발생 가능
            TossPaymentInfo tossPaymentInfo = paymentProcessorUseCase.confirmPaymentWithGateway(
                    paymentConfirmCommand
            );
            paymentProcessorUseCase.markPaymentAsDone(
                    retryablePaymentEvent,
                    tossPaymentInfo.getPaymentDetails().getApprovedAt()
            );
        } catch (PaymentRetryableValidateException              // 에러 1: 재시도 불가능한 상태 에러 발생
                 | PaymentTossNonRetryableException e) {        // 에러 2: 토스 측 재시도 불가능한 에러 발생
            handleNonRetryableFailure(retryablePaymentEvent);   // FAIL 처리 + 재고 복구
        } catch (PaymentTossRetryableException e) {             // 에러 3: 토스 측 재시도 가능한 에러 발생
            handleRetryableFailure(retryablePaymentEvent);      // UNKNOWN 상태로 변경
        }
    }

    // ...
}

재시도 검증 후, 기존 결제 승인 요청과 같이 토스 측에 재시도 요청을 보내도록 처리하였으며, 결과에 따라 다음과 같이 처리한다.

flowchart TD
%% 노드 정의
    START([복구 로직 시작])
    DB[(DB)]
    FETCH[재시도 가능 결제 조회]
    CHECK_COUNT{재시도 횟수 검증}
    INC_COUNT[재시도 횟수 증가]
    REQUEST[결제 승인 요청]
    CHECK_SUCCESS{성공 여부}
    CHECK_RETRY{재시도 가능 여부}
    DONE[Done 처리]:::green
    FAILED[Failed 처리]:::red
    UNKNOWN[Unknown 처리]:::yellow
%% 흐름 연결
    START --> FETCH
    DB -. " 일정 시간 지난 IN_PROGRESS\nUNKNOWN 상태 조회 " .-> FETCH
    FETCH --> CHECK_COUNT
    CHECK_COUNT -- " No " --> FAILED
    CHECK_COUNT -- " Yes " --> INC_COUNT
    INC_COUNT --> REQUEST
    REQUEST --> CHECK_SUCCESS
    CHECK_SUCCESS -- " Yes " --> DONE
    CHECK_SUCCESS -- " No " --> CHECK_RETRY
    CHECK_RETRY -- " No " --> FAILED
    CHECK_RETRY -- " Yes " --> UNKNOWN
    UNKNOWN --> DB
%% 스타일 정의 (모든 상태 노드에 color:#000 적용)
    classDef green fill: #D5E8D4, stroke: #82B366, color: #000
    classDef red fill: #F8CECC, stroke: #B85450, color: #000
    classDef yellow fill: #FFF2CC, stroke: #D6B656, color: #000
    style DB fill: #F5F5F5, stroke: #666, color: #000
    style CHECK_COUNT fill: #FFE6CC, stroke: #D79B00, color: #000
    style CHECK_SUCCESS fill: #FFE6CC, stroke: #D79B00, color: #000
    style CHECK_RETRY fill: #FFE6CC, stroke: #D79B00, color: #000

• 성공: 재시도 성공 후 결제 완료 처리(이미 재고가 차감되어 있으므로, 재고 감소나 복구는 필요 없음)
• 토스 측 재시도 불가능한 에러: 해당 결제에 대해 실패 처리 + 재고 복구
• 토스 측 재시도 가능 에러: UNKNOWN 상태로 변경
• 재시도 횟수 초과: 해당 결제에 대해 실패 처리 + 재고 복구

재시도 횟수를 초과하면 UNKNOWN 상태를 유지하지 않고 결제 실패로 처리해 무한 재시도를 방지했다.

4. 멱등키 사용

서버 장애나 네트워크 문제로 동일 결제가 중복 시도될 수 있어, 멱등키를 도입해 중복 결제를 방지했다.

• 이번 프로젝트에서는 결제 이벤트 생성 시 만들어지는 고유한 orderId를 멱등키로 사용
• UUID를 사용하여 고유한 키임을 보장

멱등키는 토스 결제 서버 요청 시 HTTP 헤더에 포함해 전송하며, 동일 요청이 중복 처리되지 않도록 보장한다.

결론

항목	기존 시스템 문제점	개선된 시스템 해결 방안
에러 처리	모든 에러를 동일하게 결제 실패로 처리	재시도 가능/불가능 에러로 구분하여 각각에 맞는 처리 도입
API 응답 지연	응답 지연 시 결제 실패로 처리	UNKNOWN 상태로 관리하고 재시도를 통해 최종적으로 성공 처리
결제 도중 서버 중단	서버 중단으로 결제 완료 여부를 알 수 없고, 중복 결제 발생 가능성 존재	멱등키를 사용하여 중복 결제 방지 및 재시도 로직을 통한 결제 완료 처리

한계점 및 추가 개선 사항

UNKNOWN 상태 추가로, 결제 상태 추적이 어려운 한계점이 존재하는데, 이를 보완하기 위한 추가적인 개선이 이루어진다면, 결제 시스템의 완성도를 더욱 높일 수 있을 것으로 기대된다.

• 정확한 상태 변경 이력 추적 부족 -> 결제 이력 저장으로 해결
  • 결제 상태가 변경될 때마다 상태 변경 이력을 추적하고, 상태 변경에 따른 추가적인 로그를 남기지 않아 추후 에러에 대한 추적이 어려울 수 있음
• 원장 및 지갑 관리 시스템 부재
  • 책에서 제시한 것처럼 원장/지갑 관리 기능이 포함되지 않아 결제 내역과 잔액 간의 정확한 일치 여부를 추적할 수 없음

참고

• Design Payment System

Tags:

• Payment Platform Project

외부 의존성 제어를 통한 결제 프로세스 다양한 시나리오 검증

2024. 10. 1. - Last update: 2026. 3. 11.

hyoguoo

Backend Engineer

실행 환경: Java 21, Spring Boot 3.3.3, JUnit 5

결제 시스템은 서비스 신뢰성과 직결되므로, 다양한 시나리오를 검증하는 테스트 코드가 필수적이다.

• 단위 테스트: 개별 도메인 및 서비스 로직을 대상으로 세부 로직 검증
• 통합 테스트: 실제 결제 흐름을 따라 다양한 예외 상황에 대응하는 테스트 작성

단위 테스트와 통합 테스트로 구분해 작성했으며, 토스 결제 시스템의 외부 의존성 제어가 핵심 과제였다.

참고: 토스 실제 결제 승인은 클라이언트 SDK를 통해 결제 요청을 먼저 수행해야 하며, 그 후에 결제 승인을 진행해야 한다.

결제 승인 과정에서 발생할 수 있는 다양한 시나리오에 대응할 수 있고, 신뢰성 높은 결제 프로세스를 보장하기 위해 여러 테스트 전략을 적용해보았다.

테스트 코드 작성 목표

테스트를 통해 보장하고자 한 주요 목표는 다음과 같다.

1. 결제 승인 과정 중 발생할 수 있는 다양한 시나리오 검증 및 도메인/서비스 로직 신뢰성 확보
2. 인프라스트럭처 영역은 페이크 또는 목 객체를 활용하여 효율적인 테스트 환경 구성
3. 멀티 스레드 테스트로 기본적인 동시성 이슈 검증 및 타임아웃 시나리오에 대한 검증

1. 결제 승인 과정 중 발생할 수 있는 다양한 시나리오 검증 및 도메인/서비스 로직 신뢰성 확보

결제 승인 과정은 복잡한 절차적 흐름과 다양한 예외 상황을 포함하므로, 파라미터화된 테스트로 여러 시나리오를 한번에 검증했다.

• 단일 케이스를 넘어 여러 파라미터를 조합한 테스트를 통해 다양한 시나리오 및 상태값 검증

• 서비스 로직에서 발생 가능한 에러에 대한 처리 확인

• 단순 성공 케이스 뿐만 아니라, 예외 상황이나 여러 상태 값에 대한 다양한 케이스를 고려하여 테스트 코드 작성

• PaymentEventTest.java

class PaymentEventTest {

    @ParameterizedTest
    @CsvSource({
            "1, validPaymentKey, 15000, order123, INVALID_TOTAL_AMOUNT",
            "2, invalidPaymentKey, 15000, order123, INVALID_PAYMENT_KEY",
            "1, validPaymentKey, 14000, wrongOrderId, INVALID_ORDER_ID"
    })
    @DisplayName("다양한 조건에서 검증 실패 시 PaymentValidException 예외가 발생한다.")
    void validate_InvalidCases(
            Long userId,
            String paymentKey,
            int amount,
            String orderId
    ) {
        PaymentEvent paymentEvent = defaultPaymentEvent();

        // ...

        assertThatThrownBy(
                () -> paymentEvent.validateCompletionStatus(paymentConfirmCommand, paymentInfo))
                .isInstanceOf(PaymentValidException.class);
    }

    @ParameterizedTest
    @EnumSource(value = TossPaymentStatus.class, names = {
            "CANCELED", "EXPIRED", "PARTIAL_CANCELED", "ABORTED"
    })
    @DisplayName("결제 상태가 유효하지 않은 경우 PaymentStatusException 예외가 발생한다.")
    void validate_InvalidPaymentStatus(TossPaymentStatus tossPaymentStatus) {
        PaymentEvent paymentEvent = defaultPaymentEvent();

        // ...

        assertThatThrownBy(
                () -> paymentEvent.validateCompletionStatus(paymentConfirmCommand, paymentInfo))
                .isInstanceOf(PaymentStatusException.class);
    }
}

서비스 로직에서 Toss API 통신 중 발생할 수 있는 모든 에러 코드에 대한 처리도 함께 테스트했다.

• PaymentGatewayServiceImplErrorCaseTest.java

class PaymentGatewayServiceImplErrorCaseTest extends IntegrationTest {

    // ...

    @ParameterizedTest(name = "{index}: Test with TossPaymentErrorCode={0}")
    @EnumSource(TossPaymentErrorCode.class)
    @DisplayName("TossPaymentErrorCode에 따라 Header를 설정하고 결제 확인 결과를 검증한다.")
    void confirmPayment_withTossPaymentErrorCode(TossPaymentErrorCode errorCode) {
        // given
        String uuid = new SystemUUIDProvider().generateUUID();

        ReflectionTestUtils.invokeMethod(httpOperator, "addHeader", "TossPayments-Test-Code", errorCode.name());

        // ...

        // when
        TossPaymentInfo tossPaymentInfo = paymentGatewayService.confirmPayment(tossConfirmCommand, uuid);
        PaymentConfirmResultStatus paymentConfirmResultStatus = tossPaymentInfo.getPaymentConfirmResultStatus();

        // then
        Assertions.assertThat(paymentConfirmResultStatus)
                .isEqualTo(getExpectedResultStatus(errorCode));
    }

    // ...

    @TestConfiguration
    static class TestConfig {

        @Bean
        public HttpOperator httpOperator() {
            return new AdditionalHeaderHttpOperator();
        }
    }
}

헤더에 특정 에러 코드를 추가하면 토스 측이 에러를 반환하는 테스트 API를 활용해 에러 상황을 시뮬레이션하여, 예외 상황에 대한 처리와 에러별 재요청 가능/불가능 여부를 검증했다.

2. 인프라스트럭처 영역은 페이크 또는 목 객체를 활용하여 효율적인 테스트 환경 구성

토스 API 결제 승인은 클라이언트 SDK 선행 요청이 필요해 통합 테스트 진행이 어려웠는데, 페이크 객체로 외부 의존성을 제거해 이 문제를 해결했다.

• FakeTossHttpOperator.java

public class FakeTossHttpOperator implements HttpOperator {

    // ...

    // Reflection을 통해 호출되는 메서드

    @SuppressWarnings("unused")
    public void setDelayRange(int minDelayMillis, int maxDelayMillis) {
        this.minDelayMillis = minDelayMillis;
        this.maxDelayMillis = maxDelayMillis;
    }

    @SuppressWarnings("unused")
    public void addErrorInPostRequest(String code, String message) {
        this.code = code;
        this.message = message;
        this.isErrorInPostRequest = true;
    }

    @SuppressWarnings("unused")
    public void clearErrorInPostRequest() {
        this.isErrorInPostRequest = false;
    }

    @SuppressWarnings("java:S2925")
    private void simulateNetworkDelay() {
        long delay = minDelayMillis + (long) (Math.random() * (maxDelayMillis - minDelayMillis));
        try {
            TimeUnit.MILLISECONDS.sleep(delay);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    private void throwError() {
        // ...
    }

    // ...

    @Override
    public <T, E> E requestPost(String url, Map<String, String> httpHeaderMap, T body, Class<E> responseType) {
        // 네트워크 지연 시뮬레이션
        simulateNetworkDelay();

        // 에러 발생 시뮬레이션
        if (isErrorInPostRequest) {
            throwError();
        }

        // ...

        // 실제 API 호출 없이 응답 반환
        return responseType.cast(tossPaymentApiResponse);
    }
}

위 구현체는 기존 실제 요청을 보내는 구현체의 인터페이스인 HttpOperator를 구현했지만 실제 네트워크 요청 대신, 결제 승인을 위한 객체로 만들었다.

1. 실제 API 호출 X: 외부 API 호출 없이 승인 결과 반환
2. 네트워크 지연 시뮬레이션: 실제 환경과 유사하게 네트워크 지연 시간 설정 가능
3. 에러 발생 시뮬레이션: 특정한 오류 코드와 메시지를 지정한 에러 발생 가능

페이크 객체는 @TestConfiguration으로 테스트 환경에서만 사용되도록 설정하고, Reflection으로 테스트 코드에서 호출한다.

• PaymentControllerTest.java

class PaymentControllerTest extends IntegrationTest {


    @Test
    @DisplayName("Payment Confirm 요청이 성공하면 결제가 승인되고 DONE / SUCCESS 상태로 변경되면서 재고가 감소한다.")
    void confirmPayment_Success() throws Exception {
        // ...

        ReflectionTestUtils.invokeMethod(httpOperator, "clearErrorInPostRequest"); // 에러 없음 => 성공

        // ...
    }

    @Test
    @DisplayName("Payment Confirm 요청 중 재시도 가능 오류가 발생하면 결제는 실패하고 UNKNOWN / UNKNOWN 상태로 변경되면서 재고는 감소된 상태로 유지된다.")
    void confirmPayment_Failure_RetryableError() throws Exception {
        // ...

        ReflectionTestUtils.invokeMethod(httpOperator, "addErrorInPostRequest",
                TossPaymentErrorCode.PROVIDER_ERROR.name(), // 재시도 가능한 오류 코드
                TossPaymentErrorCode.PROVIDER_ERROR.getDescription()
        );

        // ...
    }


    @Test
    @DisplayName("Payment Confirm 요청 중 재시도 불가능 오류가 발생하면 결제는 실패하고 FAILED / FAIL 상태로 변경되면서 재고는 다시 복구된다.")
    void confirmPayment_Failure_NonRetryableError() throws Exception {
        // ...

        ReflectionTestUtils.invokeMethod(httpOperator, "addErrorInPostRequest",
                TossPaymentErrorCode.INVALID_STOPPED_CARD.name(), // 재시도 불가능한 오류 코드
                TossPaymentErrorCode.INVALID_STOPPED_CARD.getDescription()
        );

        // ...
    }


    @TestConfiguration
    static class TestConfig {

        @Bean
        public HttpOperator httpOperator() {
            return new FakeTossHttpOperator();
        }
    }
}

페이크 객체를 활용해 외부 API 의존성과 절차적 선행 조건을 제거했고, 다양한 결제 시나리오를 간결하게 테스트했다.

3. 멀티 스레드 테스트로 기본적인 동시성 이슈 검증 및 타임아웃 시나리오에 대한 검증

여러 사용자가 동일한 상품을 동시에 주문하거나 외부 API 타임아웃이 발생할 수 있기 때문에 이러한 상황에 대한 검증이 필요하다.

동시성 이슈 검증

동시성 문제는 여러 요청이 동시에 동일한 리소스를 수정할 때 발생하며, 멀티 스레드 테스트를 통해 상황을 시뮬레이션하여 주문 수량과 재고가 정확히 관리되는지 확인했다.

• PaymentConfirmConcurrentTest.java

@Tag("TooLongIntegrationTest")
class PaymentConfirmConcurrentTest extends IntegrationTest {

    @ParameterizedTest
    @CsvSource({
            "1000, 1000, 1000, 0, 0",   // 재고와 주문 수량이 일치
            "1000, 999, 999, 0, 1",     // 주문 수량이 재고보다 적음
            "1000, 1001, 1000, 1, 0",   // 주문 수량이 재고보다 많음
            "1000, 1050, 1000, 50, 0",  // 재고 초과 주문 (50개 초과 주문 실패)
            "1200, 1000, 1000, 0, 200", // 재고가 1200개, 주문 수량은 1000개 (200개 남음)
    })
    @DisplayName("멀티스레드로 Payment Confirm 요청 시 결제 승인 처리와 상태가 동시성에 맞게 처리된다.")
    void concurrentConfirmPayment_withStock(
            int stock,
            int orderCount,
            int expectedSuccess,
            int expectedFail,
            int expectedStock
    ) {
        // ...

        executeConcurrentActions(orderIndex -> {
            try {

                // ...

                MvcResult mvcResult = mockMvc.perform(
                        post("/api/v1/payments/confirm")
                                .contentType(MediaType.APPLICATION_JSON)
                                .content(objectMapper.writeValueAsString(confirmRequest))
                ).andReturn();
                if (mvcResult.getResponse().getStatus() == 200) {
                    successCount.incrementAndGet();
                } else {
                    failCount.incrementAndGet();
                }
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }, orderCount);

        // then
        Product updatedProduct = jpaProductRepository.findById(1L).orElseThrow().toDomain();
        assertThat(successCount.get()).isEqualTo(expectedSuccess);
        assertThat(failCount.get()).isEqualTo(expectedFail);
        assertThat(updatedProduct.getStock()).isEqualTo(expectedStock);
    }

    @TestConfiguration
    static class TestConfig {

        @Bean
        public HttpOperator httpOperator() {
            return new FakeTossHttpOperator();
        }
    }
}

멀티스레드 수행 중엔 FakeTossHttpOperator로 외부 API 호출 없이 테스트를 구성했다.(실제 테스트 키로 부하 테스트를 수행하면 토스 측에서 일정 시간 동안 요청을 제한한다.)

타임아웃 시나리오 검증

외부 네트워크 지연으로 인한 타임아웃 문제를 검증하기 위해 결제 승인 요청에 대해 일정 지연을 설정하여 해당 상황에서도 모든 결제 요청이 적절하게 처리되는지 검증하는 테스트를 작성했다.

@Tag("TooLongIntegrationTest")
class PaymentConfirmConcurrentTest extends IntegrationTest {

    @ParameterizedTest
    @CsvSource({
            "500, 1000",
            "1000, 3000",
            "3000, 7000",
    })
    @DisplayName("멀티스레드로 Payment Confirm 요청 시 결제 승인 처리와 상태가 동시성에 맞게 처리된다.")
    void confirmPayment_withTimeout(
            int minDelayMills,
            int maxDelayMills
    ) {
        // ...

        // 네트워크 지연 설정
        ReflectionTestUtils.invokeMethod(httpOperator, "setDelayRange", minDelayMills, maxDelayMills);

        executeConcurrentActions(orderIndex -> {
            try {

                // ...

                MvcResult mvcResult = mockMvc.perform(
                        post("/api/v1/payments/confirm")
                                .contentType(MediaType.APPLICATION_JSON)
                                .content(objectMapper.writeValueAsString(confirmRequest))
                ).andReturn();
                if (mvcResult.getResponse().getStatus() == 200) {
                    successCount.incrementAndGet();
                } else {
                    failCount.incrementAndGet();
                }
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }, orderCount);

        // then
        Product updatedProduct = jpaProductRepository.findById(1L).orElseThrow().toDomain();
        assertThat(successCount.get()).isEqualTo(expectedSuccess);
        assertThat(failCount.get()).isEqualTo(expectedFail);
        assertThat(updatedProduct.getStock()).isEqualTo(expectedStock);
    }

    @TestConfiguration
    static class TestConfig {

        @Bean
        public HttpOperator httpOperator() {
            return new FakeTossHttpOperator();
        }
    }
}

결론

결제 시스템은 안정성이 최우선이기 때문에, 발생 가능한 다양한 시나리오와 문제를 테스트하는 것이 다른 도메인보다 더 중요하다고 생각한다.

단위 테스트와 통합 테스트로 로직과 전체 흐름을 검증했고, 멀티 스레드 테스트로 동시성 및 타임아웃 처리까지 확인했다.

1. 결제 승인 과정 검증: 파라미터화된 테스트로 다양한 상황별 예외 처리를 검증
2. 효율적인 테스트 환경: FakeTossHttpOperator로 외부 API 호출을 대체해 유연한 테스트 환경 구성
3. 동시성·타임아웃 처리: 멀티 스레드 테스트로 실서비스 환경에서 발생할 수 있는 문제 사전 검증

단, 이번 테스트는 기본적인 동시성·타임아웃 수준의 검증이며, 정밀한 부하 테스트는 전용 툴을 통해 추가로 진행해야 한다.

Tags:

• Payment Platform Project

트랜잭션 범위 최소화를 통한 성능 및 안정성 향상

2024. 2. 23. - Last update: 2026. 3. 11.

hyoguoo

Backend Engineer

실행 환경: Java 17, Spring Boot 3.1.5, MySQL 8.0.33
[!CAUTION] 이 글은 복구 로직 적용 전의 내용을 담고 있으며, 현재 적용된 내용은 마지막 섹션에 기술

MySQL 관련 공부를 하던 중, 트랜잭션 범위의 중요성에 대해 학습하게 되었고, 이를 개선하기 위해 트랜잭션 범위 최소화 작업을 진행하였다.

• 커넥션 풀 부족
  • 커넥션 풀은 데이터베이스와 연결된 커넥션을 미리 생성해두고, 요청이 들어올 때마다 커넥션을 빌려주고 반납받는 방식으로 동작한다.
  • 커넥션 풀에는 최대 커넥션 수가 정해져 있으며, 이를 초과하게 되면 대기열에 들어가게 된다.
  • 트랜잭션 범위가 넓어지면 커넥션을 오래 사용하게 되고, 이로 인해 커넥션 풀의 커넥션 수가 부족해지게 되어 대기열에 들어가게 된다.
  • 이로 인해 다른 요청들이 대기하게 되고, 이는 서비스의 응답 시간을 느리게 하게 된다.
• 잠금 대기
  • 만약 트랜잭션에서 레코드의 잠금을 거는 경우, 넓어진 트랜잭션 범위만큼 점유하는 시간이 길어지게 된다.
  • 해당 레코드를 다른 트랜잭션에서 사용하려고 할 때, 다른 트랜잭션들이 락을 대기하게 되고, 이는 데드락이 발생할 확률을 높이게 된다.

최근에 읽었던 Real MySQL 8.0 서적에서도 트랜잭션 범위를 최소화하라고 권장하고 있으며, 특히 네트워크 작업이 있는 요청은 반드시 트랜잭션에서 배제해야 한다고 말하고 있다.

넓은 범위에 걸친 트랜잭션

이전에 개발한 결제 연동 시스템에서 하나의 트랜잭션에서 네트워크 요청을 포함한 많은 작업을 수행하고 있었다.(전체적인 플로우는 링크 참고)

OrderService.java

public class OrderService {

    // ...

    @Transactional // 해당 메서드 전체에 걸친 트랜잭션 범위
    public OrderConfirmResponse confirmOrder(OrderConfirmRequest orderConfirmRequest) {
        // 1. OrderInfo + Product + User Fetch Join 조회(X-LOCK)
        OrderInfo orderInfo =
                this.getOrderInfoByOrderPessimisticLock(orderConfirmRequest.getOrderId());
        // 2. 재고 감소
        productService.reduceStock(orderInfo.getProduct().getId(), orderInfo.getQuantity());

        // 3. TossPayment 측 결제 정보 조회(외부 API)
        TossPaymentResponse paymentInfo = paymentService.getPaymentInfoByOrderId(
                orderConfirmRequest.getOrderId()
        );

        // 4. 결제 정보 검증
        orderInfo.validateInProgressOrder(paymentInfo, orderConfirmRequest);

        // 5. TossPayment 측 결제 승인(외부 API)
        TossPaymentResponse confirmPaymentResponse =
                paymentService.confirmPayment(
                        TossConfirmRequest.createByOrderConfirmRequest(orderConfirmRequest)
                );

        // 6. 주문 확정 상태 변경
        OrderInfo confirmedOrderInfo = orderInfo.confirmOrder(
                confirmPaymentResponse,
                orderConfirmRequest
        );

        return new OrderConfirmResponse(confirmedOrderInfo);
    }

    // ...
}

1. 하나의 트랜잭션 범위에 포함된 모든 로직
   • 실질적으로 데이터베이스의 트랜잭션이 필요한 부분은 초록색으로 표시된 부분 뿐이지만 전체 로직을 트랜잭션 범위로 감싸고 있음
2. 불필요한 테이블의 레코드까지 X-LOCK을 통해 조회
   • 재고 감소 동시성 처리를 위해 필요한 테이블은 Product 레코드 뿐이지만, 불필요하게 OrderInfo과 User의 레코드까지 잠금 설정
   • 여기서 얻은 LOCK을 로직이 끝나는 시점까지 유지하게 되어 다른 트랜잭션들이 대기하게 되어 데드락 발생 확률 상승
3. 외부 API 요청을 트랜잭션 범위 내에서 수행
   • 외부 API 호출은 네트워크 작업을 수반하여 시간적 범위 증가
   • 트랜잭션을 유지하는 시간이 길어지게 되어 다른 트랜잭션들의 대기 시간 증가하여 전체 서비스 응답 시간 증가
   • 최악의 경우 외부 API에서 응답이 늦게 오거나 Time Out 되면 기하급수적으로 서비스 응답 시간 증가

외부 API 응답이 늦은 경우 발생하는 문제

가장 문제가 될 수 있는 부분은 외부 API 응답이 늦게 오거나 Time Out 되는 경우인데, 결제 승인 요청 API 응답이 늦게 오는 경우를 시뮬레이션하여 확인해보았다.

MockController.java

// Mock Server를 띄워 승인 요청에 대한 응답 수신 시 3초 대기하도록 설정
@RestController
@RequiredArgsConstructor
public class MockController {

    // ...

    @PostMapping("/confirm")
    public TossPaymentResponse confirmPayment(@RequestBody TossConfirmRequest tossConfirmRequest) {
        // time out
        try {
            Thread.sleep(3000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        // ...
    }
}

동시에 10개의 주문 승인 요청을 보내는 동시성 테스트를 수행한 결과는 다음과 같다.

Lock 해제를 대기하는 나머지 트랜잭션

Lock을 가진 트랜잭션이 네트워크 지연을 기다리는 동안 다른 스레드들도 Lock 해제를 대기하는 것을 확인할 수 있다.

동시에 10개의 주문 승인 요청 테스트 결과

3초씩 대기하게 되어 10개 밖에 안 되는 요청이 30초가 넘게 걸리게 되었으며, 10개보다 조금 더 많은 개수인 20개로만 설정했을 땐 Time Out으로 마지막 몇 개의 요청은 실패했다.

트랜잭션 범위 내에 있는 외부 API 요청 배제

문제를 해결하기 위해 네트워크에 영향을 받는 외부 API 요청을 트랜잭션 범위 밖으로 배제하고, Database에 대한 작업만 트랜잭션 범위 내에서 수행하도록 변경하였다.

OrderService.java

public class OrderService {

    // ...

    // @Transactional 어노테이션 제거하여 트랜잭션 X
    public OrderConfirmResponse confirmOrder(OrderConfirmRequest orderConfirmRequest) {
        // 1. 락 없이 단순 조회
        OrderInfo orderInfo = this.getOrderInfoByOrderId(orderConfirmRequest.getOrderId());

        // 2. 재고 감소 및 Database Commit
        productService.reduceStockWithCommit(
                orderInfo.getProduct().getId(),
                orderInfo.getQuantity()
        );

        // 3. TossPayment 측 결제 정보 조회(외부 API)
        TossPaymentResponse paymentInfo = paymentService.getPaymentInfoByOrderId(
                orderConfirmRequest.getOrderId()
        );

        // 4. 결제 정보 검증
        orderInfo.validateInProgressOrder(paymentInfo, orderConfirmRequest);

        // 5. TossPayment 측 결제 승인(외부 API)
        TossPaymentResponse confirmPaymentResponse =
                paymentService.confirmPayment(
                        TossConfirmRequest.createByOrderConfirmRequest(orderConfirmRequest)
                );

        // 6. 주문 확정 상태 변경
        OrderInfo confirmedOrderInfo = orderInfo.confirmOrder(
                confirmPaymentResponse,
                orderConfirmRequest
        );
        orderInfoRepository.save(confirmedOrderInfo); // @Transactional이 없으므로 명시적으로 저장

        // WARNING!! 2번 이후에 에러 발생 시, 2번에서 발생한 재고 감소 건이 롤백되지 않음
        return new OrderConfirmResponse(confirmedOrderInfo);
    }

    // ...
}

하지만 2번에서 재고 감소 이후 에러가 발생 시 재고 감소 건이 롤백되지 않게 되어 결국 재고만 감소된 상태로 남게 되면서, 데이터 불일치가 발생하게 된다.

로직 순서 변경을 통한 위험 범위 최소화

위 문제를 최소화하기 위해 로직 순서를 변경해 에러 발생 위험 범위를 줄였다.

public class OrderService {

    // ...

    public OrderConfirmResponse confirmOrder(OrderConfirmRequest orderConfirmRequest) {
        // 1. OrderInfo + Product + User Fetch Join 조회(락 없이 단순 조회)
        OrderInfo orderInfo = this.getOrderInfoByOrderId(orderConfirmRequest.getOrderId());

        // 2. TossPayment 측 결제 정보 조회(외부 API)
        TossPaymentResponse paymentInfo = paymentService.getPaymentInfoByOrderId(
                orderConfirmRequest.getOrderId()
        );

        // 3. 결제 정보 검증
        orderInfo.validateInProgressOrder(paymentInfo, orderConfirmRequest);

        // 4. 재고 감소 및 Database Commit
        productService.reduceStockWithCommit(
                orderInfo.getProduct().getId(),
                orderInfo.getQuantity()
        );

        // 5. TossPayment 측 결제 승인(외부 API)
        TossPaymentResponse confirmPaymentResponse =
                paymentService.confirmPayment(
                        TossConfirmRequest.createByOrderConfirmRequest(orderConfirmRequest)
                );

        // 6. 주문 확정 상태 변경
        OrderInfo confirmedOrderInfo = orderInfo.confirmOrder(
                confirmPaymentResponse,
                orderConfirmRequest
        );
        orderInfoRepository.save(confirmedOrderInfo);

        // WARNING!! 4번 이후에 에러 발생 시, 2번에서 발생한 재고 감소 건이 롤백되지 않음
        return new OrderConfirmResponse(confirmedOrderInfo);
    }

    // ...
}

아래와 같은 근거로 TossPayment 측 결제 정보 조회와 결제 정보 검증을 재고 감소 및 Database Commit 수행 전으로 변경하였다.

• TossPayment 측 결제 정보 조회: 주문 승인 전 검증을 위한 외부 API 요청으로, 재고 감소 및 데이터베이스 커밋 이전에 수행해도 무방
• 결제 정보 검증: 주문 승인 전 검증을 위한 로직이므로, 재고 감소 및 데이터베이스 커밋 이전에 수행해도 무방

하지만 여전히 에러 발생 시 재고 감소 건이 롤백되지 않는 근본적인 문제점은 해결되지 않았다.

보상 트랜잭션 명시적 추가를 통한 롤백

결제 승인 전에 재고 감소를 먼저 수행 시킨 뒤 재고를 다시 증가시키는 보상 트랜잭션을 명시적으로 추가하였고, 보상 트랜잭션을 재고로 선정한 이유는 다음과 같다.

• 재고 증감 작업은 서버에서 직접 제어가 가능하므로, 핸들링하는데 있어 비교적 더 안전
• 결제 승인 요청을 먼저 수행하는 경우, 승인에 대한 보상 트랜잭션으로 결제 취소라는 외부 API 요청을 수행 필요
  • 결국 외부 API를 통한 작업이기 때문에, 네트워크 의존성이 더 커지면서 위험 요소가 증가
  • 돈이 실제로 빠져나가고(승인 API) 다시 채워지게 되어(취소 API) 사용자 경험 저하

OrderService.java

public class OrderService {

    // ...

    public OrderConfirmResponse confirmOrder(OrderConfirmRequest orderConfirmRequest) {
        // 1. OrderInfo + Product + User Fetch Join 조회(락 없이 단순 조회)
        OrderInfo orderInfo = this.getOrderInfoByOrderId(orderConfirmRequest.getOrderId());

        // 2. TossPayment 측 결제 정보 조회(외부 API)
        TossPaymentResponse paymentInfo = paymentService.getPaymentInfoByOrderId(
                orderConfirmRequest.getOrderId()
        );

        // 3. 결제 정보 검증
        orderInfo.validateInProgressOrder(paymentInfo, orderConfirmRequest);

        // 4. 재고 감소 및 Database Commit
        productService.reduceStockWithCommit(
                orderInfo.getProduct().getId(),
                orderInfo.getQuantity()
        );

        // 5. TossPayment 측 결제 승인(외부 API) + 6. 주문 확정 상태 변경
        OrderInfo confirmedOrderInfo = this.confirmPaymentAndOrderInfoWithStockRollback(
                orderConfirmRequest,
                orderInfo
        );

        return new OrderConfirmResponse(confirmedOrderInfo);
    }

    // 이후 로직 하나의 메서드로 추출
    private OrderInfo confirmPaymentAndOrderInfoWithStockRollback(
            OrderConfirmRequest orderConfirmRequest,
            OrderInfo orderInfo
    ) {
        try {
            TossPaymentResponse confirmPaymentResponse =
                    paymentService.confirmPayment(
                            TossConfirmRequest.createByOrderConfirmRequest(orderConfirmRequest)
                    );

            OrderInfo confirmedOrderInfo = orderInfo.confirmOrder(
                    confirmPaymentResponse,
                    orderConfirmRequest
            );
            orderInfoRepository.save(confirmedOrderInfo);

            return confirmedOrderInfo;
        } catch (Exception e) { // 에러 발생 시 롤백 수행
            // 재고 증가 및 Database Commit
            productService.increaseStockWithCommit(
                    orderInfo.getProduct().getId(),
                    orderInfo.getQuantity()
            );

            throw e;
        }
    }

    // ...
}

4번 재고 감소 이후 에러가 발생할 수 있는 나머지 로직을 하나의 메서드로 추출하고, 해당 메서드 내에서 에러 발생 시 재고 처리하도록 변경하였다.

결과

로직 순서 변경과 보상 트랜잭션 추가로 다음 성과를 달성했다.

네트워크 지연 설정 X, 트랜잭션 범위 최소화 전/후 수행시간 비교(11s -> 6s)

잠금 범위 축소로 성능이 향상됐으며,

네트워크 지연 설정 3,000ms, 트랜잭션 범위 최소화 후 1,000개 요청 성공

API 지연으로 잠금 대기가 늘어나는 장애를 방지해 1,000개의 요청을 모두 성공하며, 이전에 20개 요청에서 타임아웃이 발생했던 것과 비교하면 안정성이 크게 향상됐다.

에러 처리 및 복구 로직 적용에 따른 트랜잭션 범위 변화

결제 상태의 추가와 결제 복구 로직 추가로 인해 트랜잭션 범위 정책과 복구 로직도 함께 변경되었다.

• 결제 시작 처리 먼저 수행 후 재고 감소를 수행
• 결제 검증 및 외부 API 요청을 수행하는 로직은 동일하게 유지
• 시작 처리를 먼저 데이터베이스에 반영하기 때문에 그 이후에 발생하는 예외 상황들에 대해 맞는 복구 로직 각각 작성
  • 재시도 가능과 불가능한 에러로 구분
  • 재시도 가능한 에러는 UNKNOWN 상태로 변경하고, 재고는 그대로 유지
  • 재시도 불가능한 에러는 FAIL 상태로 변경하고, 재고를 복구

PaymentConfirmServiceImpl.java

public class PaymentConfirmServiceImpl implements PaymentConfirmService {

    // ...

    @Override
    public PaymentConfirmResult confirm(PaymentConfirmCommand paymentConfirmCommand) {
        // 1. 결제 이벤트 조회
        PaymentEvent paymentEvent = paymentLoadUseCase.getPaymentEventByOrderId(
                paymentConfirmCommand.getOrderId()
        );

        try {
            // 2. 재고 차감 - 재고 부족 에러 발생 가능
            orderedProductUseCase.decreaseStockForOrders(paymentEvent.getPaymentOrderList());
        } catch (PaymentOrderedProductStockException e) {   // 에러 1: 재고 부족 에러 발생
            handleStockFailure(paymentEvent);               // FAIL 처리(재고 중 일어난 에러로, 감소가 일어나지 않았으므로 복구 필요 없음)
            throw PaymentTossConfirmException.of(PaymentErrorCode.ORDERED_PRODUCT_STOCK_NOT_ENOUGH);
        }

        try {
            // 3. 결제 시작 처리 - 결제 시작 상태 검증 중 에러 발생 가능
            paymentProcessorUseCase.executePayment(paymentEvent, paymentConfirmCommand.getPaymentKey());

            // 4. 결제 검증 - 결제 검증 중 에러 발생 가능
            // 5. 토스 결제 승인 요청 - 토스 측 재시도 가능/불가능한 에러 발생 가능
            // 6. 결제 완료 처리
            PaymentEvent completedPayment = processPayment(paymentEvent, paymentConfirmCommand);

            // 7. 결제 완료 결과 반환
            // ...
        } catch (PaymentStatusException e) {                // 에러 2: 이미 요청이 진행 된 건에 대한 요청
            handleNonRetryableFailure(paymentEvent);        // FAIL 처리 + 재고 복구
            throw e;
        } catch (PaymentTossRetryableException e) {         // 에러 3: 토스 측 재시도 가능한 에러 발생
            handleRetryableFailure(paymentEvent);           // UNKNOWN 상태로 변경 + 재고 그대로 유지
            throw PaymentTossConfirmException.of(PaymentErrorCode.TOSS_RETRYABLE_ERROR);
        } catch (PaymentTossNonRetryableException e) {      // 에러 4: 토스 측 재시도 불가능한 에러 발생
            handleNonRetryableFailure(paymentEvent);        // FAIL 처리 + 재고 복구
            throw PaymentTossConfirmException.of(PaymentErrorCode.TOSS_NON_RETRYABLE_ERROR);
        } catch (Exception e) {                             // 에러5: 결제 검증 중 에러 등 기타 에러 발생
            handleUnknownException(paymentEvent);           // FAIL 처리 + 재고 복구
            throw e;
        }
    }

    // ...
}

Tags:

• Payment Platform Project

결제 정보 검증을 통한 안전한 결제 연동 시스템 구현

2023. 11. 9. - Last update: 2026. 3. 11.

hyoguoo

Backend Engineer

실행 환경: Java 17, Spring Boot 3.1.5
서버 위주의 포스팅이기 때문에 클라이언트 코드는 간략하게 작성
프론트엔드는 토스페이먼츠에서 제공해준 샘플 프로젝트 리액트 일부 수정 사용
[!CAUTION] 해당 문서는 2023년 11월 기준의 코드로 작성되었으며, 구현 코드 상방 부분 변경

KG이니시스, 다날 페이먼트, 토스 페이먼츠 등의 결제 서비스를 제공하는 업체들이 존재하는데, 그 중 토스페이먼츠를 이용하여 결제 시스템을 구현해보았다.

• 토스페이먼츠에서 제공한 클라이언트 코드 사용
• 서버를 두어 검증 단계를 추가한 결제 시스템 구현

결제 연동 이해하기

문서가 잘 되어 있어 해당 문서를 참고하면 되며, 핵심 용어를 간단하게 요약하면 아래와 같다.

• 결제 위젯: 토스페이먼츠에서 제공해주는 결제 위젯 SDK로, 결제 요청을 위한 정보를 받아 결제 요청 전송
• Client Key: 결제 위젯을 사용하기 위해 필요한 키로(토스 페이먼츠에서 제공)
• Secret Key: 결제 승인 및 조회를 위해 필요한 키로(토스 페이먼츠에서 제공)
  • 공개하면 안되는 비밀키이므로 서버에서만 사용
• 결제 후 리다이렉트: 결제가 완료되면 결제 정보와 함께 리다이렉트를 해주는데, 이때 결제 정보는 URL 파라미터로 전달
  • 결제 인증만 완료된 상태(완전히 결제가 완료된 상태 X)
• 결제 승인: 인증된 결제를 최종 승인

전체적인 흐름

결제 흐름 페이지에도 나와있듯이 결제 흐름은 요청 - 인증 - 승인 단계로 나눌 수 있다.

실제 구현 흐름

기본 결제 흐름을 기반으로, 안전한 결제를 위해 서버는 검증자 역할을 수행한다.

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server
    participant T as PG
    Note over C, T: 결제 시퀀스 흐름
    C ->> S: 주문 번호 생성 요청
    S ->> S: 구매 요청 검증 및 DB 저장
    S -->> C: 주문 번호 반환
    C ->> T: 결제 요청
    T ->> T: 카드사 결제 인증
    T -->> C: 성공 리다이렉트
    C ->> S: 결제 승인 요청
    S ->> T: 결제 정보 조회
    T -->> S: 결제 정보 반환
    S ->> S: 결제 / 주문 정보 양방향 검증
    S ->> T: 결제 승인
    T -->> S: 승인 성공 반환
    S ->> S: DB 업데이트
    S -->> C: 성공 내역 반환
    C ->> C: 결제완료

상세 플로우 및 코드

1. 주문 번호 생성 요청 - (클라이언트)

실제 결제를 하기 위해선 주문 번호가 필요한데, 생성 정책을 다음과 같이 변경했다.

• Before: 클라이언트 측에서 직접 주문 번호 생성
• After: 서버측에서 생성하여 반환

위 화면의 결제하기 버튼을 누르면 실제 결제 요청 전에 서버에 주문 번호를 생성하는 요청을 먼저 보낸다.

2. 구매 요청 검증 및 DB 저장 + 3. 주문 번호 반환 - (서버)

서버에서는 주문 번호 반환 뿐만 아니라 구매 상품에 대한 검증과 DB에 저장하는 작업을 수행하게 된다.

OrderService.java

public class OrderService {
    // ...

    @Transactional
    public OrderCreateResponse createOrder(OrderCreateRequest orderCreateRequest) {
        OrderProduct orderProduct = orderCreateRequest.getOrderProduct();

        OrderInfo createdOrder = orderInfoRepository.save(
                // 1. 생성자 호출
                orderCreateRequest.toEntity(
                        userService.getById(orderCreateRequest.getUserId()),
                        productService.getById(orderProduct.getProductId())
                ));

        return new OrderCreateResponse(createdOrder); // 4. Order ID를 포함한 생성된 주문 정보 반환
    }

    // ...
}

OrderInfo.java

public class OrderInfo extends BaseTime {

    // ...

    // 2. 생성 및 검증
    @Builder
    protected OrderInfo(/* ... */) {
        // ...
        this.validateProductInfo(totalAmount, quantity); // 3. 생성 완료 전 상품 정보 검증
    }

    private void validateProductInfo(BigDecimal totalAmount, Integer quantity) {
        this.product.validateStock(quantity); // 상품 재고 검증

        // 상품 가격 * 수량 == 결제 금액 검증
        BigDecimal totalPrice = this.product.getPrice().multiply(BigDecimal.valueOf(quantity));
        if (totalAmount.compareTo(totalPrice) != 0) {
            throw OrderInfoException.of(OrderInfoErrorMessage.INVALID_TOTAL_AMOUNT);
        }
    }

    // ...
}

우선 상품 금액과 결제 금액이 일치하는지 검증하고, DB에 저장한다.(여기서 저장한 정보는 이후 승인 요청에서 검증을 위해 사용된다.)

4. 결제 요청 + 5. 결제 인증 + 6. 성공 리다이렉트 - (클라이언트)

주문 번호를 성공적으로 받게 되면 클라이언트에서 결제 정보를 통해 요청을 하게 되고 아래 화면에서 결제 완료 버튼을 누르면 결제 인증이 진행된다.

결제 인증까지 완료된다면 paymentKey, orderId, amount 정보를 포함하여 성공 페이지로 리다이렉트 되는데, 각 서버에서 검증 과정을 거치도록 한다.

7. 결제 승인 요청 - (클라이언트)

토스에서 제공해준 클라이언트 코드에서는 성공 페이지로 리다이렉트 되면 결제 승인 요청을 클라이언트에서 직접하고 있었으나, 서버에 요청을 거치도록 하였다.

8. 결제 정보 조회 + 9. 결제/주문 정보 검증 + 10. 결제 승인 + 11. DB 업데이트 + 12. 성공내역 반환 - (서버)

결제 승인 요청을 받은 서버는 클라이언트에서 받은 승인 요청 정보와 결제 요청 및 승인을 통해 저장된 토스페이먼츠 결제 정보를 검증하게 된다.

OrderService.java

public class OrderService {
    // ...

    @Transactional
    public OrderConfirmResponse confirmOrder(OrderConfirmRequest orderConfirmRequest) {
        // 1. Order ID 저장 때 생성된 주문 정보 조회(+ Pesimistic Lock으로 재고 차감 동시성 제어)
        OrderInfo orderInfo = this.getOrderInfoByOrderPessimisticLock(
                orderConfirmRequest.getOrderId()
        );
        // 2. 재고 충분한지 확인 + 재고 차감
        productService.reduceStock(orderInfo.getProduct().getId(), orderInfo.getQuantity());
        // 3. 결제 정보 조회
        TossPaymentResponse paymentInfo = paymentService.getPaymentInfoByOrderId(
                orderConfirmRequest.getOrderId()
        );

        // 4. 저장된 정보 + 클라이언트 요청 정보 + 토스에 저장된 결제 정보 검증
        orderInfo.validateInProgressOrder(paymentInfo, orderConfirmRequest);

        // 5. 결제 승인
        TossPaymentResponse confirmPaymentResponse =
                paymentService.confirmPayment(
                        TossConfirmRequest.createByOrderConfirmRequest(orderConfirmRequest)
                );

        // 6. OrderInfo 업데이트
        OrderInfo confirmedOrderInfo = orderInfo.confirmOrder(
                confirmPaymentResponse,
                orderConfirmRequest
        );

        // 7. 성공내역 반환
        return new OrderConfirmResponse(confirmedOrderInfo);
    }

    // ...
}

OrderInfo와 재고를 차감할 Product에 Lock을 걸어 재고 차감 동시성 문제를 방지하였고, 검증 및 데이터 변경은 OrderInfo 엔티티에서 수행했다.

OrderInfo.java

public class OrderInfo extends BaseTime {

    // ...

    // (위 코드의 4번에서 호출)저장된 정보 + 클라이언트 요청 정보 + 토스에 저장된 결제 정보 검증
    public void validateInProgressOrder(TossPaymentResponse paymentInfo,
            OrderConfirmRequest orderConfirmRequest) {
        // 주문 상태가 IN_PROGRESS가 아니라면 결제 승인 요청을 할 수 없음
        if (!paymentInfo.getStatus().equals(OrderStatus.IN_PROGRESS.getStatusName())) {
            throw OrderInfoException.of(OrderInfoErrorMessage.NOT_IN_PROGRESS_ORDER);
        }

        this.validateOrderInfo(paymentInfo, orderConfirmRequest);
    }

    // (위 코드의 6번에서 호출)OrderInfo 업데이트
    public OrderInfo confirmOrder(TossPaymentResponse paymentInfo,
            OrderConfirmRequest orderConfirmRequest) {
        // 승인 요청 후 결제 정보가 DONE이 아니라면 결제 승인이 완료되지 않음
        if (!paymentInfo.getStatus().equals(OrderStatus.DONE.getStatusName())) {
            throw OrderInfoException.of(OrderInfoErrorMessage.NOT_DONE_PAYMENT);
        }

        this.validateOrderInfo(paymentInfo, orderConfirmRequest);

        updateOrderPaymentInfo(paymentInfo); // 결제 정보 업데이트

        return this;
    }

    // 검증 로직, validateInProgressOrder/confirmOrder에서 호출
    private void validateOrderInfo(TossPaymentResponse paymentInfo,
            OrderConfirmRequest orderConfirmRequest) {
        // 저장된 order id == 클라이언트 요청 order id
        // 저장된 user id == 클라이언트 요청 user id
        // 클라이언트 요청 payment key == 토스에 저장된 payment key
        // 클라이언트 요청 amount == 토스에 저장된 total amount == 상품 가격 * 수
        // 코드 생략
    }

    // ...
}

validateOrderInfo를 결제 승인 요청 전/후로 두 번 호출하였는데, 그 목적은 다음과 같다.

• 요청 전: 아직 검증되지 않은 결제 정보가 불필요하게 결제 승인 요청 되는 것을 방지하기 위해 검증을 수행
• 요청 후: 승인 요청 후 올바르게 결제 정보를 승인하였는지 다시 한 번 검증

검증 자체는 비용이 크지 않으므로, 불필요한 결제 승인 요청을 방지하기 위해 검증 로직을 승인 전후로 두 번 호출하는 것이 더 안전하다고 판단했다.

12. 결제 완료 - (클라이언트)

결제가 무사히 완료되면 결제 완료 페이지로 이동하게 되면서 결과를 확인할 수 있다.

또한 토스 페이먼츠의 테스트 결제내역에서도 동일한 주문번호가 남아있어 정상적으로 결제가 완료되었음을 확인할 수 있다.

한계 및 개선 방향

구현을 완료하고 나니 외부 API 연동 구조에서 발생 가능한 여러 문제들이 발견되었고, 추후 이러한 문제점을 개선 방향으로 잡으면 좋을 것 같다.

OrderService.java

public class OrderService {
    // ...

    @Transactional // 외부 API 2회 요청이 있는 트랜잭션 범위
    public OrderConfirmResponse confirmOrder(OrderConfirmRequest orderConfirmRequest) {
        OrderInfo orderInfo = this.getOrderInfoByOrderPessimisticLock(
                orderConfirmRequest.getOrderId()
        );
        productService.reduceStock(orderInfo.getProduct().getId(), orderInfo.getQuantity());
        TossPaymentResponse paymentInfo = paymentService.getPaymentInfoByOrderId(
                orderConfirmRequest.getOrderId()
        );

        orderInfo.validateInProgressOrder(paymentInfo, orderConfirmRequest);

        // 결제 승인
        TossPaymentResponse confirmPaymentResponse =
                paymentService.confirmPayment(
                        TossConfirmRequest.createByOrderConfirmRequest(orderConfirmRequest)
                );
        // 요청이 지연 되는 경우..

        if (true)
            throw new Exception("test"); // 만약 승인 이후 오류 발생하면?

        OrderInfo confirmedOrderInfo = orderInfo.confirmOrder(
                confirmPaymentResponse,
                orderConfirmRequest
        );

        return new OrderConfirmResponse(confirmedOrderInfo);
    }

    // ...
}

결제 승인 후 오류 발생 케이스 - 결제 상태 전환 관리와 재시도 로직을 통한 결제 복구

• 결제 승인 이후 오류 발생 시, 서버의 데이터베이스에는 전부 롤백이 되지만 토스에는 결제 승인된 채로 남음
• 내부에서 오류가 발생할 확률은 낮지만, 갑작스러운 서버 장애 시 문제 발생 가능

API 지연으로 인한 실패 처리 - 재시도 로직을 통해 해결

• 결제 승인 단계에서 통신 중 응답이 지연 케이스
• 우리 서버의 타임 아웃 설정 값이 5초 + 토스 API 6초 지연 시 타임 아웃 발생
• 토스사에서는 결제 승인 완료 상태 / 우리 서버에서는 결제 승인이 완료되지 않은 것으로 처리되는 데이터 불일치 상황 발생

넓은 Transaction 범위 - 트랜잭션 범위 조정으로 해결

• 외부 API 요청이 2회이 존재하는 넓은 트랜잭션 범위 설정
• API 타임 아웃이 발생하게 되면 락을 획득한 상태에서 계속 대기하면서, 요청이 많아질 경우 성능 저하 발생

Tags:

• Payment Platform Project