使用 SpringBoot Validation 对参数进行校验

在开发接口时，如果要对参数进行校验，你会怎么写？编写 if-else 吗？虽然也能达到效果，但是不够优雅。

今天，推荐一种更简洁的写法，使用 SpringBoot Validation 对方法参数进行校验，特别是在编写 Controller 层的方法时，直接使用一个注解即可完成参数校验。

示例代码：

🚀引入依赖

想要完成上述所说的参数校验，我们需要一个核心依赖：spring-boot-starter-validation，此外，为了方便演示，还需要其他依赖。

依赖如下：

<dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <optional>true</optional>
    </dependency>
  </dependencies>

💡 以下部分不是核心内容：

你在编写下面的示例代码中，会发现主要使用到了javax.validation.constraints 包下的注解，而这个包主要来自于 jakarta.validation-api 这个依赖。

如果引入依赖的时候直接引入 jakarta.validation-api 是无法实现参数校验功能的，因为它只定义了规范，而没有具体实现。但是 hibernate-validator 实现了这个规范，直接引入 hibernate-validator 也是可以实现参数校验功能的。

<!--无法完成功能-->
<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
</dependency>
<!--可以完成参数校验功能-->
<!--spring-boot-starter-validation 引入了这个依赖-->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
</dependency>

🚀 相关注解说明

这里罗列出一些主要的注解，这些注解主要来自于包 javax.validation.constraints，有兴趣查看源码的可以去这个包下查看。

可以先跳过这部分内容，下面的代码如果遇到不清楚作用的注解再回来查阅。

✈ 空值检查

注解	说明
`@NotBlank`	用于字符串，字符串不能为`null` 也不能为空字符串
`@NotEmpty`	字符串同上，对于集合（`Map`,`List`,`Set`）不能为空，必须有元素
`@NotNull`	不能为 `null`
`@Null`	必须为 `null`

✈ 数值检查

注解	说明
`@DecimalMax(value)`	被注释的元素必须为数字，其值必须小于等于指定的值
`@DecimalMin(value)`	被注释的元素必须为数字，其值必须大于等于指定的值
`@Digits(integer, fraction)`	被注释的元素必须为数字，其值的整数部分精度为 `integer`，小数部分精度为 `fraction`
`@Positive`	被注释的元素必须为正数
`@PositiveOrZero`	被注释的元素必须为正数或 0
`@Max(value)`	被注释的元素必须小于等于指定的值
`@Min(value)`	被注释的元素必须大于等于指定的值
`@Negative`	被注释的元素必须为负数
`@NegativeOrZero`	被注释的元素必须为负数或 0

✈ Boolean 检查

注解	说明
`@AssertFalse`	被注释的元素必须值为 `false`
`@AssertTrue`	被注释的元素必须值为 `true`

✈ 长度检查

注解	说明
`@Size(min,max)`	被注释的元素长度必须在 `min` 和 `max` 之间，可以是 String、Collection、Map、数组

✈ 日期检查

注解	说明
`@Future`	被注释的元素必须是一个将来的日期
`@FutureOrPresent`	被注释的元素必须是现在或者将来的日期
`@Past`	被注释的元素必须是一个过去的日期
`@PastOrPresent`	被注释的元素必须是现在或者过去的日期

✈ 其他检查

注解	说明
`@Email`	被注释的元素必须是电子邮箱地址
`@Pattern(regexp)`	被注释的元素必须符合正则表达式

除此之外，org.hibernate.validator.constraints 包下还有其他校验注解，例如 @ISBN 检查一个字符串是否是一个有效地 ISBN 序列号。

🚀 参数校验

接下来开始体验 Spring Boot Validation。

首先，编写一个需要校验的实体类：

