Spring Boot 参数校验与异常处理

╰半夏微凉° 2024-03-26 02:21 61阅读 0赞

## 0. 从 Web 的参数接收说起 ##

我们常用来获取 Web 参数的注解有以下三个：

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@RequestParam</td> 
   <td>获取 URL "?" 后所携带的参数，如：localhost:8080/user?id=1</td> 
  </tr> 
  <tr> 
   <td>@PathVariable</td> 
   <td>主要配合 RESTful 风格使用，可以获取 URL 路径上所包含的参数，如：localhost:8080/user/{id}</td> 
  </tr> 
  <tr> 
   <td>@RequestBody</td> 
   <td>用于接收请求体中的参数，常用于 <code>application/json</code> 类型的 <code>POST</code> 请求</td> 
  </tr> 
 </tbody> 
</table>

本文分别以这三个注解为出发点，以参数校验、异常处理为主线，将一些相关的琐碎知识点串联起来。

## 1. 从 @RequestParam 出发 ##

### 1.1 required 校验非 null 引发的异常 ###

`@RequestParam` 注解提供 `required` 属性来设置参数是否必需，默认值 `true` ，即无需特别注明 `required` 属性，在请求参数缺失时，就会抛出异常。

@GetMapping(value = "user", produces = MediaType.APPLICATION_JSON_VALUE)
    public Map<String, Object> getUserInfo(@RequestParam String id) {
        // doSomething()
    }

我们用 Postman 来测试上述代码，当不传递参数 id 时，将得到如下响应信息，状态码为 400 ：

![format_png][]

在服务日志中，我们可以看到异常的提示信息：

![format_png 1][]

### 1.2 异常提示信息 message 哪里去了？ ###

部分小伙伴儿会遇到跟我相同的问题，异常的提示信息仅能在服务日志中看到，并没有包含在响应体中，那么 `message` 哪里去了？

这是由于 Spring Boot 版本造成的，查阅了 Spring Boot 的 [版本日志][Link 1] ，`2.5.x` 起，默认的异常响应信息中的 `message` 属性被移除了：

![format_png 2][]

如果仍然希望异常响应时显示详细的提示信息，则需要增加如下配置：

server: 
      error: 
        include-message: always

有了上述配置，`message` 就回来了：

![format_png 3][]

### 1.3 `server.error.include-` 还有其它配置么？ ###

既然我们可以通过配置在异常响应体中增加 `message` ，那么还有什么其他可配置的信息么？

基于 `Spring Boot 2.7.8` ，将异常响应信息做如下梳理：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>属性说明</th> 
   <th>固定 / 可配置</th> 
   <th>配置项及默认值</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>timestamp</td> 
   <td>异常发生时的时间</td> 
   <td>固定</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>status</td> 
   <td>http 响应状态码</td> 
   <td>固定</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>error</td> 
   <td>与状态码对应的异常原因</td> 
   <td>固定</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>path</td> 
   <td>异常发生时的请求路径</td> 
   <td>固定</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>message</td> 
   <td>异常的提示信息</td> 
   <td>可配置</td> 
   <td><code>server.error.include-message = never</code></td> 
  </tr> 
  <tr> 
   <td>exception</td> 
   <td>异常的类名</td> 
   <td>可配置</td> 
   <td><code>server.error.include-exception = false</code></td> 
  </tr> 
  <tr> 
   <td>trace</td> 
   <td>异常跟踪堆栈信息</td> 
   <td>可配置</td> 
   <td><code>server.error.include-stacktrace = never</code></td> 
  </tr> 
  <tr> 
   <td>errors</td> 
   <td><code>BindingResult</code> 中的错误信息</td> 
   <td>可配置</td> 
   <td><code>server.error.include-binding-errors = never</code></td> 
  </tr> 
 </tbody> 
</table>

除了 `server.error.include-exception` 是布尔值外，其它三项配置可选值如下：

<table> 
 <thead> 
  <tr> 
   <th>可选值</th> 
   <th>配置说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>never</td> 
   <td>异常响应体中不会包含对应的信息</td> 
  </tr> 
  <tr> 
   <td>always</td> 
   <td>异常响应体中包含对应的信息</td> 
  </tr> 
  <tr> 
   <td>on-param</td> 
   <td>当请求参数中包含相应的参数名（<code>message</code>、<code>trace</code>、<code>errors</code>），且参数值不为 <code>false</code> 时，异常响应体中将包含对应的信息</td> 
  </tr> 
 </tbody> 
</table>

`on-param` 的效果如下图：

![format_png 4][]

> **更多的细节与说明，可阅读相关源码：**  
> \[spring-boot-x.x.x.jar\] org.springframework.boot.web.servlet.error.DefaultErrorAttributes  
> \[spring-boot-x.x.x.jar\] org.springframework.boot.web.error.ErrorAttributeOptions  
> \[spring-boot-autoconfigure-x.x.x.jar\] org.springframework.boot.autoconfigure.web.ErrorProperties

### 1.4 如何在异常响应体中添加自定义信息？ ###

如何在上述 8 个属性的基础上，扩展自定义的信息呢？

*  创建一个类，继承 `org.springframework.boot.web.servlet.error.DefaultErrorAttributes` （此处需要特别注意基类的路径，容易错误引用为 `org.springframework.boot.web.reactive.error.DefaultErrorAttributes` ）；
 *  通过 `@Component` 注解将类交托于 Spring 管理；
 *  重写 `getErrorAttributes` 方法，调用基类同名方法，在获取的 `Map` 结果集中进行自定义信息的扩展。

[format_png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/0f1f3fd002f64be1a92738c74a4e4479.png
[format_png 1]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/ed830c36e57f4d81a5e75c73e92ebc75.png
[Link 1]: https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fspring-projects%2Fspring-boot%2Fwiki%2FSpring-Boot-2.5-Release-Notes
[format_png 2]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/8b0c6b1973c347a5b5742e3edeb9691f.png
[format_png 3]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/785e4ce58d064bfe8b882f6ebd25cdb0.png
[format_png 4]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/26/7f79a2b220e74722b3820497a61e64d5.png