SpringBoot 中使用 @Valid 注解 + Exception 全局处理器优雅处理参数验证

2019-11-20 00:08:15 springboot @Valid springboot @valid

文章目录

相关地址：

Spring Servlet 文档：https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/web/servlet
示例项目 Github：https://github.com/my-dlq/blog-example/tree/master/springboot/springboot-filter-example

系统环境：

Jdk 版本：jdk 8
SpringBoot 版本：2.2.1.RELEASE

一、为什么使用 @Valid 来验证参数

在平常通过 Spring 框架写代码时候，会经常写接口类，相信大家对该类的写法非常熟悉。在写接口时经常要写效验请求参数逻辑，这时候我们会常用做法是写大量的 if 与 if else 类似这样的代码来做判断，如下：

 1@RestController
 2public class TestController {
 3
 4    @PostMapping("/user")
 5    public String addUserInfo(@RequestBody User user) {
 6        if (user.getName() == null || "".equals(user.getName()) {
 7            ......
 8        } else if(user.getSex() == null || "".equals(user.getSex())) {
 9            ......
10        } else if(user.getUsername() == null || "".equals(user.getUsername())) {
11            ......
12        } else {
13            ......
14        }
15        ......
16    }
17    
18}

这样的代码如果按正常代码逻辑来说，是没有什么问题的，不过按优雅来说，简直糟糕透了。不仅不优雅，而且如果存在大量的验证逻辑，这会使代码看起来乱糟糟，大大降低代码可读性，那么有没有更好的方法能够简化这个过程呢？答案当然是有，推荐的是使用 @Valid 注解来帮助我们简化验证逻辑。

二、@Valid 注解的作用

注解 @Valid 的主要作用是用于数据效验，可以在定义的实体中的属性上，添加不同的注解来完成不同的校验规则，而在接口类中的接收数据参数中添加 @valid 注解，这时你的实体将会开启一个校验的功能。

三、@Valid 的相关注解

下面是 @Valid 相关的注解，在实体类中不同的属性上添加不同的注解，就能实现不同数据的效验功能。

注解名称	作用描述
@Null	限制只能为null
@NotNull	限制必须不为null
@AssertFalse	限制必须为false
@AssertTrue	限制必须为true
@DecimalMax(value)	限制必须为一个不大于指定值的数字
@DecimalMin(value)	限制必须为一个不小于指定值的数字
@Digits(integer,fraction)	限制必须为一个小数，且整数部分的位数不能超过integer，小数部分的位数不能超过fraction
@Future	限制必须是一个将来的日期
@Max(value)	限制必须为一个不大于指定值的数字
@Min(value)	限制必须为一个不小于指定值的数字
@Past	限制必须是一个过去的日期
@Pattern(value)	限制必须符合指定的正则表达式
@Size(max,min)	限制字符长度必须在min到max之间
@Past	验证注解的元素值（日期类型）比当前时间早
@NotEmpty	验证注解的元素值不为null且不为空（字符串长度不为0、集合大小不为0）
@NotBlank	验证注解的元素值不为空（不为null、去除首位空格后长度为0），不同于@NotEmpty，@NotBlank只应用于字符串且在比较时会去除字符串的空格
@Email	验证注解的元素值是Email，也可以通过正则表达式和flag指定自定义的email格式

四、使用 @Valid 进行参数效验步骤

整个过程如下图所示，用户访问接口，然后进行参数效验，因为 @Valid 不支持平面的参数效验（直接写在参数中字段的效验）所以基于 GET 请求的参数还是按照原先方式进行效验，而 POST 则可以以实体对象为参数，可以使用 @Valid 方式进行效验。如果效验通过，则进入业务逻辑，否则抛出异常，交由全局异常处理器进行处理。

1、实体类中添加 @Valid 相关注解

使用 @Valid 相关注解非常简单，只需要在参数的实体类中属性上面添加如 @NotBlank、@Max、@Min 等注解来对该字段进限制，如下：

User：

1public class User {
2    @NotBlank(message = "姓名不为空")
3    private String username;
4    @NotBlank(message = "密码不为空")
5    private String password;
6}

如果是嵌套的实体对象，则需要在最外层属性上添加 @Valid 注解：

User：

 1public class User {
 2    @NotBlank(message = "姓名不为空")
 3    private String username;
 4    @NotBlank(message = "密码不为空")
 5    private String password;
 6    //嵌套必须加 @Valid，否则嵌套中的验证不生效
 7    @Valid
 8    @NotNull(message = "用户信息不能为空")
 9    private UserInfo userInfo;
10}

UserInfo：

1public class User {
2    @NotBlank(message = "年龄不为空")
3    @Max(value = 18, message = "不能超过18岁")
4    private String age;
5    @NotBlank(message = "性别不能为空")
6    private String gender;
7}

2、接口类中添加 @Valid 注解

在 Controller 类中添加接口，POST 方法中接收设置了 @Valid 相关注解的实体对象，然后在参数中添加 @Valid 注解来开启效验功能，需要注意的是， @Valid 对 Get 请求中接收的平面参数请求无效，稍微略显遗憾。

1@RestController
2public class TestController {
3
4    @PostMapping("/user")
5    public String addUserInfo(@Valid @RequestBody User user) {
6        return "调用成功!";
7    }
8
9}

3、全局异常处理类中处理 @Valid 抛出的异常

最后，我们写一个全局异常处理类，然后对接口中抛出的异常进行处理，而 @Valid 配合 Spring 会抛出 MethodArgumentNotValidException 异常，这里我们需要对该异常进行处理即可。

 1@RestControllerAdvice("club.mydlq.valid")   //指定异常处理的包名
 2public class GlobalExceptionHandler {
 3
 4    @ResponseStatus(HttpStatus.BAD_REQUEST) //设置状态码为 400
 5    @ExceptionHandler({MethodArgumentNotValidException.class})
 6    public String paramExceptionHandler(MethodArgumentNotValidException e) {
 7        BindingResult exceptions = e.getBindingResult();
 8        // 判断异常中是否有错误信息，如果存在就使用异常中的消息，否则使用默认消息
 9        if (exceptions.hasErrors()) {
10            List<ObjectError> errors = exceptions.getAllErrors();
11            if (!errors.isEmpty()) {
12                // 这里列出了全部错误参数，按正常逻辑，只需要第一条错误即可
13                FieldError fieldError = (FieldError) errors.get(0);
14                return fieldError.getDefaultMessage();
15            }
16        }
17        return "请求参数错误";
18    }
19    
20}

五、SpringBoot 中使用 @Valid 示例

1、Maven 引入相关依赖

Maven 引入 SpringBoot 相关依赖，这里引入了 Lombok 包来简化开发过程。

 1<?xml version="1.0" encoding="UTF-8"?>
 2<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 4	<modelVersion>4.0.0</modelVersion>
 5	<parent>
 6		<groupId>org.springframework.boot</groupId>
 7		<artifactId>spring-boot-starter-parent</artifactId>
 8		<version>2.2.1.RELEASE</version>
 9	</parent>
10	
11	<groupId>mydlq.club</groupId>
12	<artifactId>springboot-valid-demo</artifactId>
13	<version>0.0.1-SNAPSHOT</version>
14	<name>springboot-valid-demo</name>
15	<description>@valid demo</description>
16
17	<properties>
18		<java.version>1.8</java.version>
19	</properties>
20
21	<dependencies>
22		<dependency>
23			<groupId>org.springframework.boot</groupId>
24			<artifactId>spring-boot-starter-web</artifactId>
25		</dependency>
26		<dependency>
27			<groupId>org.projectlombok</groupId>
28			<artifactId>lombok</artifactId>
29			<optional>true</optional>
30		</dependency>
31	</dependencies>
32
33	<build>
34		<plugins>
35			<plugin>
36				<groupId>org.springframework.boot</groupId>
37				<artifactId>spring-boot-maven-plugin</artifactId>
38			</plugin>
39		</plugins>
40	</build>
41
42</project>

注意!：在 SpringBoot 2.3.x 以前 SpringBoot 包默认引入 spring-boot-starter-validation 包，而自 SpringBoot 2.3.x 以后官方将其排除，需要单独引入，所以如果你是用的是 2.3.x 以上版本，请单独引入下面依赖：

1<dependency>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-validation</artifactId>
4</dependency>

2、自定义个异常类

自定义个异常类，方便我们处理 GET 请求（GET 请求参数中一般是没有实体对象的，所以不能使用 @Valid），当请求验证失败时，手动抛出自定义异常，交由全局异常处理。

 1public class ParamaErrorException extends RuntimeException {
 2
 3    public ParamaErrorException() {
 4    }
 5
 6    public ParamaErrorException(String message) {
 7        super(message);
 8    }
 9
10}

3、自定义响应枚举类

定义一个返回信息的枚举类，方便我们快速响应信息，不必每次都写返回消息和响应码。

 1public enum ResultEnum {
 2
 3    SUCCESS(1000, "请求成功"),
 4    PARAMETER_ERROR(1001, "请求参数有误!"),
 5    UNKNOWN_ERROR(9999, "未知的错误!");
 6
 7    private Integer code;
 8    private String message;
 9
10    ResultEnum(Integer code, String message) {
11        this.code = code;
12        this.message = message;
13    }
14
15    public Integer getCode() {
16        return code;
17    }
18
19    public String getMessage() {
20        return message;
21    }
22}

4、自定义响应对象类

创建用于返回调用方的响应信息的实体类。

 1import mydlq.club.parameter.enums.ResultEnum;
 2import lombok.Data;
 3
 4@Data
 5public class ResponseResult {
 6    private Integer code;
 7    private String msg;
 8
 9    public ResponseResult(){
10    }
11
12    public ResponseResult(ResultEnum resultEnum){
13        this.code = resultEnum.getCode();
14        this.msg = resultEnum.getMessage();
15    }
16
17    public ResponseResult(Integer code, String msg) {
18        this.code = code;
19        this.msg = msg;
20    }
21}

5、自定义实体类中添加 @Valid 相关注解

下面将创建用于 POST 方法接收参数的实体对象，里面添加 @Valid 相关验证注解，并在注解中添加出错时的响应消息。

User

 1import lombok.Data;
 2import javax.validation.Valid;
 3import javax.validation.constraints.NotBlank;
 4import javax.validation.constraints.NotNull;
 5
 6/**
 7 * user实体类
 8 */
 9@Data
10public class User {
11    @NotBlank(message = "姓名不为空")
12    private String username;
13    @NotBlank(message = "密码不为空")
14    private String password;
15    // 嵌套必须加 @Valid，否则嵌套中的验证不生效
16    @Valid
17    @NotNull(message = "userinfo不能为空")
18    private UserInfo userInfo;
19}

UserInfo

 1import lombok.Data;
 2import javax.validation.constraints.Max;
 3import javax.validation.constraints.NotBlank;
 4
 5@Data
 6public class UserInfo {
 7    @NotBlank(message = "年龄不为空")
 8    @Max(value = 18, message = "不能超过18岁")
 9    private String age;
10    @NotBlank(message = "性别不能为空")
11    private String gender;
12}

6、Controller 中添加 @Valid 注解

接口类中添加 GET 和 POST 方法的两个接口用于测试，其中 POST 方法以上面创建的 Uer 实体对象接收参数，并使用 @Valid，而 GET 请求一般接收参数较少，所以使用正常判断逻辑进行参数效验。

 1import club.mydlq.valid.entity.ResponseResult;
 2import club.mydlq.valid.entity.User;
 3import club.mydlq.valid.enums.ResultEnum;
 4import club.mydlq.valid.exception.ParamaErrorException;
 5import org.springframework.validation.annotation.Validated;
 6import org.springframework.web.bind.annotation.*;
 7import javax.validation.Valid;
 8
 9@RestController
10public class TestController {
11
12    /**
13     * 获取用户信息
14     *
15     * @param username 姓名
16     * @return ResponseResult
17     */
18    @Validated
19    @GetMapping("/user/{username}")
20    public ResponseResult findUserInfo(@PathVariable String username) {
21        if (username == null || "".equals(username)) {
22            throw new ParamaErrorException("username 不能为空");
23        }
24        return new ResponseResult(ResultEnum.SUCCESS);
25    }
26
27
28    /**
29     * 新增用户
30     *
31     * @param user 用户信息
32     * @return ResponseResult
33     */
34    @PostMapping("/user")
35    public ResponseResult addUserInfo(@Valid @RequestBody User user) {
36        return new ResponseResult(ResultEnum.SUCCESS);
37    }
38
39}

7、全局异常处理

这里创建一个全局异常处理类，方便统一处理异常错误信息。里面添加了不同异常处理的方法，专门用于处理接口中抛出的异常信。

 1import club.mydlq.valid.entity.ResponseResult;
 2import club.mydlq.valid.enums.ResultEnum;
 3import club.mydlq.valid.exception.ParamaErrorException;
 4import lombok.extern.slf4j.Slf4j;
 5import org.springframework.http.HttpStatus;
 6import org.springframework.http.converter.HttpMessageNotReadableException;
 7import org.springframework.util.StringUtils;
 8import org.springframework.validation.BindingResult;
 9import org.springframework.validation.FieldError;
10import org.springframework.validation.ObjectError;
11import org.springframework.web.bind.MethodArgumentNotValidException;
12import org.springframework.web.bind.MissingServletRequestParameterException;
13import org.springframework.web.bind.annotation.ExceptionHandler;
14import org.springframework.web.bind.annotation.ResponseStatus;
15import org.springframework.web.bind.annotation.RestControllerAdvice;
16import java.util.List;
17
18@Slf4j
19@RestControllerAdvice("club.mydlq.valid")
20public class GlobalExceptionHandler {
21
22    /**
23     * 忽略参数异常处理器
24     *
25     * @param e 忽略参数异常
26     * @return ResponseResult
27     */
28    @ResponseStatus(HttpStatus.BAD_REQUEST)
29    @ExceptionHandler(MissingServletRequestParameterException.class)
30    public ResponseResult parameterMissingExceptionHandler(MissingServletRequestParameterException e) {
31        log.error("", e);
32        return new ResponseResult(ResultEnum.PARAMETER_ERROR.getCode(), "请求参数 " + e.getParameterName() + " 不能为空");
33    }
34
35    /**
36     * 缺少请求体异常处理器
37     *
38     * @param e 缺少请求体异常
39     * @return ResponseResult
40     */
41    @ResponseStatus(HttpStatus.BAD_REQUEST)
42    @ExceptionHandler(HttpMessageNotReadableException.class)
43    public ResponseResult parameterBodyMissingExceptionHandler(HttpMessageNotReadableException e) {
44        log.error("", e);
45        return new ResponseResult(ResultEnum.PARAMETER_ERROR.getCode(), "参数体不能为空");
46    }
47
48    /**
49     * 参数效验异常处理器
50     *
51     * @param e 参数验证异常
52     * @return ResponseInfo
53     */
54    @ResponseStatus(HttpStatus.BAD_REQUEST)
55    @ExceptionHandler(MethodArgumentNotValidException.class)
56    public ResponseResult parameterExceptionHandler(MethodArgumentNotValidException e) {
57        log.error("", e);
58        // 获取异常信息
59        BindingResult exceptions = e.getBindingResult();
60        // 判断异常中是否有错误信息，如果存在就使用异常中的消息，否则使用默认消息
61        if (exceptions.hasErrors()) {
62            List<ObjectError> errors = exceptions.getAllErrors();
63            if (!errors.isEmpty()) {
64                // 这里列出了全部错误参数，按正常逻辑，只需要第一条错误即可
65                FieldError fieldError = (FieldError) errors.get(0);
66                return new ResponseResult(ResultEnum.PARAMETER_ERROR.getCode(), fieldError.getDefaultMessage());
67            }
68        }
69        return new ResponseResult(ResultEnum.PARAMETER_ERROR);
70    }
71
72    /**
73     * 自定义参数错误异常处理器
74     *
75     * @param e 自定义参数
76     * @return ResponseInfo
77     */
78    @ResponseStatus(HttpStatus.BAD_REQUEST)
79    @ExceptionHandler({ParamaErrorException.class})
80    public ResponseResult paramExceptionHandler(ParamaErrorException e) {
81        log.error("", e);
82        // 判断异常中是否有错误信息，如果存在就使用异常中的消息，否则使用默认消息
83        if (!StringUtils.isEmpty(e.getMessage())) {
84            return new ResponseResult(ResultEnum.PARAMETER_ERROR.getCode(), e.getMessage());
85        }
86        return new ResponseResult(ResultEnum.PARAMETER_ERROR);
87    }
88
89}

8、启动类

 1import org.springframework.boot.SpringApplication;
 2import org.springframework.boot.autoconfigure.SpringBootApplication;
 3
 4@SpringBootApplication
 5public class Application {
 6
 7	public static void main(String[] args) {
 8		SpringApplication.run(Application.class, args);
 9	}
10
11}

9、示例测试

下面将针对上面示例中设置的两种接口进行测试，分别来验证参数效验功能。

|| - 测试接口 /user/{username}

使用 GET 方法请求地址 http://localhost:8080/user?username=test 时，返回信息：

1{
2    "code": 1000,
3    "msg": "请求成功"
4}

当不输入参数，输入地址 http://localhost:8080/user 时，返回信息：

1{
2    "code": 1001,
3    "msg": "请求参数 username 不能为空"
4}

可以看到在执行 GET 请求，能够正常按我们全局异常处理器中的设置处理异常信息。

|| - 测试接口 /user

(1)、使用 POST 方法发起请求，首先进行不加 JSON 请求体来对 http://localhost:8080/user 地址进行请求，返回信息：

1{
2    "code": 1001,
3    "msg": "参数体不能为空"
4}

(2)、输入部分参数进行测试。

请求内容：

1{
2 "username":"test",
3 "password":"123"
4}

返回信息：

1{
2    "code": 1001,
3    "msg": "userinfo不能为空"
4}

(3)、输入完整参数，且设置 age > 18 时，进行测试。

1{
2 "username":"111",
3 "password":"sa",
4  "userInfo":{
5  	"age":19,
6  	"gender":"男"
7  }
8}

返回信息：

1{
2    "code": 1001,
3    "msg": "不能超过18岁"
4}

可以看到在执行 POST 请求，也能正常按我们全局异常处理器中的设置处理异常信息，且提示信息为我们设置在实体类中的 Message。

---END---