Files
clean-architecture-backend-…/docs/manual/05-idempotency.md
T
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00

6.4 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 실행 전 거부 같은 키로 나중에
503 IDEMPOTENCY_COMPLETION_UNKNOWN, retryable=true 실행 뒤 결과 기록 실패. 적용됐을 수 있음 "적용 안 됨"이라 하지 않는다. 같은 키로 나중에 재전송, 새 키 금지
500 IDEMPOTENCY_RECOVERY_REQUIRED 이전 시도 효과를 증명 못함 재전송·재실행 모두 위험. 업무 데이터로 확인
500 DB_COMPLETION_UNKNOWN, retryable=false DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정

같은 키 재전송은 작업을 다시 돌리지 않는다. 첫 시도가 실행을 시작한 뒤 processing lease(기본 30s)가 지나면 두 저장소 모두 그 기록을 넘겨주지 않고 500 IDEMPOTENCY_RECOVERY_REQUIRED로 답한다. 넘겨받는 것은 실행 전 claim과 재시도 가능한 실패뿐이다. 기록은 lease + replay-ttl 동안 남고, replay-ttl이 lease보다 짧으면 기동이 실패한다(IdempotencyStoreContract, 재리뷰 2026-11-04 RR-01-11·RR-03-11).

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은 키 없이 재시도 금지.
  • 상대편에 효과가 났을 수 있으면 "모른다"로 분류한다.