본문으로 건너뛰기
· backend · 2분 읽기

구매와 재고 API의 일괄 처리를 멱등하게 만들기

일괄 입고 API에서 일부 항목만 저장되면 재시도 시 이미 반영된 항목을 구분해야 한다. 전체 성공 또는 전체 실패를 계약으로 정한 경우에는 재고 변경, 문서 상태, 요청 결과를 같은 트랜잭션에서 저장한다.

예제는 구매 문서의 행을 참조하는 입고 문서다. 수량은 합성 정수로 표현하고, 실제 단위 환산이나 회사별 승인 규칙은 포함하지 않는다.

구현한 범위

구매·재고·생산 문서의 상태 전파, 잔량 검증과 멱등 일괄 처리를 트랜잭션과 API 계약으로 구현했다. 회사의 문서명과 세부 업무 규칙은 제외하고, 아래에서는 가상 문서와 수량으로 정합성 조건을 설명한다.

문서 상태보다 관계와 잔량부터 확인한다

입고 행에는 원본 구매 행 ID를 저장한다. 요청의 구매 문서 ID와 행의 소속이 일치하는지, tenant가 같은지, 취소된 문서를 참조하지 않는지 검증한다.

잔량을 주문 수량 - 누적 입고 수량으로 정의했다면 두 요청이 동시에 같은 잔량을 읽는 경우를 막아야 한다. 조회 후 Go 코드에서만 비교하면 두 요청이 모두 통과할 수 있다.

sql
UPDATE purchase_line
SET received_quantity = received_quantity + $1
WHERE id = $2
  AND tenant_id = $3
  AND $1 > 0
  AND received_quantity + $1 <= ordered_quantity
RETURNING id, received_quantity;

영향받은 행이 없으면 존재하지 않음, 권한 범위 불일치, 잔량 부족 중 무엇인지 서비스 계약에 맞게 처리한다. 여러 행과 문서 상태를 함께 확인해야 한다면 행 잠금과 트랜잭션을 사용한다. PostgreSQL 행 잠금은 같은 행을 수정하는 경쟁 트랜잭션을 조정한다.

요청 안의 중복도 정규화한다

동일한 구매 행이 요청 안에 두 번 들어올 수 있다. 이를 금지할지 수량을 합칠지 먼저 정한다. 합치는 경우 합산 후 잔량을 비교하고, 숫자 범위 초과도 검사한다.

서로 다른 요청이 여러 구매 행을 갱신한다면 잠금 순서를 ID 순으로 고정한다. 이것이 모든 deadlock을 없애지는 않지만 반대 순서로 같은 행들을 잡는 경합은 줄인다. deadlock 재시도는 실패한 SQL 한 줄이 아니라 트랜잭션 전체를 대상으로 한다.

요청키와 입력 서명

요청키는 같은 시도를 식별한다. 입력 서명은 그 키가 다른 요청에 재사용됐는지 확인한다.

signature input
  tenant_id
  operation_version
  purchase_document_id
  정규화한 행 목록 (purchase_line_id, quantity)

JSON 원문을 그대로 해시하면 필드 순서나 숫자 표기 차이로 서명이 달라질 수 있다. 의미 있는 필드를 명시적으로 직렬화한다. 항목 순서가 의미 없다면 정렬하고, 순서가 결과를 바꾼다면 보존한다.

(tenant_id, operation, request_key)에는 unique 제약을 둔다. 동일 키·동일 서명은 저장된 결과를 반환하고, 동일 키·다른 서명은 충돌로 반환한다. 키의 보관 기간이 끝난 뒤 같은 요청을 다시 보내면 재실행될 수 있으므로 API의 재시도 가능 기간과 함께 정한다.

트랜잭션 경계

BEGIN
  요청키 확보 및 입력 서명 비교
  원본 문서와 대상 행 잠금
  잔량과 문서 관계 검증
  입고 문서 및 행 생성
  잔량 갱신
  구매 문서 상태 재계산
  요청 결과 저장
  필요한 Outbox 이벤트 저장
COMMIT

문서 상태가 모든 행의 잔량에서 계산된다면 상태 갱신 경로도 같은 잠금 규칙에 참여해야 한다. 다른 API가 잠금 없이 문서를 취소하면 일괄 처리 안에서만 정합성을 지켜도 부족하다.

외부 알림 전송은 이 트랜잭션에 포함되지 않는다. 커밋 후 직접 전송하다 실패하면 DB를 되돌릴 수 없으므로, 알림 의도를 Outbox에 남기는 식으로 분리한다.

전체 롤백의 비용

항목이 많을수록 트랜잭션과 잠금 유지 시간이 길어진다. DB에 보내는 쿼리를 청크로 나눠도 같은 트랜잭션이면 잠금은 커밋까지 유지될 수 있다. 따라서 청크 크기와 API 최대 항목 수는 다른 설정이다.

처리 규모가 너무 크다면 비동기 작업으로 바꾸거나 부분 성공 계약을 별도로 설계할 수 있다. 내부 최적화를 이유로 기존 전체 성공 계약을 조용히 바꾸지는 않는다.

재현할 입력과 기대 결과

아래 공개용 합성 시나리오의 동시 실행 검증은 수행하지 않았다. 다음 합성 시나리오에서 문서·잔량·요청 결과를 함께 비교한다.

입력기대 결과
잔량 10에 각각 7을 처리하는 동시 요청하나만 성공하고 최종 누적량은 허용 범위 이내
마지막 항목의 잔량 부족앞 항목의 문서와 잔량 변경도 롤백
응답 유실 후 같은 요청키 재시도기존 생성 ID와 결과 반환
같은 요청키에 수량 변경충돌, 추가 변경 없음
다른 tenant의 구매 행 참조원본과 신규 문서 모두 변경 없음

실패 응답을 받은 경우에도 요청 전후 DB 상태를 비교해 앞 항목의 변경이 남지 않았는지 확인한다.

공유하기 X LinkedIn

관련 글