문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
149 lines
10 KiB
Markdown
149 lines
10 KiB
Markdown
# 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`, 키 형식은 `IdempotencyKeyHeaderTest`
|
||
- 헤더 규칙(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`) |
|
||
|
||
필터 앞에서 끊긴 응답(필터 체인 밖의 오류)은 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 | `IDEMPOTENCY_KEY_INVALID` (`details.reason` = `MISSING`/`MALFORMED`) | `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를 돌려준다. 키로 결과를 조회하는 엔드포인트는 없다.
|
||
- **키 문법**: 보이는 ASCII(`0x21`–`0x7E`) 1~256자. 서버는 trim하거나 고치지 않는다. 짝 프론트의
|
||
`isValidIdempotencyKey`와 같은 규칙이다. KEYED 엔드포인트는 모두 `IdempotencyKeyHeader.parse`로 헤더를
|
||
읽어 같은 코드로 거부한다(리뷰 02-12). 키 원문은 응답에 돌려 쓰지 않는다. 키를 요구하지 않는
|
||
엔드포인트는 키 없이 보호 없이 실행된다.
|
||
|
||
같은 executor가 내는 나머지 두 실패:
|
||
|
||
| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 멱등성 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다 |
|
||
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 재전송도 재실행도 안전하지 않다. 업무 데이터로 결과를 확인한다 |
|
||
|
||
## 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`·스트리밍)이 시간 안에 끝나지 않았다 |
|
||
| `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절을 같은 변경에서 고친다.
|
||
- 짝 프론트의 백엔드 계약 문서(`clean-architecture-frontend-template`
|
||
`docs/architecture/backend-api-and-server-state-contract.md` §4.1·§6)는 이 문서를 가리켜야 한다.
|