Loading...
Spring Framework Reference Documentation 7.0.2의 Error Responses의 한국어 번역본입니다.
아래의 경우에 피드백에서 신고해주신다면 반영하겠습니다.
감사합니다 :)
See equivalent in the Servlet stack
REST 서비스에 대한 일반적인 요구 사항은 error response의 body에 상세 정보를 포함하는 것입니다. Spring Framework는 "Problem Details for HTTP APIs" 명세, RFC 9457을 지원합니다.
다음은 이 지원을 위한 주요 추상화입니다:
ProblemDetail — RFC 9457 problem detail에 대한 표현으로, 명세에서 정의한 표준 필드와 비표준 필드 모두에 대한 단순한 컨테이너입니다.ErrorResponse — HTTP status, response header, 그리고 RFC 9457 형식의 body를 포함하는 HTTP error response 상세 정보를 노출하기 위한 계약입니다. 이를 통해 exception이 HTTP response로 어떻게 매핑되는지에 대한 상세 정보를 캡슐화하고 노출할 수 있습니다. 모든 Spring WebFlux exception은 이를 구현합니다.ErrorResponseException — 다른 구현체들이 편리한 기본 클래스로 사용할 수 있는 기본적인 ErrorResponse 구현입니다.ResponseEntityExceptionHandler — 모든 Spring WebFlux exception과, 모든 ErrorResponseException을 처리하고 body가 있는 error response를 렌더링하는 @ControllerAdvice를 위한 편리한 기본 클래스입니다.See equivalent in the Servlet stack
RFC 9457 response를 렌더링하기 위해, 어떤 @ExceptionHandler나 어떤 @RequestMapping 메서드에서도 ProblemDetail 또는 ErrorResponse를 반환할 수 있습니다. 이는 다음과 같이 처리됩니다:
ProblemDetail의 status 프로퍼티가 HTTP status를 결정합니다.ProblemDetail의 instance 프로퍼티는 아직 설정되어 있지 않은 경우 현재 URL path에서 설정됩니다.HttpMessageConverter는 ProblemDetail을 렌더링할 때 "application/json"보다 "application/problem+json"을 선호하며, 호환 가능한 media type을 찾을 수 없는 경우에도 이에 폴백합니다.Spring WebFlux exception과 모든 ErrorResponseException에 대해 RFC 9457 response를 활성화하려면, ResponseEntityExceptionHandler를 확장하고 Spring 설정에서 이를 @ControllerAdvice로 선언하면 됩니다. 이 핸들러에는 모든 내장 web exception을 포함하는, 어떤 ErrorResponse exception도 처리하는 @ExceptionHandler 메서드가 있습니다.
더 많은 exception handling 메서드를 추가할 수 있으며, 어떤 exception이든 ProblemDetail로 매핑하기 위해 protected 메서드를 사용할 수 있습니다.
WebFluxConfigurer가 있는 WebFlux Config를 통해 ErrorResponse 인터셉터를 등록할 수 있습니다. 이를 사용하여 어떤 RFC 9457 response라도 인터셉트하고 일부 동작을 수행할 수 있습니다.
See equivalent in the Servlet stack
두 가지 방법 중 하나로 비표준 필드를 가진 RFC 9457 response를 확장할 수 있습니다.
첫째, ProblemDetail의 "properties" Map에 값을 삽입합니다. Jackson 라이브러리를 사용할 때, Spring Framework는 response에서 이 "properties" Map이 언랩되어 top level JSON 프로퍼티로 렌더링되도록 보장하는 ProblemDetailJacksonMixin을 등록하며, 마찬가지로 deserialization 중에 알 수 없는 프로퍼티는 이 Map에 삽입됩니다.
또한 ProblemDetail을 확장하여 전용 비표준 프로퍼티를 추가할 수도 있습니다. ProblemDetail의 copy constructor는 서브클래스가 기존 ProblemDetail에서 쉽게 생성될 수 있도록 합니다. 예를 들어, 추가적인 비표준 필드를 가진 서브클래스로 exception의 ProblemDetail을 다시 생성하는 ResponseEntityExceptionHandler와 같은 @ControllerAdvice에서 이를 중앙집중적으로 수행할 수 있습니다.
See equivalent in the Servlet stack
error response 상세 정보를 커스터마이즈하고 국제화하는 것은 일반적인 요구 사항입니다. 또한 구현 세부 정보를 드러내지 않기 위해 Spring WebFlux exception에 대한 problem detail을 커스터마이즈하는 것은 좋은 관행입니다. 이 섹션은 이에 대한 지원을 설명합니다.
ErrorResponse는 "type", "title", 그리고 "detail"에 대한 message code와, "detail" 필드에 대한 message code argument를 노출합니다. ResponseEntityExceptionHandler는 이를 MessageSource를 통해 resolve하고 해당하는 ProblemDetail 필드를 갱신합니다.
message code에 대한 기본 전략은 다음 패턴을 따릅니다:
problemDetail.[type|title|detail].[fully qualified exception class name]
ErrorResponse는 일반적으로 기본 message code에 suffix를 추가하여 둘 이상의 message code를 노출할 수 있습니다. 아래 표는 Spring WebFlux exception에 대한 message code와 argument를 나열합니다:
| Exception | Message Code | Message Code Arguments |
|---|---|---|
HandlerMethodValidationException | (default) | {0} 모든 validation error를 나열합니다.<br>각 error에 대한 message code와 argument 역시 MessageSource를 통해 resolve됩니다. |
MethodNotAllowedException | (default) | {0} 현재 HTTP method, {1} 지원되는 HTTP method 목록 |
MissingRequestValueException | (default) | {0} 값에 대한 label (예: "request header", "cookie value", …), {1} 값 이름 |
NotAcceptableStatusException | (default) | {0} 지원되는 media type 목록 |
NotAcceptableStatusException | (default) + ".parseError" | |
ServerErrorException | (default) | {0} 클래스 생성자에 제공된 실패 이유 |
UnsupportedMediaTypeStatusException | (default) | {0} 지원되지 않는 media type, {1} 지원되는 media type 목록 |
UnsupportedMediaTypeStatusException | (default) + ".parseError" | |
UnsatisfiedRequestParameterException | (default) | {0} 파라미터 조건 목록 |
WebExchangeBindException | (default) | {0} 글로벌 error 목록, {1} 필드 error 목록.<br>각 error에 대한 message code와 argument 역시 MessageSource를 통해 resolve됩니다. |
NoResourceFoundException | (default) | {0} resource를 찾기 위해 사용된 request path (또는 그 일부) |
다른 exception과 달리,<br>
WebExchangeBindException과HandlerMethodValidationException에 대한 message argument는<br>MessageSourceresource bundle을 통해서도 커스터마이즈할 수 있는<br>MessageSourceResolvableerror 목록을 기반으로 합니다.<br>자세한 내용은<br>Customizing Validation Errors을 참조하십시오.
See equivalent in the Servlet stack
클라이언트 애플리케이션은 WebClient를 사용할 때 WebClientResponseException을, RestTemplate을 사용할 때 RestClientResponseException을 catch할 수 있으며, 이들의 getResponseBodyAs 메서드를 사용하여 error response body를 ProblemDetail 또는 ProblemDetail의 서브클래스와 같은 임의의 대상 타입으로 디코딩할 수 있습니다.
API Versioning
Web Security