错误响应

REST 服务的一个常见要求是在错误响应体中包含详细信息。Spring Framework 支持“HTTP API 的问题详情”规范，https://datatracker.ietf.org/doc/html/rfc9457.html[RFC 9457]。 以下是此支持的主要抽象：

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

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

  • ErrorResponseException — 基本的 ErrorResponse 实现，其他类可以将其用作方便的基类。

  • ResponseEntityExceptionHandler — 用于处理所有 Spring WebFlux 异常和任何 ErrorResponseException，并以包含响应体的形式呈现错误响应的 @ControllerAdvice 的便捷基类。

渲染

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

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

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

  • 对于内容协商，Jackson HttpMessageConverter 在渲染 ProblemDetail 时优先选择 "application/problem+json" 而非 "application/json"，并且在找不到兼容的媒体类型时也会回退到它。

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

您可以通过 WebFlux 配置 和 WebFluxConfigurer 注册 ErrorResponse 拦截器。使用它来拦截任何 RFC 9457 响应并采取一些操作。

非标准字段

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

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

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

定制和国际化

定制和国际化错误响应详情是常见的需求。 定制 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 资源包进行定制。有关更多详细信息，请参阅 自定义验证错误。

客户端处理

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