@Data
public class Student {
    @NotBlank(message = "主键不能为空")
    private String id;
    @NotBlank(message = "名字不能为空")
    @Size(min=2, max = 4, message = "名字字符长度必须为 2~4个")
    private String name;
    @Pattern(regexp = "^1(3\\d|4[5-9]|5[0-35-9]|6[567]|7[0-8]|8\\d|9[0-35-9])\\d{8}$", message = "手机号格式错误")
    private String phone;
    @Email(message = "邮箱格式错误")
    private String email;
    @Past(message = "生日必须早于当前时间")
    private Date birth;
    @Min(value = 0, message = "年龄必须为 0~100")
    @Max(value = 100, message = "年龄必须为 0~100")
    private Integer age;
    @PositiveOrZero
    private Double score;
}

随后编写一个控制层代码，进行测试：

@RestController
public class TestController {

    @GetMapping("/test")
    public Student test(@RequestBody @Validated Student student) {
        return student;
    }
}

使用 postman 进行测试，发送一个不带参数的请求，查看结果：

💡后端控制台日志打印是这样的（显示极度不友好），可以看到校验规则生效了：

2022-11-23 22:10:13.249  WARN 19840 --- [nio-8080-exec-1] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [0] in public com.example.springvalidationdemo.domain.Student com.example.springvalidationdemo.controller.TestController.test(com.example.springvalidationdemo.domain.Student) with 2 errors: [Field error in object 'student' on field 'name': rejected value [null]; codes [NotBlank.student.name,NotBlank.name,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [student.name,name]; arguments []; default message [name]]; default message [名字不能为空]] [Field error in object 'student' on field 'id': rejected value [null]; codes [NotBlank.student.id,NotBlank.id,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [student.id,id]; arguments []; default message [id]]; default message [主键不能为空]] ]

🚀 全局异常处理

查看上面的日志打印，可以看到当参数校验不通过时，会抛出异常 MethodArgumentNotValidException，同时也会打印那些参数没有通过校验，以及该参数校验规则。

为了方便查看，我们可以编写一个全局异常处理，处理这个参数校验异常，并使用统一返回实体返回给前端。

@ControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseBody
    public ResponseEntity<Object> exception(MethodArgumentNotValidException e, HttpServletRequest request) {
        Map<String, String> result = new HashMap<>();
        BindingResult bindingResult = e.getBindingResult();
        log.error("请求[ {} ] {} 的参数校验发生错误", request.getMethod(), request.getRequestURL());
        for (ObjectError objectError : bindingResult.getAllErrors()) {
            FieldError fieldError = (FieldError) objectError;
            log.error("参数 {} = {} 校验错误：{}", fieldError.getField(), fieldError.getRejectedValue(), fieldError.getDefaultMessage());
            result.put(fieldError.getField(), fieldError.getDefaultMessage());
        }
        // 一般项目都会有自己定义的公共返回实体类，这里直接使用现成的 ResponseEntity 进行返回，同时设置 Http 状态码为 400
        return ResponseEntity.badRequest().body(result);

    }

}

再次使用 postman 发起测试：

控制台打印出自定义的日志信息：

2022-11-23 22:16:37.800 ERROR 19880 --- [nio-8080-exec-2] c.e.s.handler.GlobalExceptionHandler     : 请求[ GET ] http://localhost:8080/test 的参数校验发生错误
2022-11-23 22:16:37.800 ERROR 19880 --- [nio-8080-exec-2] c.e.s.handler.GlobalExceptionHandler     : 参数 name = null 校验错误：名字不能为空
2022-11-23 22:16:37.800 ERROR 19880 --- [nio-8080-exec-2] c.e.s.handler.GlobalExceptionHandler     : 参数 id = null 校验错误：主键不能为空
2022-11-23 22:19:36.594 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 请求[ GET ] http://localhost:8080/test 的参数校验发生错误
2022-11-23 22:19:36.594 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 参数 email = abc.com 校验错误：邮箱格式错误
2022-11-23 22:19:36.594 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 参数 score = -20 校验错误：必须是正数或零
2022-11-23 22:19:36.595 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 参数 birth = Thu Jan 01 08:00:00 CST 2099 校验错误：生日必须早于当前时间
2022-11-23 22:19:36.595 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 参数 phone = 12233 校验错误：手机号格式错误
2022-11-23 22:19:36.595 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 参数 age = -40 校验错误：年龄必须为 0~100
2022-11-23 22:19:36.595 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 参数 name = 我是很长的名字 校验错误：名字字符长度必须为 2~4个
2022-11-23 22:19:36.595 ERROR 19880 --- [nio-8080-exec-6] c.e.s.handler.GlobalExceptionHandler     : 参数 score = -20 校验错误：需要在0和9223372036854775807之间

