错误响应

查看在Servlet堆栈中的等效内容

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

以下是此支持的主要抽象：

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

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

  • ErrorResponseException — 其他人可以使用作为方便基类的基本ErrorResponse实现。

  • ResponseEntityExceptionHandler — 用于处理所有Spring WebFlux异常和任何ErrorResponseException的方便基类，以及呈现带有主体的错误响应的@ControllerAdvice。

渲染

查看在Servlet堆栈中的等效内容

您可以从任何@ExceptionHandler或任何@RequestMapping方法返回ProblemDetail或ErrorResponse以呈现RFC 7807响应。处理如下：

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

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

  • 在内容协商中，当呈现ProblemDetail时，Jackson HttpMessageConverter优先选择“application/problem+json”而不是“application/json”，如果找不到兼容的媒体类型，它也会回退到它。

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

非标准字段

查看在Servlet堆栈中的等效内容

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

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

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

自定义和国际化

在Servlet堆栈中查看等效内容

定制和国际化错误响应细节是一个常见需求。定制Spring WebFlux异常的问题细节也是一个良好的实践，以避免暴露实现细节。本节描述了支持这一点的内容。

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

消息代码的默认策略遵循以下模式：

problemDetail.[type|title|detail].[完全限定的异常类名]

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

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

HandlerMethodValidationException

(默认)

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

MethodNotAllowedException

(默认)

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

MissingRequestValueException

(默认)

{0} 值的标签（例如“请求头”，“cookie值”，...），{1} 值的名称

NotAcceptableStatusException

(默认)

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

NotAcceptableStatusException

(默认) + ".parseError"

ServerErrorException

(默认)

{0} 提供给类构造函数的失败原因

UnsupportedMediaTypeStatusException

(默认)

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

UnsupportedMediaTypeStatusException

(默认) + ".parseError"

UnsatisfiedRequestParameterException

(默认)

{0} 参数条件列表

WebExchangeBindException

(默认)

{0} 全局错误列表，{1} 字段错误列表。每个错误的消息代码和参数也通过MessageSource解析。
与其他异常不同，WebExchangeBindException和HandlerMethodValidationException的消息参数基于MessageSourceResolvable错误列表，这些错误列表也可以通过MessageSource资源包进行定制。有关更多详细信息，请参阅自定义验证错误。

客户端处理

在Servlet堆栈中查看等效内容

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