문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(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·의존 없음이어야 한다.
13 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 - 핸들러 밖 오류(
/error디스패치)의 실패 Envelope: 실제 컨테이너에서WebContractAssertions(TomcatWebContractIT·Jetty lane), 기본 JWT 체인에서JwtChainErrorDispatchIT - 멱등성 응답의 status·code·retryable·
Retry-After:IdempotencyExceptionMappingTest,RetryAfterAdvisorTest,OperationalErrorTest, 키 형식은IdempotencyKeyHeaderTest, 실행 전 거부와 결과 불명의 구분은IdempotencyExecutorTest, lease 하한은IdempotencySettingsTest - 헤더 규칙(3절):
WebMvcRequestIdFilterTest,CorsSecurityFilterIntegrationTest - web 전용 코드(4절):
TransportErrorHandlingTest,IdempotencyKeyHeaderTest, web-advancedWebAdvancedErrorMappingTest
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가 아니다. - 컨트롤러가
String을 반환해도 JSON을 요청하면(Accept: application/json) 같은 Envelope로 나간다 ("data": "<문자열>"). 텍스트를 요청하면 문자열 그대로다. - 빈 컬렉션 결과는
"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) |
컨트롤러에 닿기 전에 거부된 요청(보안 방화벽이 막은 경로, 필터의 sendError, 필터가 던진 예외)도 같은
실패 Envelope다. 컨테이너가 /error로 넘긴 요청을 EnvelopeErrorController가 status에 맞는 코드로 답한다.
본문에 요청 경로나 시각을 싣지 않는다. 원래 status가 그대로 나가고, 기본 JWT 체인에서도 익명 400이 401로
바뀌지 않는다(재리뷰 RR-02-02). 다만 요청 id 필터를 지나기 전에 끊긴 응답은 meta의 id 키가 빠질 수 있다.
클라이언트는 meta의 모르는 키를 무시한다.
4xx·5xx status로 나가는 본문은 success:true로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로
돌려주는 핸들러는 그 본문이 그대로 나간다.
왜 이렇게 나가는가
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 | IDEMPOTENCY_KEY_INVALID (details.reason = MISSING/MALFORMED) |
false |
없음 | 문법에 맞는 키를 붙여 다시 보낸다 |
- 처리 중을
retryable=true로 두는 이유. 같은 키 재전송은 서버가 재생·처리 중·불일치로 안전하게 판정하므로, 다시 보내는 것이 맞는 행동이다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못해, 첫 요청이 끝나면 같은 작업이 두 번 적용된다. Retry-After: 2의 근거. 기본 processing lease(app.capabilities.idempotency.processing-lease, 30s)보다 짧아, 첫 시도가 아직 끝날 수 있는 동안 다시 묻는다. 너무 이르면 409를 한 번 더 받을 뿐이고 결과가 바뀌지는 않는다. 값은IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER하나이고RetryAfterAdvisor가 그 값을 쓴다.processing-lease를 이 값(2초) 이하로 설정하면 기동이 실패한다(IdempotencySettings, 재리뷰 RR-02-05).- executor는 기다리지 않는다. 처리 중이면 바로 409를 돌려준다. 키로 결과를 조회하는 엔드포인트는 없다.
- 키 문법: 보이는 ASCII(
0x21–0x7E) 1~256자. 서버는 trim하거나 고치지 않는다. 짝 프론트의isValidIdempotencyKey와 같은 규칙이다. KEYED 엔드포인트는 모두IdempotencyKeyHeader.parse로 헤더를 읽어 같은 코드로 거부한다(리뷰 02-12). 키 원문은 응답에 돌려 쓰지 않는다. 키를 요구하지 않는 엔드포인트는 키 없이 보호 없이 실행된다.
같은 executor가 내는 나머지 세 실패. 저장소가 응답하지 않은 경우는 언제 멈췄는지로 코드가 갈린다.
| 경우 | status | error.code |
retryable |
Retry-After |
클라이언트 행동 |
|---|---|---|---|---|---|
| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음 | 503 | IDEMPOTENCY_UNAVAILABLE |
true |
없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다 |
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — 결과 불명 | 503 | IDEMPOTENCY_COMPLETION_UNKNOWN |
true |
없음 | "적용되지 않았다"고 알리지 않는다. 같은 키로 나중에 다시 보낸다. 새 키 금지 |
| 이전 시도의 효과를 증명할 수 없음 | 500 | IDEMPOTENCY_RECOVERY_REQUIRED |
false |
없음 | 재전송도 재실행도 안전하지 않다. 업무 데이터로 결과를 확인한다 |
- 결과 불명이 무엇을 뜻하나. 작업은 이미 돌았다. 그 작업의 트랜잭션 안 DB 변경은 예외와 함께
롤백되지만, 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 일어났을 수 있다. 그래서 실행 전 거부와 같은
503이어도 code가 다르다. 클라이언트는 status가 아니라
error.code로 가른다. - 같은 키로 다시 보내면 서버가 판정한다. 결과가 실제로는 기록됐으면 재생(첫 요청의 성공 응답), 첫 시도의
processing lease가 아직 남았으면 409
IDEMPOTENT_IN_FLIGHT, lease가 지났으면 500IDEMPOTENCY_RECOVERY_REQUIRED다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다 (재리뷰 2026-11-03 README 4절 결정, RR-02-03).
3. 헤더
요청 id·correlation id
| 헤더 | 방향 | 규칙 |
|---|---|---|
X-Request-Id |
응답(항상) | 서버가 만든다. 신뢰 설정(app.web.mvc.trust-inbound-request-id)일 때만 요청 값을 받는다 |
X-Correlation-Id |
요청·응답(항상) | 요청 값이 [A-Za-z0-9._-]{1,128}(앞뒤 공백 제거 후)이면 그대로 잇고, 아니면 서버가 새로 만든다. 고치지 않고 바꾼다 |
traceparent |
요청·응답(항상) | 유효한 W3C 값이면 잇고, 아니면 새로 만든다 |
세 값은 응답 meta의 requestId·correlationId·traceId와 같다. 셋 다 짝 프론트의
[A-Za-z0-9._:-]{1,128} 안에 든다.
브라우저가 읽을 수 있는 응답 헤더(CORS)
CORS가 켜져 있으면(app.cors.enabled=true) cross-origin 실제 응답의 Access-Control-Expose-Headers에
아래가 들어간다. 이 목록 밖의 헤더(안전 목록 Cache-Control·Content-Type 등 제외)는 브라우저 코드에서
null로 보인다.
- 플랫폼(
CorsExposedHeaders.PLATFORM):Retry-After,X-Request-Id,X-Correlation-Id,traceparent,Location,ETag,X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset - fileserver를 실은 배포:
Tus-Resumable,Tus-Version,Tus-Extension,Tus-Max-Size,Upload-Offset,Upload-Length,Upload-Defer-Length,Upload-Expires,Upload-Complete,Upload-Limit,Content-Disposition,Accept-Ranges
새 응답 헤더를 쓰는 모듈은 CorsExposedHeaders bean으로 자기 헤더를 기여한다.
4. web 전용 오류 코드
OperationalError(docs/registries/error-codes.yaml) 밖에서 HTTP 어댑터가 내는 코드다.
| 코드 | status | category | retryable |
Retry-After |
언제 |
|---|---|---|---|---|---|
REQUEST_TIMEOUT |
503 | TRANSIENT_DEPENDENCY |
true |
없음 | 비동기 요청(Callable·DeferredResult·스트리밍)이 시간 안에 끝나지 않았다. GraphQL도 같은 이름을 쓰지만 그쪽 category는 GraphQL 전용 어휘 TIMEOUT이다(src/adapter/inbound/graphql/README.md) |
IDEMPOTENCY_KEY_INVALID |
400 | VALIDATION |
false |
없음 | 2절 |
RATE_LIMIT_UNAVAILABLE |
503 | TRANSIENT_DEPENDENCY |
true |
있음 | rate-limit 저장소 응답 없음(docs/web/runbook.md) |
RATE_LIMIT_INCOMPATIBLE |
503 | INTERNAL |
false |
없음 | rate-limit 제공자가 계약과 맞지 않음 |
- 컨트롤러 파라미터 제약 위반(
@RequestParam @Max(10))은 요청 본문 위반과 같은400 VALIDATION_FAILED이고details는[{field, code, message}]다. 거절된 값은 싣지 않는다. - web-advanced를 실은 서비스의 예외 코드(
ADMISSION_REFUSED503 등 10종)는src/adapter/inbound/web-advanced/README.md「오류 응답」이 정본이다. - 직접 쓰는 거부 응답(401·403·429·503)도 컨트롤러 응답과 같이
application/json;charset=UTF-8이다.
5. 바꿀 때
- 응답 키를 더하거나 빼면
EnvelopeWireShapeTest와 이 문서 1절을 같이 고친다. - 응답 헤더를 새로 쓰면
CorsExposedHeaders에 넣고 3절을 고친다. - 멱등성 코드의 status·retryable·
Retry-After를 바꾸면OperationalError,RetryAfterAdvisor,docs/registries/error-codes.yaml, 이 문서 2절을 같은 변경에서 고친다. 공유 코드의retryable은 gRPC trailer(error-retryable)와 GraphQL extension(retryable)에도 그대로 나가므로 그 둘의 README와 매핑 테스트(GrpcStatusMapperTest,GraphQlWireErrorMapperTest)도 같이 본다. - 짝 프론트의 백엔드 계약 문서(
clean-architecture-frontend-templatedocs/architecture/backend-api-and-server-state-contract.md§4.1·§6)는 이 문서를 가리켜야 한다.