Files
clean-architecture-backend-…/docs/web/http-contract.md
T
DongHyeonka 34565130e0 fix!: 성숙도 리뷰의 High·P1 결함 19건을 고친다
문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를
모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중
끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을
DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와
wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이
기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를
한 번도 돌리지 않았다.

방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택:
- 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은
  쓰기가 하나 늘어 버림).
- 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를
  트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림).
- 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가).
- 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는
  web Jackson mixin으로 생략(shared-contract는 stdlib only).
- 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로.
- strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다.
발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다.

위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지
않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다.
이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다
(다음 커밋에서 대체 이미지로 해결).

검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지
pull 거부). -p optional-platforms ci integrationCheck, performanceCheck,
releaseCheck(-PgitRevision) 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절
BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은
audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true,
Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다.
2026-11-03 19:52:06 +09:00

6.9 KiB

HTTP wire 계약

이 백엔드의 HTTP 응답을 읽는 클라이언트(짝 프론트, 파생 서비스의 다른 앱)가 기대해도 되는 것을 한 곳에 적는다. 응답 모양과 멱등성 응답의 뜻은 이 문서가 정본이다. 다른 문서(web README 예외 표, docs/web/runbook.md, docs/registries/error-codes.yaml 주석)는 이 문서를 가리키고 같은 문장을 쓴다.

코드가 이 문서를 지키는지는 다음 테스트가 확인한다.

  • 응답 원문의 키 집합: src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeWireShapeTest.java
  • 멱등성 응답의 status·code·retryable·Retry-After: IdempotencyExceptionMappingTest, RetryAfterAdvisorTest, OperationalErrorTest

1. Envelope 키 존재 규칙

JSON 응답은 모두 Envelope 하나의 모양이다(소유자 결정 2). 값이 null인 필드는 키째 생략한다. 빈 목록([])은 null이 아니므로 생략하지 않는다.

응답 최상위 키 없는 키
성공 success(=true), data, meta error
실패 success(=false), error, meta data
bulk 전체 성공 success(=true), results, meta error
bulk 부분 실패 success(=false), error(code=BATCH_PARTIAL_FAILURE, details=항목별 결과), meta results
  • success가 판별자다. 클라이언트는 success로 갈라 읽고, 키가 있는지로 판단하지 않는다.
  • 성공인데 data가 null이면 data 키도 없다. 본문이 아예 없는 응답(204)은 Envelope가 아니다.
  • 빈 컬렉션 결과는 "data": [], 빈 bulk 결과는 "results": [], 항목 없는 부분 실패는 "details": []로 나간다.

error 키

키 항상 있음 뜻
code 예 안정된 기계용 식별자. 클라이언트는 이것으로 분기한다
category 예 Category enum 이름(VALIDATION, CONFLICT …)
message 예 사용자에게 보여도 되는 한국어 문구(ClientErrorMessages). 분기에 쓰지 않는다
retryable 예 같은 요청을 다시 보내도 안전하고 의미가 있는지
details 아니오 코드별 구조 정보(검증 실패 필드 목록, bulk 항목 결과). 없으면 키도 없다

meta 키

키 언제 있나
requestId 요청 id 필터(WebMvcRequestIdFilter)를 지난 모든 응답
traceId 위와 같음. 추적이 꺼져 있어도 필터가 만든 W3C trace id가 들어간다
correlationId 위와 같음. 값이 없으면 키가 없다
page 페이지 목록 응답에만. number·size·total·sort(미정렬이면 sort: null)

필터 앞에서 끊긴 응답(필터 체인 밖의 오류)은 id 키가 빠질 수 있다. 클라이언트는 meta의 모르는 키를 무시한다.

왜 이렇게 나가는가

