Files
clean-architecture-backend-…/docs/manual/05-idempotency.md
T
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

5.7 KiB

05. 멱등성·결과 불명 처리

핵심

쓰기 요청의 결과는 세 가지다: 됐다, 안 됐다, 모른다. "모른다"를 "안 됐다(다시 해도 됨)"로 적으면 같은 작업이 두 번 적용된다. 그래서 결과를 증명할 수 없을 때는 항상 "모른다"로 답하고, 클라이언트가 안전하게 다시 물을 방법(같은 멱등성 키)을 준다.

클라이언트 ── POST + Idempotency-Key ──▶ 컨트롤러 ──▶ KEYED 유스케이스
                                                         │ IdempotencyExecutor
                                                         ├─ 처음 본 키   → 실행 → 결과 저장 → 응답
                                                         ├─ 끝난 키     → 저장된 결과 재생
                                                         ├─ 실행 중 키  → 409 IDEMPOTENT_IN_FLIGHT (retryable, Retry-After 2)
                                                         └─ 다른 본문   → 422 IDEMPOTENT_REQUEST_MISMATCH
DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false)

정본: docs/web/http-contract.md 2절(wire 응답), src/application-core/CLAUDE.md 「Idempotency (KEYED)」 (executor 구조), docs/adr/ADR-JPA-003-completion-unknown.md(커밋 결과 불명).

판단: 이 쓰기를 KEYED로 만드나

  • 고르는 기준: 클라이언트가 응답을 못 받았을 때 다시 보내는가, 그리고 두 번 적용되면 피해가 있는가.
  • 기본값: 생성·결제·주문·발송처럼 "두 번 = 피해"인 쓰기는 KEYED. 같은 입력이면 같은 결과인 쓰기(상태를 X로 설정)는 IDEMPOTENT. 그 밖은 NOT_IDEMPOTENT(생성 명령의 기본값 — 바꿀지 여기서 정한다).
  • 예외: 자연 키가 있어 DB 유일성 제약이 중복을 막으면(04장) 키 없이도 두 번째 요청이 409로 끝난다. 다만 그 409는 "이미 있음"이지 "첫 요청의 결과"가 아니다. 클라이언트가 첫 결과를 받아야 하면 KEYED.

KEYED로 만드는 순서

  1. @UseCaseCapability(idempotency = Idempotency.KEYED).
  2. 유스케이스 본문을 IdempotencyExecutor로 감싼다. executor를 유스케이스가 만들지 않는다 — composition:idempotency가 한 번 만든다.
  3. scope digest(주체 + 키 + operation 코드의 HMAC)와 요청 fingerprint(SHA-256)를 유스케이스 밖(전송)에서 만든다. 원본 키는 저장소에 닿지 않는다.
  4. 작업 결과를 IdempotentAction.Outcome(Success / RetryableNoEffect / EffectUnknown)으로 돌려준다. 예외를 던지면 effect-unknown으로 센다.
  5. 저장소 provider를 고른다: app.capabilities.idempotency.provider = postgresql 또는 redis (기본 disabled). 운영에서 in-memory 금지.

예: src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/ 의 PosterImagePublicationController(키 헤더 검증), 유스케이스 쪽은 sample application/posterimage.

클라이언트에게 무엇을 약속하나

응답 의미 클라이언트 행동
409 IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2 같은 키가 아직 실행 중. 결과 불명 같은 키로 기다렸다 재전송. 새 키 금지
422 IDEMPOTENT_REQUEST_MISMATCH 같은 키에 다른 본문 클라이언트 버그. 재전송 안 함
503 IDEMPOTENCY_UNAVAILABLE 실행 전 거부 같은 키로 나중에
500 IDEMPOTENCY_RECOVERY_REQUIRED 이전 시도 효과를 증명 못함 재전송·재실행 모두 위험. 업무 데이터로 확인
500 DB_COMPLETION_UNKNOWN, retryable=false DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정

409를 retryable=true로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시 보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.

결과 불명을 만드는 곳마다 같은 규칙

리뷰가 찾은 반복 원인 1번이 "결과 불명을 확실함으로 기록"이었다(05-01, 04-01, 06-01). 새 경계를 만들 때 아래 질문에 답한다.

  • 고르는 기준: 실패한 호출이 상대편에서 이미 효과를 냈을 수 있는가.
  • 기본값: 그럴 수 있으면 "결과 불명"으로 분류한다. 재시도 가능(retryable=true)으로 분류하지 않는다. 근거 코드:
    • DB 커밋 중 끊김 → DB_COMPLETION_UNKNOWN (src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java)
    • 메시지 발행 응답 없음 → OutboxPublishAmbiguousException(application-core outbox)
    • 알림 발송 시작 뒤 crash → 재발송하지 않고 reconcile(application-notification evidence 모델)
  • 예외: 요청이 상대에게 도달하기 전에 실패한 것이 증명되면(연결 수립 실패, 실행 전 거부) 재시도 가능이다. 반대 방향 실수(확실히 안 간 것을 불명으로)도 결함이다(리뷰 05-17).
  • 불명 상태를 푸는 방법(reconcile, 키 재전송, 운영자 확인)을 runbook에 적는다(docs/runbooks/).

지금 이해하면 되는 것

  • "두 번 = 피해"인 쓰기는 KEYED. executor는 composition이 만든다.
  • 409 in-flight는 같은 키로 다시, 422는 버그, 500 completion-unknown은 키 없이 재시도 금지.
  • 상대편에 효과가 났을 수 있으면 "모른다"로 분류한다.