🚀 传递校验

我们也可以使用传递校验，即一个参数类中包含了另一个参数类，被包含的参数类也可以被校验。

在声明一个新的参数类，同时修改 Student 类。

@Data
public class ClassInfo {
    @NotBlank(message = "班主任姓名不能为空")
    private String teacher;
    @NotNull(message = "教师不能为空")
    private Integer classroom;
    @NotNull(message = "年级不能为空")
    @Min(value = 1, message = "年级只能是 1-6")
    @Max(value = 6, message = "年级只能是 1-6")
    private Integer grade;
}

@Data
public class Student {
   //.............
    // 新加的字段，被包含的参数类，使用 @Valid 就能传递校验，如果不使用 @Valid 注解，则无法传递校验。
    @Valid
    private ClassInfo classInfo;
}

再使用 postman 测试一次

🚀 分组校验

此外还可以使用分组校验，令一组方法对某些字段校验，而令一组方法对其他字段校验，例如：一般情况下，新增实体的接口方法 [POST] 不需要主键 ID，修改实体的接口方法 [PUT] 就需要主键 ID 以便进行修改。

为注解 @Validated 赋值属性 value，以及为那些校验注解赋值属性 group，即可达到分组的效果。

接下来看看如何实现分组校验。

在 Student 类中添加两个内部接口 Inteface，同时修改 id 字段的注解，以进行分组

@Data
public class Student {
    // id 字段属于 Create 组
    @NotBlank(message = "主键不能为空", groups = {Student.Create.class})
    private String id;
    // .............
    // 更新分组
    public interface Update {}

    // 创建分组
    public interface Create {}
}

在控制层新增两个接口

@RestController
public class TestController {

    // @Validated 注解可以赋值 value 属性进行分组，value 是可以以数组的形式赋值，既可以分配多个组
    @PostMapping("/students")
    public Student create(@RequestBody @Validated(Student.Create.class) Student student) {
        return student;
    }

    @PutMapping("/students")
    public Student update(@RequestBody @Validated(Student.Update.class) Student student) {
        return student;
    }
}

在 postman 上进行测试：

可以看到分组校验也生效了。

🚀 总结

在实际开发中，我们可以使用 Spring Boot Validation 提供的注解进行参数校验，提高代码的可读性，避免编写大量的 if-else 代码块和重复的校验语句。

Ocean-Tang / spring-validation-demo

使用 SpringBoot Validation 对参数进行校验

🚀引入依赖

🚀 相关注解说明

✈ 空值检查

✈ 数值检查

✈ Boolean 检查

✈ 长度检查

✈ 日期检查

✈ 其他检查

🚀 参数校验

🚀 全局异常处理

🚀 传递校验

🚀 分组校验

🚀 总结

简介

发行版

贡献者

近期动态

Ocean-Tang / spring-validation-demo .gitee-modal { width: 500px !important; }

使用 SpringBoot Validation 对参数进行校验

🚀引入依赖

🚀 相关注解说明

✈ 空值检查

✈ 数值检查

✈ Boolean 检查

✈ 长度检查

✈ 日期检查

✈ 其他检查

🚀 参数校验

🚀 全局异常处理

🚀 传递校验

🚀 分组校验

🚀 总结

简介

发行版

贡献者

近期动态

搜索帮助

Ocean-Tang / spring-validation-demo