Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

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 파이프라인 그대로 사용

같은 주제 다른 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: (미작성)

12 KiB Raw Permalink Blame History