|
|
|
@ -4827,47 +4827,50 @@ include::webmvc-cors.adoc[leveloffset=+1] |
|
|
|
== REST API exceptions |
|
|
|
== REST API exceptions |
|
|
|
[.small]#<<web-reactive.adoc#webflux-ann-rest-exceptions, WebFlux>># |
|
|
|
[.small]#<<web-reactive.adoc#webflux-ann-rest-exceptions, WebFlux>># |
|
|
|
|
|
|
|
|
|
|
|
A common requirement for REST services is to include error details in the body of the |
|
|
|
A common requirement for REST services is to include details in the body of an error |
|
|
|
response. The Spring Framework provides support for |
|
|
|
response. The Spring Framework supports the "Problem Details for HTTP APIs" |
|
|
|
https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807] formatted error responses. |
|
|
|
specification, https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807]. These are the main |
|
|
|
|
|
|
|
abstractions for this support: |
|
|
|
Main abstractions and supporting infrastructure: |
|
|
|
|
|
|
|
|
|
|
|
- `ProblemDetail` -- representation for an RFC 7807 problem detail; a simple container |
|
|
|
- `ProblemDetail` in the `spring-web` module is the core abstraction that represents an |
|
|
|
for both standard fields defined in the spec, and for non-standard ones. |
|
|
|
RFC 7807 problem detail. It helps to enable a range of features in Spring MVC for the |
|
|
|
- `ErrorResponse` -- contract to expose HTTP error response details including HTTP |
|
|
|
handling and rendering of such responses. |
|
|
|
status, response headers, and a body in the format of RFC 7807; this allows exceptions to |
|
|
|
- `ErrorResponse` is an interface that defines an error response, including status, headers, |
|
|
|
encapsulate and expose the details of how they map to an HTTP response. All Spring MVC |
|
|
|
and `ProblemDetail` as its body. All Spring web exceptions implement this interface, and |
|
|
|
exceptions implement this. |
|
|
|
thus encapsulate a default opinion on how they map to an RFC 7807 error response. |
|
|
|
- `ErrorResponseException` -- basic `ErrorResponse` implementation that others |
|
|
|
- `ErrorResponseException` is a `RuntimeException` that implements `ErrorResponse`, which |
|
|
|
can use as a convenient base class. |
|
|
|
can be raised directly or serve as a base class for other exceptions. |
|
|
|
- `ResponseEntityExceptionHandler` -- convenient base class for an |
|
|
|
- {api-spring-framework}/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandler.html[`ResponseEntityExceptionHandler`] |
|
|
|
<<mvc-ann-controller-advice,@ControllerAdvice>> that handles all Spring MVC exceptions, |
|
|
|
provides handling for Spring MVC exceptions and for any `ErrorResponseException`. |
|
|
|
and any `ErrorResponseException`, and renders an error response with a body. |
|
|
|
Applications can extend this as an <<mvc-ann-controller-advice>> to enable RFC 7807 support. |
|
|
|
|
|
|
|
|
|
|
|
You can return `ProblemDetail` or `ErrorResponse` directly from `@RequestMapping` or |
|
|
|
`ProblemDetail` and `ErrorResponse` are supported as return values from |
|
|
|
from `@ExceptionHandler` controller methods to render an RFC 7807 response as follows: |
|
|
|
`@ExceptionHandler` and `@RequestMapping` controller methods. The `status` property of |
|
|
|
|
|
|
|
`ProblemDetail` is used to set the response status, while the `instance` property is set |
|
|
|
- The `status` property of `ProblemDetail` determines the HTTP status. |
|
|
|
from the current URL path, if not already set. |
|
|
|
- The `instance` property of `ProblemDetail` is set from the current URL path, if not |
|
|
|
|
|
|
|
already set. |
|
|
|
The Jackson `HttpMessageConverter` returns "application/problem+json" as a preferred |
|
|
|
- For content negotiation, the Jackson `HttpMessageConverter` prefers |
|
|
|
choice to serialize `ProblemDetail` to JSON as part of content negotiation. If no suitable |
|
|
|
"application/problem+json" over "application/json" when rendering a `ProblemDetail`, |
|
|
|
media type is found to render a `ProblemDetail` response body, content negotiation falls |
|
|
|
and also falls back on it if no compatible media type is found. |
|
|
|
back on "application/problem+json". |
|
|
|
|
|
|
|
|
|
|
|
You can extend an RFC 7807 response with non-standard fields as follows: |
|
|
|
Applications can extend `ProblemDetail` with non-standard fields in one of two ways: |
|
|
|
|
|
|
|
|
|
|
|
- Insert into the "properties" `Map` of `ProblemDetail`. When using the Jackson |
|
|
|
. Add properties to the generic `properties` map in `ProblemDetail`. When using |
|
|
|
library, the Spring Framework registers `ProblemDetailJacksonMixin` that ensures this |
|
|
|
the Jackson library, this `properties` map is unwrapped and as top level JSON |
|
|
|
"properties" `Map` is unwrapped and rendered as top level JSON properties in the |
|
|
|
properties with the help of `ProblemDetailJacksonMixin`. |
|
|
|
response, and likewise any unknown property during deserialization is inserted into |
|
|
|
. Create a `ProblemDetail` subclass that defines the extra, non-standard fields. |
|
|
|
this `Map`. |
|
|
|
Subclasses can use a protected copy constructor in order to re-create an existing |
|
|
|
- Extend `ProblemDetail` to add dedicated non-standard properties. The copy constructor |
|
|
|
`ProblemDetail` as a subclass. This can be done centrally from an `@ControllerAdvice` |
|
|
|
in `ProblemDetail` allows a sub-class to make it easy to be created from an existing |
|
|
|
such as `ResponseEntityExceptionHandler`. |
|
|
|
`ProblemDetail`. This could be done centrally, e.g. from an `@ControllerAdvice` such as |
|
|
|
|
|
|
|
`ResponseEntityExceptionHandler` that re-creates the `ProblemDetail` of an exception into |
|
|
|
On the client side, `WebClientResponseException` and `RestClientResponseException` provide |
|
|
|
a subclass with the additional non-standard fields. |
|
|
|
methods that decode the response body to some target type. This is useful to decode to a |
|
|
|
|
|
|
|
`ProblemDetail`, or to any other class, including subclasses of `ProblemDetail`. |
|
|
|
A client application can catch `WebClientResponseException`, when using the `WebClient`, |
|
|
|
|
|
|
|
or `RestClientResponseException` when using the `RestTemplate`, and use their |
|
|
|
|
|
|
|
`getResponseBodyAs` methods to decode the error response body to any target type such as |
|
|
|
|
|
|
|
`ProblemDetail`, or a subclass of `ProblemDetail`. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
rstoyanchev
2 years ago