docs(contract): 거절 code별 적용 여부를 백엔드 코드로 정한다 (1101/14.4)
문제
"검증 거절은 적용 안 됨" 판정(64e98ee)의 근거가 추론이었다. 백엔드
http-contract.md 4절은 VALIDATION_FAILED의 출처를 적지만 "상태를 바꾸지
않는다"는 문장이 없다. 그 밖의 400·409·422 code는 어느 단계에서 나오는지
적힌 곳이 없었다. 계약 4.1·6절은 백엔드 커밋이 없어 기준을 결정일로 적었다.
고른 방법
- 백엔드 5786126c 코드에서 400·409·422를 내는 곳을 모두 찾고, code마다
단계(쓰기 전 / 쓰기 뒤 가능)와 프론트 결과(NOT_APPLIED / MAYBE_APPLIED),
백엔드 파일:줄을 6.1절 표에 적었다. 같은 code가 쓰기 전과 뒤에서 모두
나오면 쓰기 뒤 가능으로 둔다. 프론트는 code만으로 둘을 가르지 못한다.
- 4.1·6절 기준을 결정일에서 백엔드 SHA 5786126c로 바꿨다.
- 표와 지금 프론트 판정이 다른 곳을 같은 절에 적었다. client.ts는 다른
작업이 고치고 있어 이 변경에서 건드리지 않았다.
찾은 것
- 쓰기 전: VALIDATION_FAILED(출처 5곳 모두 바인딩·검증 단계, CVE handler는
지금 요청 경로 출처 없음), IDEMPOTENCY_KEY_INVALID, IDEMPOTENT_REQUEST_
MISMATCH. IDEMPOTENT_IN_FLIGHT도 이번 요청은 쓰기 전이지만 앞선 요청이
적용될 수 있어 MAYBE_APPLIED다.
- 쓰기 뒤 가능: BAD_PARAMETER(모든 층의 IllegalArgumentException),
MAPPING_FAILED(멱등성 응답 직렬화는 action이 끝난 뒤), DB_* 409 8종,
LOCK_ACQUISITION_TIMEOUT, 참조 도메인 400·409 6종, 선택 모듈 11종.
fileserver INTEGRITY_MISMATCH·MALWARE_DETECTED(422)는 레코드를 REJECTED로
쓴 뒤 던진다.
- 프론트와 다른 곳: 필드 목록 없는 400 VALIDATION_FAILED는 표로 NOT_APPLIED인데
V2는 effect가 없다. V2는 422 전체를 NOT_APPLIED로 보지만 fileserver 422는
MAYBE_APPLIED다. V3 참조 분류기는 400·422 전체를 NOT_APPLIED로 본다(참조
fixture용, 짝 백엔드에는 맞지 않는다).
버린 대안
- 백엔드 문서 표를 프론트 문서에 복사: 단계 정보는 백엔드 문서에 없다.
복사할 것이 아니라 프론트가 코드에서 읽은 판정이라 SHA와 파일:줄로 적었다.
- 프론트에 백엔드 소스를 읽는 검사 추가: 두 repo가 나란히 있어야만 돈다.
표를 SHA에 묶고, SHA를 올릴 때 표를 다시 확인하라고 적었다.
위험·한계
- "쓰기 전"은 지금 코드에서 handler에 닿는 출처를 센 결과다. 백엔드가
application bean에 @Validated를 달거나 JPA entity에 Bean Validation 제약을
넣으면 필드 목록 있는 VALIDATION_FAILED가 use case 안에서도 나온다. 백엔드에
이것을 막는 검사는 없다.
- 줄 번호는 5786126c 기준이다. 백엔드가 바뀌면 어긋난다.
검증
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- 표의 파일:줄은 백엔드 5786126c에서 grep·sed로 다시 열어 확인했다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.4
This commit is contained in:
@@ -165,12 +165,13 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정
|
||||
|
||||
- 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md)
|
||||
1절 "Envelope 키 존재 규칙"
|
||||
- 기준 버전: 백엔드 성숙도 리뷰 2026-11-01의 15절 결정(2026-11-03)을 반영한 본.
|
||||
값이 null인 필드는 키째 생략한다. 백엔드에 이 변경의 커밋이 생기면 그 SHA로
|
||||
바꾼다.
|
||||
- 기준 커밋: 백엔드 `5786126c`. `http-contract.md`는 `34565130`에서 들어왔고
|
||||
`1400dc15`에서 마지막으로 바뀌었다. 값이 null인 필드는 키째 생략한다. 백엔드
|
||||
기준 커밋을 올리면 6.1절 표를 같은 변경에서 다시 확인한다.
|
||||
- 프론트에서 Envelope를 읽는 곳: V2 `src/adapters/http/schema-registry.ts`와
|
||||
`src/adapters/http/client.ts`. V3 실행기는 Envelope 없이 DTO를 검증한다
|
||||
(`src/adapters/http/index.ts` V2 주석).
|
||||
- 실패 Envelope의 `error.code`가 "적용 안 됨"인지는 6.1절이 정한다.
|
||||
|
||||
### 4.2 Status와 error
|
||||
|
||||
@@ -241,16 +242,81 @@ backend idempotency를 대체하지 않는다.
|
||||
|
||||
- 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md)
|
||||
2절 "멱등성 응답", 4절 "web 전용 오류 코드"
|
||||
- 기준 버전: 4.1절과 같다(백엔드 리뷰 2026-11-01 15절 결정, 2026-11-03).
|
||||
- 기준 커밋: 4.1절과 같다(백엔드 `5786126c`).
|
||||
- 프론트가 그 응답을 읽는 곳:
|
||||
- 키 생성·검사: `src/contracts/mutation-intent.ts` `isValidIdempotencyKey`
|
||||
- 결과 불명 재전송이 같은 키를 쓰고 `Retry-After`까지 기다리는 곳:
|
||||
`src/presentation/adapters/query/application-query.ts`
|
||||
- V2 거절 판정: `src/adapters/http/client.ts` `IDEMPOTENCY_REFUSALS`
|
||||
- V2 거절 판정: `src/adapters/http/client.ts` `IDEMPOTENCY_REFUSALS`와
|
||||
`fieldValidation`
|
||||
- V3 참조 기능 판정: `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts`
|
||||
(effect), `src/features/reference-feature/adapters/reference-http-gateway.ts`
|
||||
(code)
|
||||
|
||||
### 6.1 거절 code와 적용 여부
|
||||
|
||||
mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐는지 정해야 한다.
|
||||
|
||||
- `NOT_APPLIED`: 쓰기 전에 거절됐다. 다음 저장은 새 `Idempotency-Key`를 쓴다.
|
||||
- `MAYBE_APPLIED`: 쓰기 뒤에도 나올 수 있다. mutation 코디네이터가 키를 붙들고
|
||||
결과 불명으로 보인다. effect가 없는 실패도 이 값이다.
|
||||
|
||||
백엔드 `http-contract.md`는 code가 어느 단계에서 나오는지 적지 않는다. 아래 표는
|
||||
프론트가 백엔드 `5786126c`의 코드를 읽고 정한 판정이다. 같은 code가 쓰기 전과
|
||||
뒤에서 모두 나오면 "쓰기 뒤 가능"으로 둔다. 프론트는 code만 보고 둘을 가를 수
|
||||
없다.
|
||||
|
||||
| code (status) | 나오는 곳 | 단계 | 프론트 결과 | 백엔드 파일:줄 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `VALIDATION_FAILED` (400), details = 필드 목록 | 요청 본문 `@Valid` 실패, 컨트롤러 파라미터 제약 실패. 컨트롤러 메서드가 불리기 전 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:218-231`, `:346-368` |
|
||||
| `VALIDATION_FAILED` (400), details = 필드 목록 | `ConstraintViolationException`. 어느 층에서 던져도 이 handler가 받는다. 요청 경로에서 던지는 코드는 없다(application bean에 `@Validated` 없음, JPA entity에 Bean Validation 제약 없음, 직접 throw 없음) | 쓰기 전(현재 출처 없음) | `NOT_APPLIED` | `GlobalExceptionHandler.java:101-106` |
|
||||
| `VALIDATION_FAILED` (400), details = `{cause}` 또는 없음 | 본문을 읽지 못함(`HttpMessageNotReadableException`) | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:233-251` |
|
||||
| `VALIDATION_FAILED` (400), details = `{field, code}` | 페이지·정렬 파라미터. 목록 GET 컨트롤러가 use case 전에 검사한다 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:149-153`, `PageParams.java:27-33`, `SortParam.java:16-43` |
|
||||
| `IDEMPOTENCY_KEY_INVALID` (400) | KEYED 컨트롤러 첫 줄의 키 파싱 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyKeyHeader.java:32-38`, `PosterImagePublicationController.java:64` |
|
||||
| `IDEMPOTENT_REQUEST_MISMATCH` (422) | 멱등성 executor가 action 전에 판정 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyExecutor.java:102-103`, `:134-135` |
|
||||
| `IDEMPOTENT_IN_FLIGHT` (409) | 멱등성 executor가 action 전에 판정. 같은 키의 앞선 요청이 실행 중이다 | 이번 요청은 쓰기 전. 앞선 요청은 적용될 수 있다 | `MAYBE_APPLIED` | `IdempotencyExecutor.java:104-105`, `:136-137` |
|
||||
| `BAD_PARAMETER` (400) | 타입 변환 실패, 필수 파라미터·헤더 없음(쓰기 전). **어느 층이든 `IllegalArgumentException`**(use case·domain 포함) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `GlobalExceptionHandler.java:92-99`, `:108-116`, `:397-438` |
|
||||
| `MAPPING_FAILED` (400) | web 매퍼(쓰기 전), outbound ACL 매퍼(use case 안), 멱등성 응답 직렬화(action이 끝난 뒤) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `WorkLogWebMapper.java:36`, `RepoStatsAclMapper.java:14`, `JsonIdempotentResponseCodec.java:32`, `IdempotencyExecutor.java:229` |
|
||||
| `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_LOCK_TIMEOUT`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT` (409) | persistence 어댑터가 SQL·JPA 실패를 바꾼 것. 트랜잭션 안이나 commit에서 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FailureCategory.java:79-95`, `StandardSqlStateErrorMapping.java:46-52`, `PersistenceExceptionTranslator.java:131` |
|
||||
| `LOCK_ACQUISITION_TIMEOUT` (409) | 분산 락 대기 초과. use case 안 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `LockRegistryDistributedLock.java:50`, `:53` |
|
||||
| 참조 도메인 `WORKLOG_INVALID`, `POSTER_INVALID_STATE`, `POSTER_IMAGE_REQUIRED` (400), `WORKLOG_CONFLICT`, `POSTER_ALREADY_EXISTS`, `POSTER_IMAGE_ALREADY_PUBLISHED` (409) | application·domain 예외 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `DomainExceptionHandler.java:52-90` |
|
||||
| 선택 모듈 web-advanced `PATCH_REJECTED` (400), `PATCH_TEST_FAILED` (409) | patch 라이브러리. 부르는 코드가 단계를 정한다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 |
|
||||
| 선택 모듈 fileserver `BAD_REQUEST` (400), `FILE_ALREADY_EXISTS`, `FILE_NOT_READY`, `UPLOAD_OFFSET_MISMATCH`, `CONCURRENT_MODIFICATION` (409), `INTEGRITY_MISMATCH`, `MALWARE_DETECTED`, `INVALID_PATH`, `PATH_OUTSIDE_NAMESPACE` (422) | application·outbound 층. `INTEGRITY_MISMATCH`·`MALWARE_DETECTED`는 레코드를 `REJECTED`로 쓴 뒤 던진다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FileserverErrorCode.java:26-44`, `FinalizeUploadApplicationUseCase.java:211-224`, `:336-341` |
|
||||
|
||||
- application-notification의 `VALIDATION_FAILED`(`NotificationFailureCode`)는
|
||||
`ApiErrorCarrier`가 아니다. HTTP로는 500 `INTERNAL_ERROR`로 나가므로 표에 없다.
|
||||
- 표에 없는 400·409·422 code는 `MAYBE_APPLIED`로 본다.
|
||||
- 파일 위치(백엔드 repo 기준):
|
||||
- `GlobalExceptionHandler.java`: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/`
|
||||
- `PageParams.java`, `SortParam.java`: 같은 모듈 `.../web/pagination/`
|
||||
- `IdempotencyKeyHeader.java`: 같은 모듈 `.../web/http/`
|
||||
- `IdempotencyExecutor.java`: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/`
|
||||
- `JsonIdempotentResponseCodec.java`: `src/adapter/inbound/web-advanced/.../advanced/idempotency/`
|
||||
- `FailureCategory.java`, `StandardSqlStateErrorMapping.java`,
|
||||
`PersistenceExceptionTranslator.java`, `LockRegistryDistributedLock.java`:
|
||||
`src/adapter/outbound/persistence-jpa/`
|
||||
- `PosterImagePublicationController.java`, `WorkLogWebMapper.java`,
|
||||
`RepoStatsAclMapper.java`, `DomainExceptionHandler.java`: `src/sample-portfolio/`
|
||||
- `FileserverErrorCode.java`, `FinalizeUploadApplicationUseCase.java`:
|
||||
`src/application-fileserver/`
|
||||
|
||||
프론트 판정과 표가 다른 곳(고치면 이 줄을 지운다):
|
||||
|
||||
- 필드 목록이 없는 400 `VALIDATION_FAILED`(`{cause}`, details 없음,
|
||||
`{field, code}`)는 표로는 `NOT_APPLIED`다. V2(`client.ts` `fieldValidation`)는
|
||||
effect를 붙이지 않아 `MAYBE_APPLIED`가 된다.
|
||||
- V2는 code와 상관없이 422를 모두 `NOT_APPLIED`로 본다. 기본 배포의 422는
|
||||
`IDEMPOTENT_REQUEST_MISMATCH` 하나라 맞다. fileserver를 실은 배포의 422 4종은
|
||||
표로는 `MAYBE_APPLIED`다.
|
||||
- V3 참조 기능 분류기(`classifyProblem`)는 참조 fixture(problem+json)용이라
|
||||
400·422를 모두 `NOT_APPLIED`로 본다. V3를 짝 백엔드에 붙이면
|
||||
`BAD_PARAMETER`, `MAPPING_FAILED`, 도메인 400이 틀린다.
|
||||
|
||||
남은 위험: "쓰기 전"은 현재 코드에서 그 handler에 닿는 출처를 센 결과다. 백엔드가
|
||||
application bean에 `@Validated`를 달거나 JPA entity에 Bean Validation 제약을
|
||||
넣으면, 필드 목록이 있는 400 `VALIDATION_FAILED`가 use case 안에서도 나온다.
|
||||
백엔드에는 이것을 막는 검사가 없다.
|
||||
|
||||
## 7. Cursor pagination과 snapshot
|
||||
|
||||
Backend가 pagination을 선택할 때 새 response schema/operation version으로 다음
|
||||
|
||||
Reference in New Issue
Block a user