Spring Boot 优雅式数据校验

----javax.validation

0X01 需求描述

在实际项目开发中，总会需要对于由客户端用户传递过来的数据进行校验工作，如果需要校验的字段比较多，此时可以选择进行统一的异常处理并返回异常信息，如果需要进行精准返回错误信息则需要进行大量的条件判断，那么这样则编码工作是非常痛苦的，而且代码还相当冗长，所以这时我们可以使用Spring的javax.validation注解式参数校验来简化这部分的代码开发，从而写出更优雅式、清晰阅读、便于维护的代码。

0X02 快速实现

下面就简单写个Demo来体验一把使用javax.validation来简化业务开发的快感！

由于SpringBoot2.3.0之后就不在集成Validation组件了，那么此时就需要手动导入Spring Boot Starter Validation。或者可以降低SpringBoot的版本。我这里使用SpringBoot2.6.6。

1.导入相关依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2.编写实体类

package cn.imyjs.pojo;

import lombok.Data;

// 注意以下注解均是由javax.validation提供！
import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;

/**
 * @Classname user
 * @Description TODO
 * @Date 2022/4/22 19:03
 * @Created by YJS
 * @WebSite www.imyjs.cn
 */
@Data  // 此处是lombok提供相关注解，用于简化实体类开发
public class User {

    @NotNull(message = "用户ID不得为空！")
    private Integer id;

    @Size(min = 3, max = 8, message = "用户名长度在3~8个字符！")
    private String username;

    @Size(min = 6, max = 16, message = "用户名长度在6~16个字符！")
    private String password;

    @Min(value = 18, message = "年龄最低限制18！")
    @Max(value = 60, message = "年龄最高限制18！")
    private Integer age;
}

3.编写控制器类

@RestController
@RequestMapping("user")
public class UserController {

    /**
     * 演示GET请求方式的使用
     * @param user
     * @return
     */
    @GetMapping("register")
    public String login( @Valid User user){  // 此处使用@Valid 注解开启校验
        System.out.println(user);
        return "注册成功！";
    }

    /**
     * 演示POST请求方式的使用
     * @param user
     * @param bindingResult
     * @return
     */
    @PostMapping("register")
    public String register(@Valid @RequestBody User user, BindingResult bindingResult){ // 此处使用@Valid 注解开启校验
        List<ObjectError> allErrors = bindingResult.getAllErrors();
        if ( allErrors.size() > 0){
            return allErrors.get(0).getDefaultMessage();
        }
        System.out.println(user);
        return "注册成功！";
    }
}

此时，对于校验非法的数据相关提示信息并不会返回到前端。需要进行如下的处理！

4.编写异常处理类

@RestControllerAdvice
public class GlobalExceptionHandler {
    //处理Get请求中 使用@Valid 验证路径中请求实体校验失败后抛出的异常
    @ExceptionHandler(BindException.class)
    @ResponseBody
    public String BindExceptionHandler(BindException e) {
        String message = e.getBindingResult().getAllErrors().stream().map(DefaultMessageSourceResolvable::getDefaultMessage).collect(Collectors.joining());
        return message;
    }
}

经过测试，此时只能处理GET请求的异常信息，那么对于其他方式请求可以在对应的控制层方法中，进行如下校验：

@PostMapping("register")
    public String register(@Valid @RequestBody User user, BindingResult bindingResult){ // 此处使用@Valid 注解开启校验
        List<ObjectError> allErrors = bindingResult.getAllErrors();
        if ( allErrors.size() > 0){
            return allErrors.get(0).getDefaultMessage();
        }
        System.out.println(user);
        return "注册成功！";
    }

• 在方法参数列表中添加 BindingResult bindingResult
• 然后通过getAllErrors()方法获取可能产生的校验失败信息
• 最后将失败信息返回即可！

0X03 常用注解

0X04 方法级别验证

在能够对传入的实体进行验证之后，希望能够对通过 @RequestParam 或者是 @PathVariable 传入的参数通过注解校验，那就很方便了。Spring对此也进行了扩展，使用方式如下：

