Files
clean-architecture-backend-…/docs/upgrade/2026-11-round9-contracts.md
T
DongHyeonka 377cf17653
pr / done (pull_request) Canceled after 0s
fix(http): 새 눈 리뷰가 찾은 계약 빈틈을 닫는다
PR 전 리뷰(계약·시험 렌즈, 구조 리뷰) 발견을 고친다.

- 상태만 아는 503·429(Spring이 던진 ResponseStatusException 등)가 SERVER_BUSY·
  RATE_LIMIT_EXCEEDED로 나가면서 Retry-After를 싣지 않았다. error dispatch는
  싣는데 handleExceptionInternal은 안 실었다. registry 값을 같은 advisor로 단다.
- virtual thread admission filter가 보안 chain 앞이라 cross-origin 거절 503에 CORS
  헤더가 없어 브라우저가 본문도 Retry-After도 못 읽었고, 인증 없는 요청도 permit을
  썼다. chain 바로 뒤(-99)로 옮겼다.
- permit을 한 번만 돌려주는 가드, onTimeout 뒤 onComplete, onStartAsync 재등록을
  지키는 시험이 없었다. 둘을 더했다.
- stream 위치 규칙이 writer와 WebStreamEvidence 두 곳에 있었다. 증거에
  requireNext를 두고 writer가 쓰기 전에 부른다.
- fileserver Retry-After가 좁히기 식을 복사했고 SERVER_BUSY 값을 두 번 적었다.
  ErrorResponseFactory.effectiveRetryable 하나를 같이 쓰고, 공용 이름의 code는
  RetryAfterAdvisor 값을 읽는다. 재시도 불가 code 전부가 헤더를 싣지 않는지 본다.
- batch 전체 성공의 results[]에 "error": null이 나갔다. 항목 record가 null을
  생략한다. batch 시험은 envelope wire 규칙을 실은 mapper로 키 집합을 본다.
- 알림 channel·locale 파싱이 두 controller에 있었다. NotificationVocabulary
  하나로 모으고, detail은 web 검증 어휘(INVALID)를 쓴다. 예외 이름을
  NotificationFieldRejectedException으로 바꿨다(THROWABLES_ARE_NAMED_EXCEPTION).
  template 게시의 거절 시험을 더했다.
- patch 전체 검증 설명에서 상태 전이 예를 뺐다. 검증 대상은 web 표현 DTO이고
  업무 규칙은 유스케이스의 것이다.
- web README의 RetryAfterHint 예시, upgrade 안내 행 넷(bulk 문구·null 키, stream
  역행 항목, 상태만 아는 503·429의 Retry-After, admission filter 순서)과 부분 실패의
  part 짚기(index)를 적었다.

Refs: RR9-03-01, RR9-03-02, RR9-03-06, RR9-03-13, RR9-03-15, RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-27
2026-11-13 05:09:45 +09:00

6.2 KiB

업그레이드 안내 — 2026-11 HTTP 계약·오류 코드 정리

  • 범위: web-advanced(patch·stream·virtual thread), fileserver·notification HTTP, 전송 오류 코드를 약속한 계약에 맞춘 변경. 응답 코드·모양이 바뀐 곳이 있다. 아래 표가 그 목록이다.
  • 근거: 2026-11-12 전체 리뷰(docs/reviews/2026-11-12-round9-review/)의 계약·오류 코드 발견

1. 누가 읽나

이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스와, 그 서비스의 HTTP 응답을 읽는 client 팀이 읽는다.

2. 할 일

