문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
5.9 KiB
5.9 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로 만드는 순서
@UseCaseCapability(idempotency = Idempotency.KEYED).- 유스케이스 본문을
IdempotencyExecutor로 감싼다. executor를 유스케이스가 만들지 않는다 —composition:idempotency가 한 번 만든다. - scope digest(주체 + 키 + operation 코드의 HMAC)와 요청 fingerprint(SHA-256)를 유스케이스 밖(전송)에서 만든다. 원본 키는 저장소에 닿지 않는다.
- 작업 결과를
IdempotentAction.Outcome(Success/RetryableNoEffect/EffectUnknown)으로 돌려준다. 예외를 던지면 effect-unknown으로 센다. - 저장소 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면 같은 키로 재전송하면 서버가 판정 |
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-coreoutbox) - 알림 발송 시작 뒤 crash → 재발송하지 않고 reconcile(application-notification evidence 모델)
- DB 커밋 중 끊김 →
- 예외: 요청이 상대에게 도달하기 전에 실패한 것이 증명되면(연결 수립 실패, 실행 전 거부) 재시도 가능이다. 반대 방향 실수(확실히 안 간 것을 불명으로)도 결함이다(리뷰 05-17).
- 불명 상태를 푸는 방법(reconcile, 키 재전송, 운영자 확인)을 runbook에 적는다(
docs/runbooks/).
지금 이해하면 되는 것
- "두 번 = 피해"인 쓰기는 KEYED. executor는 composition이 만든다.
- 409 in-flight는 같은 키로 다시, 422는 버그, 500 completion-unknown은 키 없이 재시도 금지.
- 상대편에 효과가 났을 수 있으면 "모른다"로 분류한다.