Files
clean-architecture-backend-…/docs/manual/05-idempotency.md
T
DongHyeonka 2c692554cb fix!: r9 확인 리뷰가 찾은 결함 25건을 고친다
문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).

방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
  만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
  금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
  늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.

위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).

검증: GATES

Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
2026-11-05 20:37:55 +09:00

9.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 실행 전 거부(저장소 응답 없음, 또는 claim의 lease가 시작 전에 끝남) 같은 키로 나중에
503 IDEMPOTENCY_COMPLETION_UNKNOWN, retryable=true 실행 뒤 결과 기록 실패. 적용됐을 수 있음 "적용 안 됨"이라 하지 않는다. 같은 키로 나중에 재전송, 새 키 금지
500 IDEMPOTENCY_RECOVERY_REQUIRED 이전 시도 효과를 증명 못함 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키
500 DB_COMPLETION_UNKNOWN, retryable=false DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정

같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(재리뷰 2026-11-04 RR5-01-05, 라운드6 RR6-02-05, 정본 docs/web/http-contract.md 2절). Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지 않는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키 요청이 다시 실행한다. 그래서 트랜잭션 밖 효과는 따로 멱등하게 만든다. 첫 시도가 processing lease(기본 30s)보다 오래 걸릴 때 보이는 모습도 저장소마다 다르다.

  • Redis: 첫 시도가 실행을 시작한 뒤 lease가 지나면 그 기록을 넘겨주지 않고 500 IDEMPOTENCY_RECOVERY_REQUIRED로 답한다. 넘겨받는 것은 실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은 기록을 바꾸지 않는다. executor는 lease를 늘리지 않아 30s를 넘는 정상 요청도 lease가 지나는데, 그 첫 시도가 나중에 끝나면 결과가 기록되고 첫 요청은 정상 응답을 받으며 그 뒤 같은 키 요청은 그 결과를 재생한다(2026-11-04 소유자 결정).
  • PostgreSQL: executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면(템플릿의 모양) claim 기록은 그 트랜잭션과 함께 커밋되거나 롤백된다. 같은 키 요청은 409·500 대신 첫 요청이 끝날 때까지 기다렸다가 재생(커밋)이나 새 실행(롤백)을 받는다. 작업이 예외로 끝나면 실패 기록도 함께 롤백되어 다음 같은 키 요청이 다시 실행한다. 쓰기 트랜잭션 제한(기본 30s)을 넘긴 요청도 기록과 함께 롤백된다 (DB_QUERY_CANCELED). 그래서 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다. 트랜잭션 밖 효과는 다음 요청에서 다시 일어날 수 있다.

claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 거절하고(LEASE_EXPIRED), executor는 작업을 돌리지 않은 채 503 IDEMPOTENCY_UNAVAILABLE로 답한다. 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다. IdempotencyClaimAttempt를 재시도 사이에 들고 있다가 같은 attempt로 다시 부르는 호출자도 넘겨받는다(라운드6 RR6-02-01. 전에는 같은 claim을 재생받아 시작을 다시 거절당해 기록이 사라질 때까지 503이었다). 같은 attempt를 두 호출이 동시에 쓰면 서버가 가려내지 못하므로, 재시도는 앞 호출이 돌아온 뒤에 한다. 기록은 lease + replay-ttl 동안 남고, replay-ttl이 lease보다 짧으면 기동이 실패한다 (IdempotencyStoreContract, 재리뷰 2026-11-04 RR-01-11·RR-03-11). 작업이 실패로 끝나 executor가 포기나 재시도 가능으로 표시한 기록은 표시한 때부터 failure-retention(기본 24h) 동안 남는다(PostgreSQL을 트랜잭션 하나로 쓰면 위처럼 롤백과 함께 사라진다). failure-retention이 replay-ttl보다 짧으면 기동이 실패한다. 짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(RR3-03-02, 2026-11-04 소유자 결정). 거꾸로 말하면 replay-ttl(APP_IDEMPOTENCY_TTL)은 lease 이상, failure-retention 이하로 둔다.

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