# 할 일 안 하면 해당 서비스
1 JsonMergePatchApplier·JsonPatchApplier를 만드는 코드에 셋째 인자로 Boot의 jakarta.validation.Validator bean을 넘긴다 컴파일이 실패한다 web-advanced patch를 쓰는 서비스
2 patch 거부를 읽는 client는 PATCH_REJECTED(400) 하나로 본다. 전에는 JSON이 아닌 본문이 500 INTERNAL_ERROR, 빈 문서·연산 모양 오류·merge 깊이 초과가 400 BAD_PARAMETER, 너무 깊은 pointer가 403 PATCH_PATH_FORBIDDEN이었다 client가 옛 코드로 분기하던 곳이 다른 코드를 받는다 patch route를 둔 서비스와 그 client
3 patch 결과가 Bean Validation 제약을 어기면 400 VALIDATION_FAILED와 필드별 details가 나간다. patch 대상 타입의 제약을 확인한다 전에는 제약을 어긴 객체가 그대로 저장 경로로 갔다 web-advanced patch를 쓰는 서비스
4 스트림 Failure 기록의 code가 실패의 코드(예: STREAM_ITEM_TOO_LARGE) 또는 INTERNAL_ERROR다. DEPENDENCY_FAILURE로 분기하던 client를 고친다 그 분기가 다시는 맞지 않는다 NDJSON·JSON-seq stream을 읽는 client
5 virtual thread profile을 켠 배포는 이제 실제로 허가 상한을 건다. admission-limit이 부하에 맞는지 본다 전에는 상한이 없어 모든 요청이 들어왔다. 이제 넘치면 503 SERVER_BUSY와 Retry-After: 1이다 app.web.advanced.mvc-virtual-threads.enabled=true인 배포
6 fileserver batch(POST /v1/files:batch)를 읽는 client는 success로 가른다. 모두 성공하면 success: true와 최상위 results[], 하나라도 실패하면 success: false, error.code = BATCH_PARTIAL_FAILURE, part별 error.details[](index, status, id, code, message)다. 부분 실패에서는 part를 요청 순서 index로 짚는다(clientPartId는 전부 성공한 results[]에만 있다) 전에는 실패가 있어도 success: true이고 결과가 data.results[]에 있었다. 옛 경로로 읽던 client는 결과를 못 찾는다 fileserver를 쓰는 서비스와 그 client
7 BulkItemResult.error(index, code, message)를 부르던 코드를 BulkItemResult.error(index, ApiErrorCode)로 바꾼다. 문구는 code의 category 고정 문구가 된다 컴파일이 실패한다 bulk endpoint를 둔 서비스
8 서버 포화 거절을 읽는 client는 SERVER_BUSY(503, retryable, Retry-After: 1)로 본다. web-advanced ADMISSION_REFUSED, fileserver instance·전송 pool 포화의 TRANSFER_ADMISSION_REJECTED(429), gRPC 포화의 RESOURCE_EXHAUSTED/RATE_LIMIT_EXCEEDED가 이 코드로 바뀌었다(gRPC status는 UNAVAILABLE). 호출자 자신의 동시 전송 초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다 옛 코드로 분기하던 재시도 로직이 맞지 않는다. 자바에서 WebAdvancedError.ADMISSION_REFUSED를 참조하던 코드는 컴파일이 실패한다 세 전송의 client, web-advanced 코드를 참조하던 서비스
9 컨테이너가 넘긴 503(필터의 sendError(503) 등)은 SERVER_BUSY다. 비동기 요청 시간 초과만 REQUEST_TIMEOUT이다 전에는 모든 503이 REQUEST_TIMEOUT이었다 web을 쓰는 모든 서비스의 client
10 알림 template 게시 경로를 /notification-templates에서 /notificationTemplates로 바꾼다(prefix 뒤) 옛 경로는 404다 알림 template을 게시하는 client와 배포 스크립트
11 알림 제출·template 게시의 모르는 channel·slot·locale·fallbackLocale은 400 VALIDATION_FAILED와 그 필드를 짚는 details다(전에는 details 없는 BAD_PARAMETER) BAD_PARAMETER로 분기하던 client가 다른 코드를 받는다 알림 HTTP client
12 이름 없이 올린 파일의 표시 이름이 upload.bin에서 file이 된다(모든 전송에서 같다) 표시 이름이 바뀐다. 동작은 같다 fileserver를 쓰는 서비스
13 fileserver ATOMIC_PUBLISH_UNSUPPORTED(재시도 불가 code)는 더 이상 Retry-After를 싣지 않는다. 본문 retryable=false와 맞춘 것이다 그 헤더로 재시도하던 client가 재시도하지 않는다(원래 재시도해도 소용없는 실패다) fileserver client
14 브라우저 client는 Content-Range를 읽을 수 있다(CORS 노출 목록에 더함) — 더하기만 한 변경 fileserver 다운로드를 이어 받는 브라우저 client
15 bulk 부분 실패의 error.message가 영어 문구에서 category 고정 문구(ClientErrorMessages)로 바뀌었다. 항목(details[])은 자기 상태에 맞는 키만 싣는다(성공 항목에 code·message 키 없음, 실패 항목에 id 키 없음) 문구로 분기하던 client(원래 하면 안 된다)나 null 키를 기대하던 strict client가 다르게 본다 bulk endpoint를 둔 서비스의 client
16 스트림에서 위치가 앞 항목보다 크지 않은 항목은 이제 나가지 않고, 스트림이 INTERNAL_ERROR Failure 기록으로 끝난다(전에는 그 항목을 쓴 뒤 끝났다) 서버 결함이 있는 source의 client가 마지막 항목을 받지 않는다 NDJSON·JSON-seq stream을 읽는 client
17 상태만 아는 503·429(Spring이 던진 ResponseStatusException 등)도 registry의 Retry-After를 싣는다 — 헤더를 더하기만 한 변경 web을 쓰는 서비스의 client
18 virtual thread admission filter가 Spring Security chain 뒤에서 돈다. 인증·권한에서 거절된 요청은 허가를 쓰지 않고, 거절 503에 CORS 헤더가 붙는다 — virtual thread profile을 켠 배포