61 lines
4.1 KiB
Markdown
61 lines
4.1 KiB
Markdown
---
|
|
title: concept / Idempotency
|
|
source_type: llm-generated
|
|
status: reviewed
|
|
confidence: high
|
|
tags: [concept, ca-tmpl, api-design, spring-boot, idempotency]
|
|
related_projects: [ca-tmpl]
|
|
last_reviewed: 2026-06-15
|
|
---
|
|
|
|
# concept / Idempotency
|
|
|
|
## Summary
|
|
|
|
동일한 요청을 한 번 보내는 것과 여러 번 연속해서 보내는 것이 서버의 상태에 미치는 영향이 동일한 성질.
|
|
- 안전한 메서드(Safe Methods) 및 멱등한 메서드(Idempotent Methods)를 구분하여 HTTP 클라이언트의 재시도 안전성을 보장하는 기반이 된다.
|
|
|
|
## Standard (공식 정의)
|
|
|
|
RFC 9110 HTTP Semantics 규격에 따른 정의는 다음과 같다.
|
|
- **Idempotent Methods**: `GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`, `TRACE`는 여러 번 수행해도 리소스의 최종 상태가 동일하다. 따라서 transient network failure 발생 시 클라이언트가 안전하게 재시도할 수 있다.
|
|
- **Non-Idempotent Methods**: `POST`와 `PATCH`는 호출할 때마다 새로운 리소스가 생성되거나 상태 변경이 누적될 수 있어, 재시도가 안전하지 않다. 중복 처리를 방지하려면 별도의 `Idempotency-Key` 헤더와 같은 고유 분산 락/식별 메커니즘이 합의되어야 한다.
|
|
|
|
## 한계 / 주의점
|
|
|
|
- **멱등성은 서버가 보장해야 하는 계약이다**: 클라이언트 입장에서 단순히 `GET`을 보낸다고 해서 서버가 내부적으로 멱등하게 처리하지 않고 사이드 이펙트(예: 조회수 1 증가 등)를 누적한다면 엄격한 의미의 멱등성은 깨질 수 있다. 그러나 HTTP 명세상 클라이언트는 RFC 규격을 신뢰하고 재시도를 감행하게 된다.
|
|
- **Idempotency-Key 계약의 부재**: 아웃바운드 연동 시 상대방 서버가 `Idempotency-Key` 사양을 구현하지 않았다면, `POST`나 `PATCH` 호출 실패 시 클라이언트는 네트워크 지연 등의 원인으로 인해 요청이 이미 처리되었는지 알 수 없어 재시도가 불가능하다.
|
|
|
|
## Project Application
|
|
|
|
- [[wiki/explainer/adapter-outbound.md]]
|
|
- `OutboundRetryPolicy`는 RFC 9110 규격에 정의된 멱등한 메서드(`GET`, `HEAD`, `PUT`, `DELETE`)에 대해서만 `shouldRetry`가 `true`를 반환하도록 설계되어 있음. `POST`/`PATCH`는 부작용 방지를 위해 즉시 `false`를 뱉고 재시도를 전면 금지함.
|
|
|
|
## Claim-backed Knowledge
|
|
|
|
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
|
|---|---|---|---|
|
|
| RFC 9110 기반 멱등 메서드 리스트 및 재시도 타당성 | `raw/official-docs/rfc9110-http-semantics.md` | `high` | RFC 9110 표준 명세 |
|
|
| non-idempotent API 재시도를 위한 Idempotency-Key 계약 | `raw/official-docs/idempotency-stripe-api-ref.md` | `high` | Stripe의 실무 멱등 키 처리 패턴 |
|
|
|
|
## 내가 설명할 수 있어야 하는 것
|
|
|
|
- `GET`과 `PUT`은 왜 멱등하고 `POST`와 `PATCH`는 왜 비멱등한가?
|
|
- 왜 우리 아웃바운드 HTTP 클라이언트는 `POST`/`PATCH` 요청에 대해 재시도를 원천 차단하는가? (Idempotency-Key 계약 미정의에 따른 사이드 이펙트 방지)
|
|
- 비멱등 메서드를 꼭 재시도해야 할 경우, 인프라 및 애플리케이션 계층에서 어떤 설계를 보완해야 하는가?
|
|
|
|
## Interview Questions
|
|
|
|
- HTTP 메서드 중 멱등성을 보장하는 메서드와 그렇지 않은 메서드를 구분하고, 네트워크 타임아웃 발생 시 각각에 대한 재시도 전략을 설명해 주세요.
|
|
- 아웃바운드 호출 시 POST 요청의 재시도를 제한하는 시스템에서, 일시적인 네트워크 순단 상황을 어떻게 극복할 수 있겠습니까?
|
|
|
|
## Do Not Overclaim
|
|
|
|
- "멱등한 메서드만 재시도하므로 어떠한 데이터 정합성 문제도 발생하지 않는다"고 확언해서는 안 된다. 업스트림(상대방 서버)이 표준을 무시하고 내부 구현을 비멱등하게 작성했을 경우 여전히 사이드 이펙트가 발생할 수 있음을 인지해야 한다.
|
|
|
|
## Sources
|
|
|
|
- [RFC 9110 Section 9.3: Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html)
|
|
- [[raw/official-docs/rfc9110-http-semantics.md]]
|
|
- [[raw/official-docs/idempotency-stripe-api-ref.md]]
|