Envelope·BulkEnvelope·ApiError·ResponseMeta는 shared-contract에 있고, 이 leaf는 Java 표준 라이브러리 외에는 의존하지 않는다. 그래서 @JsonInclude를 타입에 붙이지 않고, web 어댑터의 EnvelopeWireFormatConfig가 Jackson mix-in으로 같은 규칙을 Boot의 JsonMapper에 등록한다. 이 어댑터의 모든 HTTP writer(MVC 변환기, 보안 entry point, rate-limit interceptor)가 그 JsonMapper를 쓴다. GraphQL·STOMP·gRPC는 이 타입들을 직렬화하지 않으므로 이 규칙의 영향을 받지 않는다.

2. 멱등성 응답

Idempotency-Key를 받는 쓰기 엔드포인트(KEYED)는 IdempotencyExecutor를 거친다. 같은 키로 다시 보낸 요청은 서버가 아래 넷 중 하나로 판정한다. 키는 인증 주체와 operation 범위 안에서만 같은 키다.

경우 status error.code retryable Retry-After 클라이언트 행동
재생(replay): 같은 키·같은 본문, 첫 요청 완료 첫 요청과 같은 성공 status — (성공 Envelope) — 없음 첫 요청의 결과로 받아들인다. meta의 id는 이번 요청의 것이다
처리 중(in-flight): 같은 키, 첫 요청이 아직 실행 중 409 IDEMPOTENT_IN_FLIGHT true 2 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송한다. 새 키 금지
본문 불일치(mismatch): 같은 키·다른 본문 422 IDEMPOTENT_REQUEST_MISMATCH false 없음 클라이언트 버그. 다시 보내지 않는다. 새 작업이면 새 키를 만든다
키 누락·형식 오류 400 BAD_PARAMETER false 없음 키를 붙여 다시 보낸다
  • 처리 중을 retryable=true로 두는 이유. 같은 키 재전송은 서버가 재생·처리 중·불일치로 안전하게 판정하므로, 다시 보내는 것이 맞는 행동이다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못해, 첫 요청이 끝나면 같은 작업이 두 번 적용된다.
  • Retry-After: 2의 근거. 기본 processing lease(app.capabilities.idempotency.processing-lease, 30s)보다 짧아, 첫 시도가 아직 끝날 수 있는 동안 다시 묻는다. 너무 이르면 409를 한 번 더 받을 뿐이고 결과가 바뀌지는 않는다. lease를 2초보다 짧게 설정한 서비스는 이 값이 lease를 넘으므로 값을 다시 정한다(RetryAfterAdvisor, docs/registries/error-codes.yaml).
  • executor는 기다리지 않는다. 처리 중이면 바로 409를 돌려준다. 키로 결과를 조회하는 엔드포인트는 없다.
  • 키 누락 처리는 엔드포인트가 정한다(공용 검증 부품 없음, 리뷰 02-12). 템플릿 예시 (PosterImagePublicationController)는 헤더가 없으면 MissingRequestHeaderException, 비었거나 256자를 넘으면 IllegalArgumentException으로 둘 다 400 BAD_PARAMETER다. 키를 요구하지 않는 엔드포인트는 키 없이 보호 없이 실행된다.

같은 executor가 내는 나머지 두 실패:

경우 status error.code retryable Retry-After 클라이언트 행동
멱등성 저장소 응답 없음 503 IDEMPOTENCY_UNAVAILABLE true 없음 작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다
이전 시도의 효과를 증명할 수 없음 500 IDEMPOTENCY_RECOVERY_REQUIRED false 없음 재전송도 재실행도 안전하지 않다. 업무 데이터로 결과를 확인한다

3. 바꿀 때

  • 응답 키를 더하거나 빼면 EnvelopeWireShapeTest와 이 문서 1절을 같이 고친다.
  • 멱등성 코드의 status·retryable·Retry-After를 바꾸면 OperationalError, RetryAfterAdvisor, docs/registries/error-codes.yaml, 이 문서 2절을 같은 변경에서 고친다.
  • 짝 프론트의 백엔드 계약 문서(clean-architecture-frontend-template docs/architecture/backend-api-and-server-state-contract.md §4.1·§6)는 이 문서를 가리켜야 한다.