문제
짝 백엔드는 이제 값이 null인 필드를 키째 뺀다(백엔드
docs/web/http-contract.md §1). V2 Envelope 스키마
(src/adapters/http/schema-registry.ts)는 두 곳에서 "키 없음"을 null과
다르게 읽는다.
- 성공 응답의 data: z.unknown()은 키가 없으면 거절한다(zod 4). 백엔드가
data:null을 빼고 보낸 성공이 ENVELOPE_MISMATCH 실패가 된다. data:null은
그대로 통과한다.
- meta.requestId·traceId가 필수다. 백엔드는 요청 id 필터 앞에서 끊긴
응답(보안 entry point 등)에서 이 키를 뺄 수 있다고 적는다. 그러면 실패
Envelope 전체가 거절되어 백엔드 error.code가 HTTP_FAILURE로 바뀐다.
error.details(키 없음 허용), meta.correlationId(선택), meta.page(strip)는
이미 키가 없어도 받는다.
고른 방법
- data를 z.unknown().default(null)로 둔다. 키가 없으면 스키마가 null을
채우므로 client.ts의 "data" in 검사와 payload 검증이 data:null과 같은
길을 탄다. 정규화가 wire 스키마 한 곳에 있다.
- meta.requestId·traceId를 optional로 둔다. safeMeta()는 이미 키가 없는
경우를 처리한다.
버린 대안
- client.ts에서 "data" in 검사를 빼고 data ?? null로 읽기: 스키마와
클라이언트 두 곳이 같은 규칙을 나눠 갖는다.
- 성공의 error:null, 실패의 data:null도 다시 받기: 백엔드가 더는 보내지
않는 모양이다. 최상위 strict는 그대로 둔다.
위험·한계
- meta id가 없는 Envelope도 이제 유효하다. 그런 응답의 HttpResult.meta와
AppFailure에는 requestId·traceId가 없다(이전에는 응답 전체가 거절됐다).
- V3 실행기는 Envelope를 읽지 않는다(DTO 자체를 검증). 이 변경은 V2
경로만 바꾼다. bulk Envelope(results)는 프론트에 쓰는 곳이 없어 다루지
않았다.
검증
- RED: tests/integration/http-client.test.ts "envelope keys the paired
backend omits" 5행 중 2행 실패. data 키 없는 성공이 ok:false, id 키 없는
403이 code HTTP_FAILURE.
- GREEN: 같은 5행 통과. tests/integration/http-client·http-diagnostics·
http-execution-contract·auth-recovery·legacy-http-credential-authority,
tests/runtime-schema 8 files 150 tests 통과. tsc app·test 통과, 바꾼
파일 eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15