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
6.2 KiB
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을 켠 배포 |