pr / done (pull_request) Canceled after 0s
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
33 lines
6.2 KiB
Markdown
33 lines
6.2 KiB
Markdown
# 업그레이드 안내 — 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을 켠 배포 |
|