Idempotency (멱등성)

1. 개요

네트워크는 언제나 불안정하며, 클라이언트의 요청이나 서버의 응답은 언제든지 유실될 수 있습니다. 클라이언트가 API를 호출했는데 타임아웃이 발생했다면, 클라이언트는 이 요청이 서버에서 처리되었는지 알 길이 없어 **재시도(Retry)**를 하게 됩니다. 이때 서버가 같은 요청을 두 번 처리하게 되면서 문제가 발생할 수 있는데, 이를 방지하기 위한 핵심 개념이 바로 **멱등성(Idempotency)**입니다.

---

2. 멱등성(Idempotency)이란?

수학이나 전산학에서 멱등성이란 연산을 여러 번 적용하더라도 결과가 달라지지 않는 성질을 의미합니다. 즉, f(f(x)) = f(x) 가 성립하는 경우입니다.

서버 API 관점에서 보면, **“동일한 요청을 한 번 보내든, 100번 보내든 서버의 상태(데이터베이스 등)가 동일하게 유지되는 성질”**을 말합니다.

2-1. HTTP 메서드와 멱등성

RESTful API를 설계할 때 HTTP 메서드별로 멱등성 여부가 명확히 구분됩니다.

• GET: 데이터를 조회만 하므로 여러 번 호출해도 서버 상태는 변하지 않습니다. (멱등함 O)
• PUT: 특정 리소스를 통째로 교체합니다. 같은 데이터로 여러 번 교체해도 최종 상태는 똑같습니다. (멱등함 O)
• DELETE: 리소스를 삭제합니다. 이미 삭제된 리소스를 다시 삭제하려 해도 최종적으로 그 리소스가 없다는 상태는 같습니다. (멱등함 O)
• POST: 새로운 리소스를 생성합니다. 여러 번 호출하면 여러 개의 리소스가 생성됩니다. (멱등하지 않음 X)
• PATCH: 리소스의 일부를 수정합니다. 로직에 따라 멱등할 수도, 아닐 수도 있습니다. (예: age = 20은 멱등하지만, age = age + 1은 멱등하지 않습니다.)

---

3. 왜 중요한가? (재시도와 데이터 정합성)

주문 결제 시스템이나 예약 취소 시스템을 생각해 봅시다.

1. 사용자가 ‘결제’ 버튼을 누릅니다. (POST /payments)
2. 서버는 결제를 완료하고 계좌에서 돈을 차감합니다.
3. 하지만 서버가 “결제 완료” 응답을 보내기 직전에 네트워크가 끊어집니다.
4. 클라이언트는 에러를 보고 다시 ‘결제’ 버튼을 누릅니다(재시도).
5. 서버는 다시 결제를 처리하여 돈이 이중 차감됩니다.

이러한 끔찍한 상황을 막기 위해 API는 멱등성을 보장하도록 설계되어야 합니다.

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database

    C->>S: 1. 예약 취소 요청 (Retry 1)
    S->>DB: 2. 상태 변경 (CONFIRMED -> CANCELLED)
    DB-->>S: 3. 반영 완료
    S--xC: 4. 응답 전송 중 네트워크 유실!
    
    Note over C: Timeout 발생, 재시도 수행
    C->>S: 5. 예약 취소 요청 (Retry 2)
    S->>DB: 6. 상태 조회 (이미 CANCELLED)
    S-->>C: 7. 200 OK (멱등성 보장: 추가 변경 없음)

---

4. 멱등성을 구현하는 방법

4-1. 고유한 Idempotency Key 사용

가장 보편적인 방법은 클라이언트가 요청을 보낼 때 헤더에 고유한 Idempotency-Key (UUID 등)를 포함하여 보내는 것입니다. 서버는 이 키를 Redis나 DB에 저장해 두고, 동일한 키로 요청이 들어오면 로직을 수행하지 않고 이전에 성공했던 응답을 그대로 반환합니다. Stripe와 같은 결제 API들이 이 방식을 채택합니다.

4-2. 데이터베이스 상태 체크 (Optimistic 멱등성)

비즈니스 로직 단에서 엔티티의 현재 상태를 체크하여 멱등성을 보장할 수도 있습니다. 예를 들어, 취소 요청이 들어왔을 때 대상의 상태가 이미 CANCELLED라면 에러를 던지거나 성공(200 OK)을 반환하고 로직을 조기 종료(Return)하는 방식입니다.

@Transactional
public void cancelBooking(String bookingId) {
    Booking booking = repository.findById(bookingId);
    
    // 멱등성 보장 로직
    if (booking.getStatus() == BookingStatus.CANCELLED) {
        return; // 이미 취소되었으므로 아무 작업도 하지 않음
    }
    
    booking.cancel();
}

안전하고 견고한 분산 시스템을 구축하기 위해 멱등성은 선택이 아닌 필수입니다.

---