1. 增加配置 MethodValidationPostProcessor 参数校验处理器

   package cn.imyjs.config;
   
   import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.validation.beanvalidation.MethodValidationPostProcessor;
   
   /**
    * @Classname MethodValidationPostProcessor
    * @Description TODO
    * @Date 2022/4/22 21:21
    * @Created by YJS
    * @WebSite www.imyjs.cn
    */
   @Configuration
   @EnableAutoConfiguration
   public class MethodValidationConfig {
       @Bean
       public MethodValidationPostProcessor methodValidationPostProcessor() {
           return new MethodValidationPostProcessor();
       }
   }
   

2. 在对应的 controller 或者 service 或者其他想要校验方法参数的类增加 @Validated

   @RestController("hello")
   @Validated
   public class HelloController {
       @RequestMapping("/{username}")
       public String hello(@PathVariable @Size(min = 6, max = 16, message = "用户名长度在6~16位！") String username){
           return "Hello" + username;
       }
   }
   

3. 此时，需要进行重新编写参数异常处理类

   @RestControllerAdvice
   public class GlobalExceptionHandler {
   
       // 处理Get请求中 使用@Valid 验证路径中请求实体校验失败后抛出的异常
       // 用于处理类似http://localhost/user/register?age=10&username=aa请求中age和username的校验引发的异常
       // BindException --- 用于处理请求参数为实体类时校验引发的异常  --- Content-Type为application/x-www-form-urlencoded
       @ExceptionHandler(BindException.class)
       @ResponseBody
       public String BindExceptionHandler(BindException e) {
           String message = e.getBindingResult().getAllErrors().stream().map(DefaultMessageSourceResolvable::getDefaultMessage).collect(Collectors.joining());
           return message;
       }
   
       //处理请求参数格式错误 @RequestParam上validate失败后抛出的异常是javax.validation.ConstraintViolationException
       @ExceptionHandler(ConstraintViolationException.class)
       @ResponseBody
       public String ConstraintViolationExceptionHandler(ConstraintViolationException e) {
           String message = e.getConstraintViolations().stream().map(ConstraintViolation::getMessage).collect(Collectors.joining());
           return message;
       }
   
       //处理请求参数格式错误 @RequestBody上validate失败后抛出的异常是MethodArgumentNotValidException异常。
       // MethodArgumentNotValidException --- 用于处理请求参数为实体类时校验引发的异常 --- Content-Type为application/json
       @ExceptionHandler(MethodArgumentNotValidException.class)
       @ResponseBody
       public String MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {
           String message = e.getBindingResult().getAllErrors().stream().map(DefaultMessageSourceResolvable::getDefaultMessage).collect(Collectors.joining());
           return message;
       }
   
   
       // 可能出现的未知异常
       @ExceptionHandler(value = Exception.class)
       @ResponseBody
       @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
       public String handle(Exception e) {
           return "系统未知异常";
       }
   
   }
   

0X05 @Valid与@Validated

以下内容参考自网络：@Validated和@Valid区别

在检验 Controller 的入参是否符合规范时，使用 @Validated 或者 @Valid 在基本验证功能上没有太多区别。但是在分组、注解地方、嵌套验证等功能上两个有所不同：

1. 分组

@Validated：提供了一个分组功能，可以在入参验证时，根据不同的分组采用不同的验证机制。将不同的校验规则分给不同的组，在使用时，指定不同的校验规则：

• 创建接口类

  /**
   * 校验分组1
   */
  public interface Group1 {
  }
  
  // ------------------------------ //
  
  /**
   * 校验分组2
   */
  public interface Group2 {
  }
  

• 实体类

  @Data
  public class User {
      /**
       * 用户名
       */
      @NotBlank(message = "用户名不能为空！", groups = {Group1.class})
      private String username;
      /**
       * 性别
       */
      @NotBlank(message = "性别不能为空！")
      private String gender;
      /**
       * 年龄
       */
      @Min(value = 1, message = "年龄有误！", groups = {Group1.class})
      @Max(value = 120, message = "年龄有误！", groups = {Group2.class})
      private int age;
      /**
       * 地址
       */
      @NotBlank(message = "地址不能为空！")
      private String address;
      /**
       * 邮箱
       */
      @Email(message = "邮箱有误！", groups = {Group2.class})
      private String email;
      /**
       * 手机号码
       */
      @Pattern(regexp = "^(13[0-9]|14[579]|15[0-3,5-9]|16[6]|17[0135678]|18[0-9]|19[89])\\d{8}$",message = "手机号码有误！", groups = {Group2.class})
      private String mobile;
  }
  

