Files
clean-architecture-backend-…/docs/web/http-contract.md
T
2026-11-13 07:21:13 +09:00

218 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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가 아닌 응답은 두 곳뿐이다. fileserver의 프로토콜 예외(`docs/fileserver/http-contract.md` 「Envelope 규칙의
프로토콜 예외」)와 알림 provider callback이다. callback은 provider가 status만 읽는 webhook 응답이라 본문 없이
204·400·413·503만 답한다(`src/adapter/inbound/web-notification/AGENTS.md`).
### 왜 이렇게 나가는가
`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): 같은 키, 첫 요청이 아직 실행 중(Redis 저장소. PostgreSQL 저장소는 409 대신 첫 요청이 끝날 때까지 기다린다 — 아래 "첫 시도가 lease보다 오래 걸릴 때") | 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·시작 단계) 멱등성 저장소 응답 없음. 또는 claim의 processing lease가 작업 시작 전에 끝나 저장소가 시작을 거절함 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다(다음 요청이 그 claim을 넘겨받아 실행한다) |
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 같은 키 재전송은 안전하다 — 서버는 효과가 있었을 수 있는 작업을 다시 돌리지 않고, 첫 시도가 늦게 끝났으면 그 결과를 재생하며, 효과 없이 끝났으면 실행하고, 아니면 다시 500이다. 결과는 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차(`docs/runbooks/idempotency-unavailable.md`)에 따라 새 키로 다시 보낸다 |
- **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서
불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은
남는다. 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 일어났을 수 있다. 그래서 실행 전 거부와 같은
503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다.
- **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면
재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 이것은 Redis 저장소의
판정이다. PostgreSQL 저장소는 아래처럼 첫 요청이 끝날 때까지 기다린 뒤 판정한다. 새 키로 보내면 서버는
다른 요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정
RR-01-11).
- **첫 시도가 lease보다 오래 걸릴 때 — 저장소마다 다르다.** executor는 lease를 늘리지 않으므로 30s를 넘는
정상 요청도 lease가 지난다(재리뷰 2026-11-04 RR5-01-05).
- Redis: lease가 지난 실행 기록을 다음 요청이 만나면 500으로 답하고 기록은 건드리지 않는다. 첫 시도가
그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기 응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그
결과를 재생한다. 첫 시도가 실패를 보고하면 먼저 온 보고 하나가 기록된다(효과 불명이면 계속 500, 효과
없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이 이미 사라진 뒤에 끝나면 결과를
기록하지 못해 첫 요청도 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다(2026-11-04 소유자 결정).
- PostgreSQL: 템플릿처럼 executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면 claim 기록은 그
트랜잭션이 끝날 때 함께 커밋되거나 롤백된다. 그래서 같은 키 요청은 409나 500을 받지 않고 그 기록에서
기다린다. 첫 트랜잭션이 커밋되면 재생을, 롤백되면 새 실행을 받는다. lease가 지나도 같다. 작업이 실패해
예외로 끝난 요청은 executor가 남긴 실패 기록도 함께 롤백되므로, 효과 불명 실패도 다음 같은 키 요청이
다시 실행한다. 또 쓰기 트랜잭션 제한(`app.persistence-jpa.transaction.write-timeout`, 기본 30s — 기본
lease와 같다, 업그레이드 안내 B-21)이 두 요청에 모두 걸린다. 첫 요청이 그보다 오래 걸리면 취소되고 claim
기록도 함께 롤백된다(503 `DB_QUERY_CANCELED`). 기다리던 요청도 자기 제한을 넘기면 같은 코드로 끝난다.
어느 경우든 롤백된 DB 변경은 남지 않지만, 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 다음 같은 키
요청에서 두 번 일어날 수 있다. 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다
(`PostgreSqlIdempotencyIntegrationTest`).
- **서버가 기억하는 기간.** 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새
요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다.
- 완료된 응답: 완료부터 `replay-ttl`(`APP_IDEMPOTENCY_TTL`, 기본 24h).
- 끝나지 않은 시도: claim부터 processing lease + `replay-ttl`. lease가 지난 실행 기록도 이 수명을 그대로
쓴다. 그 사이 첫 시도가 끝나면 그때부터 위(완료)나 아래(실패)의 수명으로 바뀐다.
- 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이
재시도 가능으로 끝난 시도. 표시한 때부터 `failure-retention`(`APP_IDEMPOTENCY_FAILURE_RETENTION`,
기본 24h). PostgreSQL 저장소를 쓰기 트랜잭션 하나 안에서 쓰면 실패 기록은 요청의 롤백과 함께 사라져
남지 않는다(위 PostgreSQL 항목).
`replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).
`failure-retention`이 `replay-ttl`보다 짧아도 기동이 실패한다. 더 짧으면 효과 불명으로 포기한 기록이 그만큼
먼저 사라지고, 그 뒤 같은 키 재전송은 작업을 다시 돌린다(재리뷰 2026-11-04 RR3-03-02, 2026-11-04 소유자
결정).
## 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`, `Content-Range`
새 응답 헤더를 쓰는 모듈은 `CorsExposedHeaders` bean으로 자기 헤더를 기여한다.
## 4. web 전용 오류 코드
`OperationalError`(`docs/registries/error-codes.yaml`) 밖에서 HTTP 어댑터가 내는 코드다.
| 코드 | status | category | `retryable` | `Retry-After` | 언제 |
| --- | --- | --- | --- | --- | --- |
| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. 그 밖의 503(필터의 `sendError(503)` 등)은 공용 `SERVER_BUSY`다. 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 제공자가 계약과 맞지 않음 |
| `OPERATION_NOT_FOUND` | 404 | `NOT_FOUND` | `false` | 없음 | durable operation 조회(`DurableOperationController`)에서 그 operation이 없거나 다른 호출자의 것이다. 둘을 가르지 않는다 |
- 컨트롤러 파라미터 제약 위반(`@RequestParam @Max(10)`)은 요청 본문 위반과 같은
`400 VALIDATION_FAILED`이고 `details`는 `[{field, code, message}]`다. 거절된 값은 싣지 않는다.
- web-advanced를 실은 서비스의 예외 코드(`PATCH_REJECTED` 400 등)는
`src/adapter/inbound/web-advanced/README.md` 「오류 응답」이 정본이다.
- 서버 포화(허가 상한, 꽉 찬 work pool)는 모든 전송이 공용 `SERVER_BUSY`(503, retryable, `Retry-After: 1`)
하나로 답한다. 호출자 자신의 빈도 초과만 `RATE_LIMIT_EXCEEDED` 429다(`docs/registries/error-codes.yaml`).
- 직접 쓰는 거부 응답(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`)도 같이 본다.
- 짝 프론트 repo `clean-architecture-frontend-template`의 백엔드 계약 문서(「backend API와 server state
계약」 §4.1·§6)는 이 문서를 가리켜야 한다. 그 문서는 다른 repo에 있어서 여기서 경로로 가리키지 않는다.