[개발지식] 멱등성(Idempotency), 멱등성 키(Idempotency Key)

---

1.멱등성(Idempotency)

연산을 한 번 실행하든, 여러 번 실행하든 동일하게 유지되는 성질을 멱등성이라고 부른다.
개발분야에서는 동일한 요청을 여러 번 보내야 할 때, 시스템의 데이터 일관성을 지키는 특징을 설명할때 멱등성의 용어를 사용한다.

 

 

 

2.HTTP 메서드 멱등성

HTTP 멱등성은 동일한 요청을 한 번 보내든 여러 번 연속으로 보내든 서버의 상태가 동일하게 유지되는 성질을 의미한다.
즉, 서버에 미치는 영향이 항상 같으며 중복 요청으로 인한 side effect가 발생하지 않는다.

아래 표에서 GET같은 경우는 리소스를 단순히 조회만 한다. 백 번을 조회해도 서버의 데이터 상태는 변하지 않으므로 멱등하다고 할수있다..

GET	데이터 조회	멱등	리소스를 변경하지 않고 여러 번 조회해도 항상 같은 데이터가 반환됩니다.
PUT	데이터 전체 교체/생성	멱등	동일한 데이터를 여러 번 덮어써도 최종 상태는 항상 같습니다.
DELETE	데이터 삭제	멱등	이미 삭제된 리소스에 대해 요청을 다시 보내도 존재하지 않는 상태가 유지됩니다.
POST	데이터 생성	X	매번 새로운 리소스가 생성되므로 요청 횟수만큼 데이터가 추가됩니다.
PATCH	데이터 부분 수정	X	리소스의 일부만 변경할 때 사용하며, 누적 연산으로 인해 결과가 달라질 수 있습니다.

 

 

 

 

 

3.멱등성 키(Idempotency Key)

클라이언트가 고유한 문자열을 생성하여 커스텀 HTTP 헤더에 포함하는 방법으로 네트워크 오류로 인해 클라이언트가 서버의 응답을 받지 못해 같은 요청을 두 번, 세 번 재시도하더라도 결제같은 중요 로직을 수행하지 않도록 하기위한 키이다.

 

https://cloud.google.com/discover/idempotency?hl=ko

멱등성이란 무엇인가요? API 안정성 가이드

 

 

 

4. 멱등성 키의 작동 흐름

4-1.키 생성 (클라이언트)

사용자가 결제 버튼을 누르면, 프론트엔드(모바일 앱/웹)는 고유한 문자열인 멱등성 키(주로 UUID 형식)를 생성합니다.

4-2. API 요청

HTTP 헤더에 이 키를 담아 서버에 전송합니다.

POST /payments

Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

 

4-3. 키 검증 (서버)

백엔드 서버는 데이터베이스나 인메모리 캐시(예: Redis)에서 해당 키가 존재하는지 조회합니다.

 

4-4. 상태별 분기 처리

키가 없는 경우: 결제 로직을 실행합니다. 실행 전 데이터베이스에 키를 '처리 중' 상태로 저장하고, 완료되면 '성공' 상태와 결과 데이터를 함께 저장한 뒤 클라이언트에게 응답합니다.

키가 있고 상태가 '처리 중'인 경우: 동일한 요청이 거의 동시에 들어왔거나 아직 이전 작업이 안 끝난 상태입니다. 서버는 이중 결제를 막기 위해 에러를 반환하거나 잠시 대기하라고 알려줍니다.

키가 있고 상태가 '성공'인 경우 (재시도 요청): 결제 로직을 절대 다시 타지 않습니다. 서버는 이전에 DB에 저장해 두었던 과거의 성공 응답 데이터를 그대로 꺼내서 다시 반환합니다. 클라이언트 입장에서는 방금 결제가 성공한 것처럼 정상적인 응답을 받게 됩니다.

 

 

 

 

 

https://docs.tosspayments.com/blog/what-is-idempotency

멱등성이 뭔가요? | 토스페이먼츠 개발자센터