错误响应

参见响应式栈中的等效内容

REST服务的常见需求是在错误响应正文中包含详细信息。Spring框架支持“HTTP API 的问题详细信息”规范，RFC 9457。

以下是此支持的主要抽象

  • ProblemDetail——RFC 9457 问题详细信息的表示；一个简单的容器，用于规范中定义的标准字段和非标准字段。

  • ErrorResponse——用于公开 HTTP 错误响应详细信息的契约，包括 HTTP 状态、响应头和 RFC 9457 格式的主体；这允许异常封装和公开它们如何映射到 HTTP 响应的详细信息。所有 Spring MVC 异常都实现了这一点。

  • ErrorResponseException——其他可以作为便捷基类的基本ErrorResponse实现。

  • ResponseEntityExceptionHandler——一个方便的基类，用于处理所有 Spring MVC 异常和任何ErrorResponseException的@ControllerAdvice，并呈现带有正文的错误响应。

渲染

参见响应式栈中的等效内容

您可以从任何@ExceptionHandler或任何@RequestMapping方法返回ProblemDetail或ErrorResponse以渲染 RFC 9457 响应。处理过程如下：

  • ProblemDetail的status属性决定HTTP状态。

  • 如果尚未设置，则ProblemDetail的instance属性将从当前URL路径设置。

  • 对于内容协商，在渲染ProblemDetail时，Jackson HttpMessageConverter更倾向于“application/problem+json”而不是“application/json”，如果找不到兼容的媒体类型，它也会回退到它。

要为 Spring WebFlux 异常和任何ErrorResponseException启用 RFC 9457 响应，请扩展ResponseEntityExceptionHandler并将其声明为 Spring 配置中的@ControllerAdvice。该处理程序具有一个@ExceptionHandler方法，该方法处理任何ErrorResponse异常，其中包括所有内置的 Web 异常。您可以添加更多异常处理方法，并使用受保护的方法将任何异常映射到ProblemDetail。

您可以通过MVC配置和WebMvcConfigurer注册ErrorResponse拦截器。使用它来拦截任何 RFC 9457 响应并采取一些措施。

非标准字段

参见响应式栈中的等效内容

您可以通过两种方式之一扩展 RFC 9457 响应中的非标准字段。

一种是插入ProblemDetail的“properties”Map中。当使用 Jackson 库时，Spring 框架会注册ProblemDetailJacksonMixin，以确保此“properties”Map被解包并以顶级 JSON 属性的形式渲染在响应中，并且同样在反序列化期间任何未知属性都会插入到此Map中。

您还可以扩展ProblemDetail以添加专用的非标准属性。ProblemDetail中的复制构造函数允许子类轻松地从现有ProblemDetail创建。例如，这可以在@ControllerAdvice（例如ResponseEntityExceptionHandler）中集中完成，该@ControllerAdvice将异常的ProblemDetail重新创建为具有附加非标准字段的子类。

定制和国际化

参见响应式栈中的等效内容

定制和国际化错误响应详细信息是一个常见需求。为 Spring MVC 异常定制问题详细信息也是一个好习惯，以避免泄露实现细节。本节介绍对此的支持。

ErrorResponse公开了“type”、“title”和“detail”的消息代码，以及“detail”字段的消息代码参数。ResponseEntityExceptionHandler通过MessageSource解析这些代码，并相应地更新相应的ProblemDetail字段。

消息代码的默认策略如下：

  • "type": problemDetail.type.[完全限定异常类名]

  • "title": problemDetail.title.[完全限定异常类名]

  • "detail": problemDetail.[完全限定异常类名][后缀]

ErrorResponse可以公开多个消息代码，通常在默认消息代码中添加后缀。下表列出了 Spring MVC 异常的消息代码和参数

异常 消息代码 消息代码参数

AsyncRequestTimeoutException

(默认)

ConversionNotSupportedException

(默认)

{0} 属性名，{1} 属性值

HandlerMethodValidationException

(默认)

{0} 列出所有验证错误。每个错误的消息代码和参数也通过MessageSource解析。

HttpMediaTypeNotAcceptableException

(默认)

{0} 支持的媒体类型列表

HttpMediaTypeNotAcceptableException

(默认) + ".parseError"

HttpMediaTypeNotSupportedException

(默认)

{0} 不支持的媒体类型，{1} 支持的媒体类型列表

HttpMediaTypeNotSupportedException

(默认) + ".parseError"

HttpMessageNotReadableException

(默认)

HttpMessageNotWritableException

(默认)

HttpRequestMethodNotSupportedException

(默认)

{0} 当前HTTP方法，{1} 支持的HTTP方法列表

MethodArgumentNotValidException

(默认)

{0} 全局错误列表，{1} 字段错误列表。每个错误的消息代码和参数也通过MessageSource解析。

MissingRequestHeaderException

(默认)

{0} 头部名称

MissingServletRequestParameterException

(默认)

{0} 请求参数名称

MissingMatrixVariableException

(默认)

{0} 矩阵变量名称

MissingPathVariableException

(默认)

{0} 路径变量名称

MissingRequestCookieException

(默认)

{0} Cookie名称

MissingServletRequestPartException

(默认)

{0} 部分名称

NoHandlerFoundException

(默认)

NoResourceFoundException

(默认)

TypeMismatchException

(默认)

{0} 属性名，{1} 属性值

UnsatisfiedServletRequestParameterException

(默认)

{0} 参数条件列表
与其他异常不同，MethodArgumentValidException和HandlerMethodValidationException的消息参数基于一个MessageSourceResolvable错误列表，也可以通过MessageSource资源包进行自定义。更多详情请参见自定义验证错误。

客户端处理

参见响应式栈中的等效内容

使用WebClient时，客户端应用程序可以捕获WebClientResponseException；使用RestTemplate时，可以捕获RestClientResponseException，并使用它们的getResponseBodyAs方法将错误响应体解码为任何目标类型，例如ProblemDetail或ProblemDetail的子类。