118 lines
12 KiB
Markdown
118 lines
12 KiB
Markdown
---
|
|
title: Spring Framework — ProblemDetail (RFC 7807 / RFC 9457) 지원
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-error-envelope, rfc7807, rfc9457, spring, problem-detail, error-format, official-doc]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-operational-error-observability-foundation, feature-boundary-validation-mapping-contract, feature-business-rule-validation-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Spring Framework — ProblemDetail (RFC 7807 / RFC 9457) 지원
|
|
|
|
> Layer: `raw/official-docs/` — Spring Framework Reference (7.0.x), "REST Exceptions" 섹션. Spring 6+ 의 기본 RFC 9457 (구 7807) 통합의 1차 근거.
|
|
> ca-tmpl Topic 4 (Error Envelope) 의 **대안 1 (ProblemDetail)** 의 Spring 구현체 비교 근거. ca-tmpl 이 custom envelope 을 채택했을 때 우회되는 Spring 기본 인프라의 범위를 평가하기 위함.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-operational-error-observability-foundation]] | ca-tmpl Topic 4 (Error Envelope) 대안 비교 — Spring `ProblemDetail` 자동 핸들링 (built-in exception → RFC 9457) 우회 비용 평가 근거 |
|
|
| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | `MethodArgumentNotValidException` → ProblemDetail 자동 변환 vs custom envelope 매핑 boilerplate 비교 근거 |
|
|
| [[raw/branch-notes/feature-business-rule-validation-contract]] | `ErrorResponse` 인터페이스 + `MessageSource` i18n 파이프라인 vs custom envelope 의 i18n 구현 비교 근거 |
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl 이 ProblemDetail 을 forbidden 으로 둔 결정의 비용을 가늠하려면 "표준을 채택했을 때 무엇이 공짜로 따라오는지" 를 알아야 함. Spring 은 RFC 9457 을 기본 지원하므로 custom envelope 을 택하면 그 인프라를 의식적으로 우회하는 셈.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Spring Framework (VMware / Broadcom)
|
|
- 발행일: rolling docs (Spring 7.0.x reference, current RFC 9457 기준)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Main Abstractions — ProblemDetail] "`ProblemDetail` — representation for an RFC 9457 problem detail; a simple container for both standard fields defined in the spec, and for non-standard ones."
|
|
|
|
> [§Main Abstractions — ErrorResponse] "`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."
|
|
|
|
> [§mvc-ann-rest-exceptions-render — 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`."
|
|
|
|
> [§mvc-ann-rest-exceptions-non-standard — Non-Standard Fields] "In Spring Boot, the `spring.mvc.problemdetails.enabled` property autoconfigures a `ResponseEntityExceptionHandler` that handles built-in exceptions with problem details."
|
|
|
|
> [§mvc-ann-rest-exceptions-i18n — Customization and i18n] "An `ErrorResponse` exposes message codes for \"type\", \"title\", and \"detail\", as well as message code arguments for the \"detail\" field. `ResponseEntityExceptionHandler` resolves these through a `MessageSource` and updates the corresponding `ProblemDetail` fields accordingly."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SPRING-PD-C1 | Spring 의 `ProblemDetail` 은 **RFC 9457** problem detail 의 representation 이며, spec 표준 필드 + non-standard 필드 둘 다를 담는 simple container | [§Main Abstractions — ProblemDetail] "`ProblemDetail` — representation for an RFC 9457 problem detail; a simple container for both standard fields defined in the spec, and for non-standard ones." | `official-vendor-doc` | Spring 6+ / 7.0.x 의 ProblemDetail 사용 | RFC 7807 호환성을 별도로 보장한다는 뜻은 아님 — Spring docs 가 9457 기준 기술 (9457 이 7807 을 obsolete) |
|
|
| SPRING-PD-C2 | `ErrorResponse` contract 는 HTTP status / headers / RFC 9457 body 를 함께 노출하며, **모든 Spring MVC 예외가 이 인터페이스를 구현** | [§Main Abstractions — ErrorResponse] "`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." | `official-vendor-doc` | Spring MVC 의 built-in 예외 (`MethodArgumentNotValidException`, `NoResourceFoundException` 등) | 사용자 정의 예외가 자동으로 `ErrorResponse` 가 된다는 뜻은 아님 — 명시적 구현 필요 |
|
|
| SPRING-PD-C3 | `@ControllerAdvice` 로 등록한 `ResponseEntityExceptionHandler` 가 모든 `ErrorResponse` 예외 (built-in 포함) 를 처리하며, custom 예외 → `ProblemDetail` 매핑용 protected method 를 사용할 수 있음 | [§mvc-ann-rest-exceptions-render — 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`." | `official-vendor-doc` | RFC 9457 응답을 활성화한 Spring MVC application | `@ControllerAdvice` 없이도 자동 활성화된다는 뜻은 아님 — 명시적 등록 필요 (Boot 의 autoconfigure 는 별도 §) |
|
|
| SPRING-PD-C4 | Spring Boot 의 `spring.mvc.problemdetails.enabled` property 가 `ResponseEntityExceptionHandler` 를 autoconfigure → built-in 예외를 problem details 로 처리 | [§mvc-ann-rest-exceptions-non-standard — Non-Standard Fields] "In Spring Boot, the `spring.mvc.problemdetails.enabled` property autoconfigures a `ResponseEntityExceptionHandler` that handles built-in exceptions with problem details." | `official-vendor-doc` | Spring Boot application 에서 problem detail 자동 활성화 | property 의 default 값이 `true` 라는 뜻은 아님 — 본 인용 범위 밖, Boot docs 별도 확인 필요 |
|
|
| SPRING-PD-C5 | `ErrorResponse` 는 "type"/"title"/"detail" 의 message code 와 detail 의 arguments 를 노출 → `MessageSource` 로 해석되어 `ProblemDetail` 필드에 반영됨 (Spring 표준 i18n 파이프라인) | [§mvc-ann-rest-exceptions-i18n — Customization and i18n] "An `ErrorResponse` exposes message codes for \"type\", \"title\", and \"detail\", as well as message code arguments for the \"detail\" field. `ResponseEntityExceptionHandler` resolves these through a `MessageSource` and updates the corresponding `ProblemDetail` fields accordingly." | `official-vendor-doc` | i18n 이 필요한 Spring MVC + ProblemDetail 사용 | RFC 7807/9457 spec 차원의 i18n 표준이 존재한다는 뜻은 아님 — Spring 의 `MessageSource` 통합이 vendor-specific |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `SPRING-PD-C1`: `ProblemDetail` 이 RFC 9457 representation 이며 standard + non-standard 필드를 모두 담음
|
|
- `SPRING-PD-C2`: 모든 Spring MVC 예외가 `ErrorResponse` 구현 → built-in 예외 자동 RFC 9457 매핑 가능
|
|
- `SPRING-PD-C3`: `ResponseEntityExceptionHandler` + `@ControllerAdvice` 등록 방법
|
|
- `SPRING-PD-C4`: Spring Boot `spring.mvc.problemdetails.enabled` autoconfigure property 존재
|
|
- `SPRING-PD-C5`: `MessageSource` 기반 i18n 통합 메커니즘
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- RFC 7807 (legacy) 의 정확한 wire format 호환성 보장 (9457 이 7807 obsolete)
|
|
- `code` / `category` / `retryable` 같은 운영 친화적 필드가 ProblemDetail 의 표준 필드에 포함됨 (아님 — `properties` Map 또는 서브클래싱으로 추가)
|
|
- Bean Validation 오류 (`MethodArgumentNotValidException`) 가 자동으로 `errors[]` 풀이 형태로 변환됨 (별도 custom 핸들러 필요)
|
|
- `spring.mvc.problemdetails.enabled` 의 default 값 (Boot version 별 확인 필요)
|
|
- 성공 응답 envelope 의 권장 형태 (ProblemDetail 은 error-only spec)
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 의 custom envelope 채택 시 built-in 예외 → custom envelope 매핑 boilerplate 의 정확한 수량 (실측)
|
|
- `properties` Map / 서브클래싱 중 어느 쪽이 `code`/`category`/`retryable` 1급 표현에 적합한지
|
|
- WebFlux (reactive) 에서 같은 추상화가 동일하게 동작하는지 (본 페이지는 webmvc)
|
|
- Bean Validation field-level 오류를 ProblemDetail 의 `errors[]` 같은 형태로 풀이하는 community 패턴 (zalando/problem-spring-web 등 — 별도 확인)
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
|
|
|
|
- 응답 shape 핵심 (해석):
|
|
- `ProblemDetail` Jackson mixin 이 `properties` Map 을 top-level 로 unwrap → 확장 필드를 표준 필드와 같은 평면에 배치 가능
|
|
- `instance` 는 자동으로 request URL 경로로 채워짐
|
|
- `application/problem+json` 이 content negotiation 에서 우선됨
|
|
- **장점 (해석)**:
|
|
- Spring 의 모든 내장 예외 (`MethodArgumentNotValidException`, `NoResourceFoundException` 등) 가 이미 `ErrorResponse` 구현 → 기본 핸들링이 공짜
|
|
- `MessageSource` 연동으로 i18n 이 표준 메커니즘과 결합 (`problemDetail.title.<FQCN>` 키)
|
|
- 확장 필드는 `properties` Map 혹은 서브클래싱
|
|
- client 는 `WebClientResponseException.getResponseBodyAs(ProblemDetail.class)` 로 즉시 디코드
|
|
- **단점 (해석)**:
|
|
- 성공 응답 envelope 은 여전히 별도 설계 필요 → "성공도 envelope 으로 감싸고 싶다" 는 요구와 충돌
|
|
- `code`/`category`/`retryable` 을 1급으로 두려면 항상 확장 필드 + 자체 client 컨벤션을 강제해야 함 (결국 표준 위에 사실상 custom 레이어)
|
|
- Bean Validation 오류 → `errors[]` 형태로 풀어내는 일은 여전히 custom 핸들러 필요
|
|
- **ca-tmpl custom envelope 와의 차이 (해석)**:
|
|
- Spring 을 쓰면 ProblemDetail 은 "기본값", custom envelope 은 "기본값 끄기" 가 됨. 즉 ca-tmpl 은 명시적으로 표준 인프라를 비활성화하는 선택
|
|
- 그 비용은 "Spring 내장 예외 → custom envelope" 매핑 boilerplate
|
|
- **표준 준수 / lock-in / client 호환성 (해석)**:
|
|
- 표준 준수 ↑. Spring 생태계 lock-in 은 양방향 — ProblemDetail 을 쓰면 Spring 과 더 정합, custom 을 쓰면 framework-agnostic
|
|
- **localization / i18n 지원 여부 (해석)**:
|
|
- `MessageSource` 기반 자동 메시지 코드 해석 — Spring 의 표준 i18n 파이프라인 그대로 사용
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc / company-tech-blog:
|
|
- [[raw/official-docs/json-api-errors-spec]] (대안 3 — JSON:API errors)
|
|
- [[raw/official-docs/google-api-error-format]] (대안 2 — gRPC `google.rpc.Status`)
|
|
- [[raw/official-docs/graphql-errors-spec]] (대안 4 — GraphQL errors)
|
|
- [[raw/company-tech-blogs/stripe-error-format]] (대안 5 — Stripe custom envelope)
|
|
- canonical contract 섹션:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] §3 Structured API Response Contract, §6 Operational Error Category
|
|
- 본 source 의 위치: ca-tmpl Topic 4 — Error Envelope, **대안 1 구현체: Spring 6+ ProblemDetail**
|
|
- 인용하는 wiki: (미작성)
|