Files
clean-architecture-backend-…/docs/web/http-contract.md
T
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00

14 KiB
Raw Blame History

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-advanced WebAdvancedErrorMappingTest

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에 맞는 코드로 답한다. 본문에 요청 경로나 시각을 싣지 않는다. 기본 JWT 체인에서도 익명 400이 401로 바뀌지 않는다(재리뷰 RR-02-02). 다만 요청 id 필터를 지나기 전에 끊긴 응답은 meta의 id 키가 빠질 수 있다. 클라이언트는 meta의 모르는 키를 무시한다.

status는 코드 표(HttpStatusErrorCodes)에 있는 것만 그대로 나간다: 401·403·404·405·406·412·413·414·415·429·503. 표에 없는 status는 그 class의 코드로 접힌다 — 4xx(408·409·410·422 등)는 BAD_PARAMETER 400, 5xx(501·502·504 등)는 INTERNAL_ERROR 500(재리뷰 RR-01-13, EnvelopeErrorControllerTest). error.code와 status가 registry (docs/registries/error-codes.yaml)와 어긋나지 않게 하려는 것이다. 클라이언트는 status가 아니라 error.code로 가르기 때문이다. 필터가 다른 status를 내야 하면 sendError 대신 그 status의 코드로 EnvelopeResponseWriter를 쓰거나, 표에 행을 더한다.

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 없음 재전송도 재실행도 안전하지 않다. 업무 데이터로 결과를 확인한다
  • 결과 불명이 무엇을 뜻하나. 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서 불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은 남는다. 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 일어났을 수 있다. 그래서 실행 전 거부와 같은 503이어도 code가 다르다. 클라이언트는 status가 아니라 error.code로 가른다.
  • 같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다. 결과가 실제로는 기록됐으면 재생(첫 요청의 성공 응답), 첫 시도의 processing lease(processing-lease, 기본 30s)가 아직 남았으면 409 IDEMPOTENT_IN_FLIGHT, lease가 지났으면 500 IDEMPOTENCY_RECOVERY_REQUIRED다. lease가 지난 실행 기록을 다음 요청이 만나면 두 저장소(PostgreSQL·Redis) 모두 넘겨주지 않고 포기(abandoned)로 표시한다 — 그 뒤 첫 시도가 늦게 끝나도 결과는 기록되지 않고 그 요청도 500을 받는다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다 (재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11).
  • 서버가 기억하는 기간. 완료된 응답은 완료부터 replay-ttl(기본 24h), 끝나지 않은 시도의 기록은 claim부터 processing lease + replay-ttl 동안 남는다. 그 뒤 같은 키는 새 요청으로 실행된다. replay-ttl이 processing-lease보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).

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_REFUSED 503 등 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-template docs/architecture/backend-api-and-server-state-contract.md §4.1·§6)는 이 문서를 가리켜야 한다.