• 控制类

  @RestController
  @RequestMapping("/api")
  public class Demo1Controller {
   
      @PostMapping("/insert1")
      public Result validatedDemo3(@Validated @RequestBody User user){
          return ResultUtil.success(user);
      }
   
      @PostMapping("/insert2")
      public Result validatedDemo4(@Validated(Group1.class) @RequestBody User user){
          return ResultUtil.success(user);
      }
   
      @PostMapping("/insert3")
      public Result validatedDemo5(@Validated(Group2.class) @RequestBody User user){
          return ResultUtil.success(user);
      }
  }
  

@Valid：作为标准JSR-303规范，还没有分组的功能。

2. 注解地方

@Validated：可以用在类、方法和方法参数上。但是不能用在成员属性（字段）上。

@Valid：可以用在方法、构造函数、方法参数和成员属性（字段）上。

两者是否能用于成员属性（字段）上直接影响能否提供嵌套验证的功能。

3. 嵌套验证

在比较两者嵌套验证时，先说明下什么叫做嵌套验证。比如我们现在有个实体叫做Item：

public class Item {

    @NotNull(message = "id不能为空")
    @Min(value = 1, message = "id必须为正整数")
    private Long id;

    @NotNull(message = "props不能为空")
    @Size(min = 1, message = "至少要有一个属性")
    private List<Prop> props;
}

props带有很多属性，属性里面有属性id，属性值id，属性名和属性值，如下所示：

public class Prop {

    @NotNull(message = "pid不能为空")
    @Min(value = 1, message = "pid必须为正整数")
    private Long pid;

    @NotNull(message = "vid不能为空")
    @Min(value = 1, message = "vid必须为正整数")
    private Long vid;

    @NotBlank(message = "pidName不能为空")
    private String pidName;

    @NotBlank(message = "vidName不能为空")
    private String vidName;
}

属性这个实体也有自己的验证机制，比如属性和属性值id不能为空，属性名和属性值不能为空等。

现在我们有个 ItemController 接受一个Item的入参，想要对Item进行验证，如下所示：

@RestController
public class ItemController {

    @RequestMapping("/item/add")
    public void addItem(@Validated Item item, BindingResult bindingResult) {
        doSomething();
    }
}

在以上代码中，如果Item实体的props属性不额外加注释，只有@NotNull和@Size，无论入参采用@Validated还是@Valid验证，Spring Validation框架只会对Item的id和props做非空和数量验证，不会对props字段里的Prop实体进行字段验证，也就是@Validated和@Valid加在方法参数前，都不会自动对参数进行嵌套验证。也就是说如果传的List中有Prop的pid为空或者是负数，入参验证不会检测出来。

为了能够进行嵌套验证，必须手动在Item实体的props字段上明确指出这个字段里面的实体也要进行验证。由于@Validated不能用在成员属性（字段）上，但是@Valid能加在成员属性（字段）上，而且@Valid类注解上也说明了它支持嵌套验证功能，那么我们能够推断出：@Valid加在方法参数时并不能够自动进行嵌套验证，而是用在需要嵌套验证类的相应字段上，来配合方法参数上@Validated或@Valid来进行嵌套验证。

我们修改Item类如下所示：

public class Item {

    @NotNull(message = "id不能为空")
    @Min(value = 1, message = "id必须为正整数")
    private Long id;

    @Valid // 嵌套验证必须用@Valid
    @NotNull(message = "props不能为空")
    @Size(min = 1, message = "props至少要有一个自定义属性")
    private List<Prop> props;
}

4.小结

总体来说@validated 相当于 @Valid 验证的升级版，功能更加强大。

0X06 微信关注

编程那点事儿