donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
docs/ca-skeleton-frontend-runtime-adapter-features
llm-wiki/raw/official-docs/spring-problem-detail.md
T

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 tags related_projects related_branches created last_reviewed
Spring Framework — ProblemDetail (RFC 7807 / RFC 9457) 지원 official-doc https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html raw high
ca-error-envelope
rfc7807
rfc9457
spring
problem-detail
error-format
official-doc
ca-skeleton-operational-contract
feature-operational-error-observability-foundation
feature-boundary-validation-mapping-contract
feature-business-rule-validation-contract
2026-05-22 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

핵심 인용 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink