93 lines
11 KiB
Markdown
93 lines
11 KiB
Markdown
---
|
|
title: Spring Framework Reference — Exceptions (Spring MVC REST)
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
|
|
archive_url:
|
|
vendor: VMware / Broadcom (Spring)
|
|
related_branches: [feature-boundary-validation-mapping-contract, feature-business-rule-validation-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-tmpl, error-handling, spring-mvc]
|
|
status: raw
|
|
confidence: high
|
|
created: 2026-05-28
|
|
last_reviewed: 2026-05-28
|
|
---
|
|
|
|
# Spring Framework Reference — Exceptions (Spring MVC REST)
|
|
|
|
> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/` 에 `source-summary-template` 형식으로 별도 작성. 원본은 raw 에 영구 보관.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | Mapper / deserialization 실패의 error category 분류 결정 (블라인드 B3). `HttpMessageNotReadableException` → VALIDATION 으로의 매핑 근거. `ResponseEntityExceptionHandler` 가 normative 하게 처리하는 예외 목록 확인 |
|
|
| [[raw/branch-notes/feature-business-rule-validation-contract]] | `MethodArgumentNotValidException` (Bean Validation 실패) 의 HTTP 400 매핑 및 `ErrorResponse` 계약 근거 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
|
|
- 아카이브 URL: (미제공)
|
|
- 저자 / 조직: Spring Framework 공식 문서 (VMware / Broadcom)
|
|
- 발행일: (지속 갱신 — 확인 시점 버전 7.0.7)
|
|
- 마지막 확인일: 2026-05-28
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-boundary-validation-mapping-contract` 에서 블라인드 B3 로 식별된 문제 — mapper 가 던지는 예외(`IllegalArgumentException`, MapStruct NPE, record canonical constructor `IllegalStateException`)와 `HttpMessageNotReadableException` 같은 Spring 내장 deserialization 예외의 error category(`VALIDATION` vs `INTERNAL`) 분류 근거가 없었다. 본 공식 문서는 Spring MVC 가 normative 하게 어떤 예외를 어떻게 처리하는지, `ErrorResponse` 계약이 무엇인지, `ResponseEntityExceptionHandler` 가 다루는 예외 목록을 직접 정의하므로 이 분류 결정의 primary 근거 자료로 보관한다.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§ Error Responses — main abstractions] "ErrorResponse — contract to expose HTTP error response details including HTTP status, response headers, and a body in the format of RFC 9457; this allows exceptions to encapsulate and expose the details of how they map to an HTTP response. All Spring MVC exceptions implement this."
|
|
|
|
> [§ Error Responses — main abstractions] "ResponseEntityExceptionHandler — convenient base class for an @ControllerAdvice that handles all Spring MVC exceptions, and any ErrorResponseException , and renders an error response with a body."
|
|
|
|
> [§ Error Responses — main abstractions] "ErrorResponseException — basic ErrorResponse implementation that others can use as a convenient base class."
|
|
|
|
> [§ Error Responses — Render] "To enable RFC 9457 responses for Spring MVC exceptions and for any ErrorResponseException , extend ResponseEntityExceptionHandler and declare it as an @ControllerAdvice in Spring configuration. The handler has an @ExceptionHandler method that handles any ErrorResponse exception, which includes all built-in web exceptions. You can add more exception handling methods, and use a protected method to map any exception to a ProblemDetail ."
|
|
|
|
> [§ Error Responses — Spring Boot note] "In Spring Boot, the spring.mvc.problemdetails.enabled property autoconfigures a ResponseEntityExceptionHandler that handles built-in exceptions with problem details."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SPRING-MVC-EXC-C1 | `ErrorResponse` 는 HTTP error response 의 status / headers / body(RFC 9457 형식) 를 노출하는 계약이며, **모든 Spring MVC 내장 예외가 이를 구현**한다 | [§ main abstractions] "contract to expose HTTP error response details including HTTP status, response headers, and a body in the format of RFC 9457 [...] All Spring MVC exceptions implement this." | `official-vendor-doc` | Spring Framework 6.x / 7.x 의 모든 Spring MVC 내장 예외 | 사용자 정의 예외(`IllegalArgumentException`, mapper NPE 등)가 자동으로 `ErrorResponse` 를 구현한다는 것은 증명하지 않음 |
|
|
| SPRING-MVC-EXC-C2 | `ResponseEntityExceptionHandler` 는 `@ControllerAdvice` 의 편의 base class 로, **모든 Spring MVC 예외 + `ErrorResponseException` 을 처리**하고 body 가 있는 error response 를 렌더링한다 | [§ main abstractions] "convenient base class for an @ControllerAdvice that handles all Spring MVC exceptions, and any ErrorResponseException , and renders an error response with a body." | `official-vendor-doc` | `ResponseEntityExceptionHandler` 를 extends 하는 `@ControllerAdvice` | 사용자 정의 예외(`IllegalArgumentException` 등)를 자동 처리한다는 것은 증명하지 않음 — 별도 `@ExceptionHandler` 필요 |
|
|
| SPRING-MVC-EXC-C3 | RFC 9457 응답을 활성화하려면 `ResponseEntityExceptionHandler` 를 extends 하고 `@ControllerAdvice` 로 선언해야 하며, 이 handler 의 `@ExceptionHandler` 메서드는 **모든 built-in web exception** 을 포함하는 모든 `ErrorResponse` 예외를 처리한다 | [§ Render] "extend ResponseEntityExceptionHandler and declare it as an @ControllerAdvice in Spring configuration. The handler has an @ExceptionHandler method that handles any ErrorResponse exception, which includes all built-in web exceptions." | `official-vendor-doc` | Spring Framework 6.x / 7.x + `@ControllerAdvice` 구성 | `@ExceptionHandler` 의 controller-local vs global 우선순위는 본 인용이 직접 명시하지 않음 (Spring docs 다른 섹션 "Exceptions" 참조 필요) |
|
|
| SPRING-MVC-EXC-C4 | `HttpMessageNotReadableException` 은 Spring MVC 가 `ResponseEntityExceptionHandler` 를 통해 normative 하게 처리하는 예외 목록에 포함되며, i18n message code 를 통해 커스터마이즈 가능하다 | [§ Customization and i18n — table] `HttpMessageNotReadableException` → message code `(default)` (표에서 직접 나열됨, line 1997 in fetched text) | `official-vendor-doc` | Spring MVC 의 `ResponseEntityExceptionHandler` + `HttpMessageNotReadableException` | HTTP status code(`400 Bad Request`)는 본 "Error Responses" 페이지의 message code 표에서 명시적으로 나열되지 않음 — HTTP status 는 `HttpMessageNotReadableException` 의 `ErrorResponse` 구현 내부(Spring source)에서 정의됨 |
|
|
| SPRING-MVC-EXC-C5 | `MethodArgumentNotValidException` 은 Spring MVC 가 `ResponseEntityExceptionHandler` 를 통해 normative 하게 처리하는 예외 목록에 포함되며, message code arguments 로 `{0}` global errors list 와 `{1}` field errors list 를 제공한다 | [§ Customization and i18n — table] "`MethodArgumentNotValidException` (default) {0} the list of global errors, {1} the list of field errors. Message codes and arguments for each error are also resolved via MessageSource ." | `official-vendor-doc` | Spring MVC Bean Validation (`@Valid` / `@Validated`) 처리 | HTTP status code(`400 Bad Request`) 는 `MethodArgumentNotValidException` 의 `ErrorResponse` 구현 내부에서 정의됨 — 본 페이지에서 직접 명시되지 않음 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `SPRING-MVC-EXC-C1`: 모든 Spring MVC 내장 예외(including `HttpMessageNotReadableException`, `MethodArgumentNotValidException`)는 `ErrorResponse` 를 구현하며, Spring 이 RFC 9457 형식으로 error response 를 렌더링할 수 있다
|
|
- `SPRING-MVC-EXC-C2`: `ResponseEntityExceptionHandler` 가 모든 Spring MVC 내장 예외와 `ErrorResponseException` 을 기본 처리한다
|
|
- `SPRING-MVC-EXC-C3`: `@ControllerAdvice` + `ResponseEntityExceptionHandler` extends 가 RFC 9457 응답의 normative 활성화 방법이다
|
|
- `SPRING-MVC-EXC-C4`: `HttpMessageNotReadableException` 은 Spring MVC normative exception handling 목록에 있다
|
|
- `SPRING-MVC-EXC-C5`: `MethodArgumentNotValidException` 은 Spring MVC normative exception handling 목록에 있다
|
|
|
|
- 이 자료가 증명하지 않는 것:
|
|
- 사용자 정의 예외(`IllegalArgumentException`, mapper NPE, record constructor `IllegalStateException`)가 자동으로 `VALIDATION` 또는 `INTERNAL` 카테고리로 분류된다는 것 — Spring 은 이들을 기본 처리하지 않음
|
|
- `HttpMessageNotReadableException` 의 정확한 HTTP status code(400) — 이는 Spring source 의 `ErrorResponse` 구현에 있으며 별도 확인 필요
|
|
- mapper layer 에서 발생하는 예외(`MapStruct NPE`, `IllegalArgumentException`)의 올바른 error category(`MAPPING_FAILED` / `VALIDATION` / `INTERNAL`) — 이 분류는 ca-tmpl 의 자체 operational contract 결정이며 본 Spring 문서가 직접 권고하지 않음
|
|
- `@ExceptionHandler` 의 controller-local vs `@ControllerAdvice` global 해석 우선순위 — 본 페이지에서 다루지 않음
|
|
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl 의 custom envelope 을 사용할 경우 `spring.mvc.problemdetails.enabled=false` 명시 여부 (SPRING-MVC-EXC-C5 및 `Claims To Verify` 항목과 연결)
|
|
- mapper 에서 발생하는 `IllegalArgumentException` / `IllegalStateException` 에 대한 별도 `@ExceptionHandler` 또는 `ErrorResponseException` wrap 여부 결정 (B3 블라인드 해소를 위한 operational contract 결정)
|
|
|
|
## 메모 / Notes
|
|
|
|
- 본 페이지 URL (`/mvc-ann-rest-exceptions.html`) 은 Spring Framework 7.0.7 기준. 6.x 에서도 동일 경로이나 버전 간 미묘한 차이 있을 수 있음 — `spring.mvc.problemdetails.enabled` 는 Spring Boot 3.x (= Spring Framework 6.x) 에서 도입됨.
|
|
- `HttpMessageNotReadableException` 의 HTTP status(400) 를 직접 확인하려면 Spring source `org.springframework.web.server.ResponseStatusException` 계층 또는 `HttpMessageNotReadableException.getStatusCode()` 확인 필요.
|
|
- B3 블라인드 해소 경로: `HttpMessageNotReadableException` → Spring 이 400 으로 처리 (ErrorResponse 구현체) → ca-tmpl 에서 `VALIDATION` 카테고리로 재분류 가능. mapper NPE / `IllegalArgumentException` → Spring 기본 처리 대상 아님 → ca-tmpl 에서 별도 `@ExceptionHandler` 추가 또는 `INTERNAL` / `MAPPING_FAILED` 카테고리 명시 결정 필요.
|
|
- 추가로 봐야 할 동일 출처 페이지: Spring MVC "Exceptions" 섹션 (`/webmvc/mvc-controller/ann-exceptionhandler.html`) — `@ExceptionHandler` scope 와 resolution order 상세
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: [[raw/official-docs/spring-problem-detail]] (Spring ProblemDetail / RFC 9457 Spring 6 지원 — already archived)
|
|
- 같은 주제 다른 official-doc: [[raw/official-docs/problem-detail-rfc-7807]] (IETF RFC 7807 원문 — already archived)
|
|
- 이 자료를 인용한 wiki 요약: `wiki/concepts/spring-mvc-exception-handling` (생성 시)
|