|
对于最新的稳定版本，请使用 Spring Framework 7.0.6! |
错误响应
REST服务的常见需求是在错误响应体中包含详情。Spring框架支持"HTTP API问题详情"规范RFC 7807。
以下是该支持的主要抽象概念：
-
ProblemDetail—表示RFC 7807问题详情；一个简单容器，用于规范中定义的标准字段以及非标准字段。 -
ErrorResponse— 用于公开HTTP错误响应详情的契约，包括HTTP状态码、响应头以及符合RFC 7807格式的消息体；该机制允许异常封装并公开其如何映射到HTTP响应的细节。所有Spring MVC异常均实现此接口。 -
ErrorResponseException— 基础ErrorResponse实现，其他人可用作便捷基类。 -
ResponseEntityExceptionHandler——处理所有Spring MVC异常和任何ErrorResponseException的 @ControllerAdvice便捷基类，并渲染包含正文的错误响应。
渲染
您可以从任意 @ExceptionHandler 或从
任意 @RequestMapping 方法中返回 ProblemDetail 或 ErrorResponse 来生成一个 RFC 7807 响应。具体处理步骤如下：
-
ProblemDetail的status属性决定了 HTTP 状态。 -
如果尚未设置，
ProblemDetail的instance属性将从当前 URL 路径设置。 -
在内容协商方面，Jackson
HttpMessageConverter在渲染ProblemDetail时优先选择"application/problem+json"而非"application/json"，并且在找不到兼容的媒体类型时也会回退到该格式。
要为Spring WebFlux异常及任何ErrorResponseException启用RFC 7807响应，需继承ResponseEntityExceptionHandler并在Spring配置中将其声明为
@ControllerAdvice。该处理器包含一个处理所有ErrorResponse异常的@ExceptionHandler方法（涵盖所有内置Web异常）。您可添加更多异常处理方法，并通过受保护的方法将任何异常映射至ProblemDetail。
非标准字段
您可以通过两种方式之一扩展带有非标准字段的 RFC 7807 响应。
一、将数据插入到ProblemDetail的"properties"Map中。使用Jackson库时，Spring框架会注册ProblemDetailJacksonMixin，
确保该"properties"Map被展开并作为顶级JSON属性呈现在响应中，
同样地，在反序列化过程中任何未知属性也会被插入到此Map中。
您还可以扩展ProblemDetail来添加专用的非标准属性。
ProblemDetail中的拷贝构造函数允许子类轻松地从现有的ProblemDetail创建。
这可以通过集中式方式实现，例如通过像ResponseEntityExceptionHandler这样的@ControllerAdvice，
将异常的ProblemDetail重新创建为包含额外非标准字段的子类。
国际化
国际化错误响应细节是一项常见需求，为Spring MVC异常定制问题细节也是一种良好实践。其支持方式如下所示：
-
每个
ErrorResponse会暴露一个消息代码和参数，用于通过MessageSource解析"detail"字段。 实际的消息代码值采用参数化占位符，例如"HTTP method {0} not supported"会从参数中扩展。 -
每个
ErrorResponse还会公开一个消息代码用于解析 "title" 字段。 -
ResponseEntityExceptionHandler使用消息码和参数来解析 "detail" 和 "title" 字段。
默认情况下，“detail”字段的消息代码为“problemDetail.”加上完全限定的异常类名。某些异常可能暴露额外的消息代码，此时会在默认消息代码后添加后缀。下表列出了Spring MVC异常的消息参数与代码：
| 异常 | 消息代码 | 消息代码参数值 |
|---|---|---|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
(default) + ".parseError" |
|
|
默认 |
|
|
(default) + ".parseError" |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
|
默认 |
|
默认情况下，"title"字段的消息代码对应"problemDetail.title."加异常类的完全限定名。
客户端处理
客户端应用在使用 WebClient 时可以捕获 WebClientResponseException，或在使用 RestTemplate 时捕获 RestClientResponseException，并通过其
getResponseBodyAs 方法将错误响应体解码为任意目标类型，例如
ProblemDetail 或 ProblemDetail 的子类。