멱등성과 중복 처리 방지 패턴

지난 글에서 페이지네이션 전략을 살펴봤습니다. 이번 글의 주제는 **멱등성(Idempotency)**입니다. 특히 결제, 포인트 적립, 재고 감소처럼 “한 번만 실행되어야 하는” 작업에서 네트워크 오류나 클라이언트 재시도로 인한 이중 처리를 방지하는 DB 패턴을 살펴봅니다.

멱등성이란

수학에서 멱등(idempotent)이란 같은 연산을 여러 번 적용해도 결과가 같은 성질입니다. f(f(x)) = f(x). 시스템에서는 같은 요청을 여러 번 보내도 결과가 한 번과 동일한 것을 의미합니다.

HTTP 메서드로 보면 GET, PUT, DELETE는 멱등이지만 POST는 멱등이 아닙니다. “결제” API를 POST /payments로 설계했을 때 클라이언트가 응답을 받지 못해 재시도하면 결제가 두 번 처리될 수 있습니다.

클라이언트: POST /payments { amount: 10000 }
서버: 결제 처리 완료
네트워크 단절 → 클라이언트 응답 못 받음
클라이언트: POST /payments { amount: 10000 } 재시도
서버: 또 결제 처리 → 이중 결제!

Idempotency-Key 패턴

Stripe가 대중화한 패턴으로, 클라이언트가 요청 시 고유한 키를 헤더에 포함합니다.

POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: payment-user123-order456-attempt1

{ "amount": 10000, "currency": "KRW" }

서버는 이 키를 저장해두고, 같은 키로 재요청이 오면 새로 처리하지 않고 이전 결과를 그대로 반환합니다.

멱등성 처리 흐름

DB 스키마 설계

멱등성 키를 저장하는 테이블을 별도로 관리합니다.

-- 멱등성 키 저장 테이블
CREATE TABLE idempotency_keys (
  idempotency_key  VARCHAR(255) PRIMARY KEY,
  request_hash     VARCHAR(64),    -- 요청 본문 해시 (다른 요청인지 검증)
  response_body    JSONB,          -- 캐시된 응답
  response_status  INT,            -- HTTP 상태 코드
  status           VARCHAR(20) DEFAULT 'processing',
  created_at       TIMESTAMPTZ DEFAULT NOW(),
  expires_at       TIMESTAMPTZ NOT NULL  -- TTL (예: 24시간)
);

CREATE INDEX ON idempotency_keys (expires_at)
  WHERE status = 'completed';  -- 만료된 키 정리용

처리 로직

트랜잭션 안에서 “키 삽입 시도 → 이미 있으면 캐시 반환” 흐름으로 처리합니다.

async def process_payment(idempotency_key: str, payload: dict):
    request_hash = sha256(json.dumps(payload, sort_keys=True))

    async with db.transaction():
        # 1. 멱등성 키 삽입 시도 (이미 존재하면 실패)
        result = await db.execute("""
            INSERT INTO idempotency_keys
              (idempotency_key, request_hash, status, expires_at)
            VALUES ($1, $2, 'processing', NOW() + INTERVAL '24 hours')
            ON CONFLICT (idempotency_key) DO NOTHING
            RETURNING status, response_body
        """, [idempotency_key, request_hash])

        if not result:
            # 2. 이미 처리된 경우: 기존 결과 조회
            existing = await db.fetchone(
                "SELECT status, response_body FROM idempotency_keys WHERE idempotency_key = $1",
                [idempotency_key]
            )
            if existing['status'] == 'processing':
                raise ConflictError("요청이 처리 중입니다")
            return existing['response_body']

        # 3. 신규: 비즈니스 로직 실행
        payment_result = await execute_payment(payload)

        # 4. 결과 저장
        await db.execute("""
            UPDATE idempotency_keys
            SET status = 'completed', response_body = $1
            WHERE idempotency_key = $2
        """, [json.dumps(payment_result), idempotency_key])

        return payment_result

DB 레벨 중복 방지: ON CONFLICT

애플리케이션 레이어 없이 DB 레벨에서 직접 중복을 방지할 수 있습니다. PostgreSQL의 ON CONFLICT DO NOTHING을 사용합니다.

DB 레벨 중복 방지 — INSERT ON CONFLICT

-- MySQL 동일 패턴
INSERT IGNORE INTO payments (idempotency_key, user_id, amount)
VALUES ('key-abc', 1, 10000);
-- 중복 시 에러 없이 무시

-- 또는 REPLACE INTO (기존 행 삭제 후 재삽입 — 사용 주의)
-- REPLACE INTO payments ... -- PK가 바뀌므로 FK 이슈 발생 가능

클라이언트 키 생성 전략

멱등성 키는 클라이언트가 생성해야 합니다. 일반적인 전략입니다.

// 결제 전 UUID 생성 (로컬 저장)
const idempotencyKey = crypto.randomUUID();
localStorage.setItem('pendingPaymentKey', idempotencyKey);

// 결제 API 호출
try {
  const result = await fetch('/payments', {
    method: 'POST',
    headers: { 'Idempotency-Key': idempotencyKey },
    body: JSON.stringify({ amount: 10000 })
  });
  localStorage.removeItem('pendingPaymentKey');
  return result.json();
} catch (error) {
  // 재시도 시 동일한 키 사용
  return retryWithSameKey(idempotencyKey);
}

주의사항

요청 본문 해시 검증: 같은 키로 다른 내용의 요청이 오면 에러 반환 (다른 결제 금액 등)
TTL 설정: 멱등성 키는 영구 보관하지 않습니다. 일반적으로 24시간 ~ 7일
분산 환경: Redis를 사용한 분산 락과 조합하면 동시 중복 요청도 방지 가능
상태 확인: processing 상태인 키로 재요청이 오면 “처리 중” 응답 반환

다음 글에서는 소프트 딜리트(Soft Delete)와 하드 딜리트(Hard Delete)의 트레이드오프와 올바른 선택 기준을 살펴봅니다.

지난 글: 커서 vs 오프셋 — 페이지네이션 전략

다음 글: Soft Delete vs Hard Delete

읽어주셔서 감사합니다. 😊