문제: 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 필드를 보내지 않는다.
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으로 둘 다 400BAD_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-templatedocs/architecture/backend-api-and-server-state-contract.md§4.1·§6)는 이 문서를 가리켜야 한다.