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

错误响应

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

REST服务的常见需求是在错误响应体中包含详情。Spring框架支持"HTTP API问题详情"规范RFC 7807。spring-doc.cadn.net.cn

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

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

  • ErrorResponse — 约定暴露HTTP错误响应细节，包括HTTP状态码、响应头和符合RFC 7807格式的响应体；从而使异常能够封装并暴露其映射到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 7807 响应。具体处理步骤如下：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 7807响应，需继承ResponseEntityExceptionHandler并在Spring配置中将其声明为 @ControllerAdvice。该处理器包含一个处理所有ErrorResponse异常的@ExceptionHandler方法（涵盖所有内置Web异常）。您可添加更多异常处理方法，并通过受保护的方法将任何异常映射至ProblemDetail。spring-doc.cadn.net.cn

非标准字段

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

您可以通过两种方式之一扩展带有非标准字段的 RFC 7807 响应。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会暴露一个消息代码和参数，用于通过MessageSource解析"detail"字段。 实际的消息代码值采用参数化占位符，例如"HTTP method {0} not supported"会从参数中扩展。spring-doc.cadn.net.cn

  • 每个 ErrorResponse 还会公开一个消息代码用于解析 "title" 字段。spring-doc.cadn.net.cn

  • ResponseEntityExceptionHandler 使用消息码和参数来解析 "detail" 和 "title" 字段。spring-doc.cadn.net.cn

默认情况下，"detail"字段的消息代码为"problemDetail."加上异常的完全限定类名。某些异常可能会提供额外的消息代码，此时将在默认消息代码后追加后缀。下表列出了Spring WebFlux异常的消息参数与代码：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

MissingRequestValueExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

{0} 值的标签（例如“请求头”、“Cookie值”、…​），{1} 值名称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机制解析BindingResult中的每个错误的消息代码和参数。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

MethodNotAllowedExceptionspring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

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

默认情况下，"title"字段的消息代码对应"problemDetail.title."加异常类的完全限定名。spring-doc.cadn.net.cn

客户端处理

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

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