🌳 고급 고급
Idempotency Key란?
쉽게 이해하기
Idempotency Key는 은행 ATM의 거래번호 같아요. 실수로 출금 버튼을 두 번 눌러도, 같은 거래번호가 있으면 중복 출금을 막아주잖아요. API에서도 같은 원리로 중복 요청을 방지해요.
핵심 정리
같은 요청을 여러 번 보내도 한 번만 처리되도록 하는 고유 키예요.
자세히 알아보기
Idempotency Key는 네트워크 문제나 클라이언트 재시도로 같은 요청이 여러 번 전송되어도, 서버가 한 번만 처리하도록 보장하는 고유 식별자예요. 특히 결제, 주문 같은 중요한 작업에서 필수적이에요.
실무에서 가장 흔한 시나리오는 결제예요. 사용자가 '결제하기' 버튼을 눌렀는데 네트워크가 느려서 응답이 안 오면, 불안해서 버튼을 다시 누를 수 있어요. Idempotency Key 없이 구현하면 중복 결제가 발생할 수 있죠. Stripe 같은 결제 API는 클라이언트가 요청 시 Idempotency-Key 헤더에 UUID를 보내면, 같은 키로 온 요청은 첫 번째 결과를 반환하고 실제로는 한 번만 처리해요.
구현 방법은 이래요. 서버는 Idempotency Key와 함께 요청 결과를 일정 시간(보통 24시간) 동안 캐시(Redis 등)에 저장해요. 같은 키로 요청이 다시 오면 실제 로직을 실행하지 않고 저장된 결과를 그대로 반환해요. 데이터베이스에 unique constraint로 idempotency_key 컬럼을 두면 DB 레벨에서도 중복을 막을 수 있어요.
주의할 점은 클라이언트가 키를 생성해야 한다는 거예요. 서버가 생성하면 재시도 시 매번 새 키가 되니까 의미가 없어요. 보통 클라이언트는 요청 전에 UUID를 생성하고, 타임아웃이나 네트워크 에러가 나면 같은 키로 재시도해요. AWS API Gateway, Stripe, Twilio 등 많은 서비스가 Idempotency Key를 지원해요.