对于最新的稳定版本，请使用 Spring Framework 7.0.6!spring-doc.cadn.net.cn

错误响应

请参阅Servlet栈中的等效实现spring-doc.cadn.net.cn

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

以下是该支持的主要抽象概念：spring-doc.cadn.net.cn

  • ProblemDetail — RFC 9457 问题详情的表示；一个用于容纳规范中定义的标准字段以及非标准字段的简单容器。spring-doc.cadn.net.cn

  • ErrorResponse — 约定用于暴露HTTP错误响应的详细信息，包括HTTP状态、响应头以及符合RFC 9457格式的响应体；这使得异常能够封装并暴露其映射到HTTP响应的细节。所有Spring WebFlux异常都实现了此约定。spring-doc.cadn.net.cn

  • ErrorResponseException — 基础 ErrorResponse 实现，其他人可用作便捷基类。spring-doc.cadn.net.cn

  • ResponseEntityExceptionHandler——一个便捷的基类，用于处理所有Spring WebFlux异常、 任何ErrorResponseException异常，并通过响应体渲染错误结果的 @ControllerAdvice。spring-doc.cadn.net.cn

渲染

请参阅Servlet栈中的等效实现spring-doc.cadn.net.cn

您可以从任意 @ExceptionHandler 或任意 @RequestMapping 方法返回 ProblemDetail 或 ErrorResponse，以生成 RFC 9457 响应。其处理方式如下：spring-doc.cadn.net.cn

  • ProblemDetail 的 status 属性决定了 HTTP 状态。spring-doc.cadn.net.cn

  • 如果尚未设置，ProblemDetail 的 instance 属性将从当前 URL 路径设置。spring-doc.cadn.net.cn

  • 在内容协商方面，Jackson HttpMessageConverter在渲染ProblemDetail时优先选择"application/problem+json"而非"application/json"，并且在找不到兼容的媒体类型时也会回退到该格式。spring-doc.cadn.net.cn

要为 Spring WebFlux 异常以及任何 ErrorResponseException 启用 RFC 9457 响应，请继承 ResponseEntityExceptionHandler 并在 Spring 配置中将其声明为 @ControllerAdvice。该处理器包含一个 @ExceptionHandler 方法，用于处理任何 ErrorResponse 异常，其中包括所有内置的 Web 异常。您可以添加更多的异常处理方法，并使用受保护的方法将任何异常映射到 ProblemDetail。spring-doc.cadn.net.cn

非标准字段

请参阅Servlet栈中的等效实现spring-doc.cadn.net.cn

你可以通过以下两种方式之一，使用非标准字段扩展 RFC 9457 响应。spring-doc.cadn.net.cn

一、将数据插入到ProblemDetail的"properties"Map中。使用Jackson库时，Spring框架会注册ProblemDetailJacksonMixin， 确保该"properties"Map被展开并作为顶级JSON属性呈现在响应中， 同样地，在反序列化过程中任何未知属性也会被插入到此Map中。spring-doc.cadn.net.cn

您还可以扩展ProblemDetail来添加专用的非标准属性。 ProblemDetail中的拷贝构造函数允许子类轻松地从现有的ProblemDetail创建。 这可以通过集中式方式实现，例如通过像ResponseEntityExceptionHandler这样的@ControllerAdvice， 将异常的ProblemDetail重新创建为包含额外非标准字段的子类。spring-doc.cadn.net.cn

自定义和国际化

请参阅Servlet栈中的等效实现spring-doc.cadn.net.cn

自定义和国际化错误响应详情是一个常见的需求。 同样，为 Spring WebFlux 异常自定义问题详情也是一种良好的实践， 可避免暴露实现细节。本节介绍对此的支持。spring-doc.cadn.net.cn

一个ErrorResponse暴露了用于"type"、"title"和"detail"的消息代码，以及为"detail"字段的消息代码参数。ResponseEntityExceptionHandler通过MessageSource 解析这些，并相应地更新对应的ProblemDetail字段。spring-doc.cadn.net.cn

默认的消息代码策略遵循以下模式：spring-doc.cadn.net.cn

problemDetail.[type|title|detail].[fully qualified exception class name]spring-doc.cadn.net.cn

一个 ErrorResponse 可能会暴露多个消息代码，通常是在默认消息代码后添加一个后缀。 下表列出了 Spring WebFlux 异常的消息代码及其参数：spring-doc.cadn.net.cn

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

HandlerMethodValidationExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 列出所有验证错误。 每个错误的消息代码和参数也通过 MessageSource 进行解析。spring-doc.cadn.net.cn

MethodNotAllowedExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 当前HTTP方法, {1} 支持的HTTP方法列表spring-doc.cadn.net.cn

MissingRequestValueExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 值的标签（例如“请求头”、“Cookie值”、…​），{1} 值名称spring-doc.cadn.net.cn

NotAcceptableStatusExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 支持的媒体类型列表spring-doc.cadn.net.cn

NotAcceptableStatusExceptionspring-doc.cadn.net.cn

(default) + ".parseError"spring-doc.cadn.net.cn

ServerErrorExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 提供给类构造函数的失败原因spring-doc.cadn.net.cn

UnsupportedMediaTypeStatusExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 不支持的媒体类型，{1} 支持的媒体类型列表spring-doc.cadn.net.cn

UnsupportedMediaTypeStatusExceptionspring-doc.cadn.net.cn

(default) + ".parseError"spring-doc.cadn.net.cn

UnsatisfiedRequestParameterExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 参数条件列表spring-doc.cadn.net.cn

WebExchangeBindExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 全局错误列表，{1} 字段错误列表。 每个错误的消息代码和参数也通过 MessageSource 进行解析。spring-doc.cadn.net.cn
与其他异常不同，WebExchangeBindException 和 HandlerMethodValidationException 的消息参数基于一个 MessageSourceResolvable 错误列表，该列表也可以通过 MessageSource 资源包进行自定义。更多详细信息，请参见 自定义验证错误。

客户端处理

请参阅Servlet栈中的等效实现spring-doc.cadn.net.cn

客户端应用在使用 WebClient 时可以捕获 WebClientResponseException，或在使用 RestTemplate 时捕获 RestClientResponseException，并通过其 getResponseBodyAs 方法将错误响应体解码为任意目标类型，例如 ProblemDetail 或 ProblemDetail 的子类。spring-doc.cadn.net.cn