SpringBoot 开发秘籍 - 整合参数校验

àì夳堔傛蜴生んèń 2022-10-20 13:40 173阅读 0赞

对于`web`服务来说，为防止非法参数对业务造成影响，在`Controller`层一定要对参数进行校验！本章我们以SpringBoot项目为例，介绍参数校验的基本用法以及一些高级技巧，希望能对你有所帮助。

### 简单使用 ###

1.  要在Springboot项目中加入参数校验功能首先得加入`spring-boot-starter-validation`依赖

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

1.  然后给需要校验的字段添加上约束性注解，如我们对实体类参数进行校验

@Data
    public class ValidEntity{ 
        private int id;
        @NotBlank
        private String appId;
        
        @NotBlank
        private String name;
        
        @Email
        private String email;
    }

常见约束注解如下：

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>功能</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@AssertFalse</td> 
   <td>可以为null,如果不为null的话必须为false</td> 
  </tr> 
  <tr> 
   <td>@AssertTrue</td> 
   <td>可以为null,如果不为null的话必须为true</td> 
  </tr> 
  <tr> 
   <td>@DecimalMax</td> 
   <td>设置不能超过最大值</td> 
  </tr> 
  <tr> 
   <td>@DecimalMin</td> 
   <td>设置不能超过最小值</td> 
  </tr> 
  <tr> 
   <td>@Digits</td> 
   <td>设置必须是数字且数字整数的位数和小数的位数必须在指定范围内</td> 
  </tr> 
  <tr> 
   <td>@Future</td> 
   <td>日期必须在当前日期的未来</td> 
  </tr> 
  <tr> 
   <td>@Past</td> 
   <td>日期必须在当前日期的过去</td> 
  </tr> 
  <tr> 
   <td>@Max</td> 
   <td>最大不得超过此最大值</td> 
  </tr> 
  <tr> 
   <td>@Min</td> 
   <td>最大不得小于此最小值</td> 
  </tr> 
  <tr> 
   <td>@NotNull</td> 
   <td>不能为null，可以是空</td> 
  </tr> 
  <tr> 
   <td>@Null</td> 
   <td>必须为null</td> 
  </tr> 
  <tr> 
   <td>@Pattern</td> 
   <td>必须满足指定的正则表达式</td> 
  </tr> 
  <tr> 
   <td>@Size</td> 
   <td>集合、数组、map等的size()值必须在指定范围内</td> 
  </tr> 
  <tr> 
   <td>@Email</td> 
   <td>必须是email格式</td> 
  </tr> 
  <tr> 
   <td>@Length</td> 
   <td>长度必须在指定范围内</td> 
  </tr> 
  <tr> 
   <td>@NotBlank</td> 
   <td>字符串不能为null,字符串trim()后也不能等于“”</td> 
  </tr> 
  <tr> 
   <td>@NotEmpty</td> 
   <td>不能为null，集合、数组、map等size()不能为0；字符串trim()后可以等于“”</td> 
  </tr> 
  <tr> 
   <td>@Range</td> 
   <td>值必须在指定范围内</td> 
  </tr> 
  <tr> 
   <td>@URL</td> 
   <td>必须是一个URL</td> 
  </tr> 
 </tbody> 
</table>

注：此表格只是简单的对注解功能的说明，并没有对每一个注解的属性进行说明；可详见源码。

1.  在Controller层对需要参数校验的方法加上@Validated注解
    
    参数校验一般分为两类：在Controller使用模型接收数据时， @Validated注解直接放在该模型参数前即可。

@PostMapping(value = "test1")
    public String test1(@Validated @RequestBody ValidEntity validEntity){ 
    	return "test1 valid success";
    }
    
    @PostMapping(value = "test3")
    public String test3(@Validated ValidEntity validEntity){ 
    	return "test3 valid success";
    }

当我们是直接在Controller层中的参数前，使用约束注解时，@Validated要直接放在类上

@PostMapping(value = "test2")
    public String test2(@Email String email){ 
        return "test2 valid success";
    }

此时需要在主类上增加@Validated注解

@Validated
    @RestController
    @RequestMapping("/demo/valid")
    public class ValidController {
    	...
    }

> 在参数校验时我们既可以使用@Validated也可以使用@Valid注解，两者功能大部分类似；
> 
> 主要区别在于：
> 
> @Valid属于javax下的，而@Validated属于spring下；
> 
> @Valid支持嵌套校验、而@Validated不支持，@Validated支持分组，而@Valid不支持。

### 统一异常处理 ###

如果参数校验未通过Spring会抛出三种类型的异常

1.  当对@RequestBody需要的参数进行校验时会出现 `org.springframework.web.bind.MethodArgumentNotValidException`

![image-20210514160525143][]

1.  当直接校验具体参数时会出现 `javax.validation.ConstraintViolationException`，也属于`ValidationException`异常

![image-20210514160539021][]

1.  当直接校验对象时会出现 `org.springframework.validation.BindException`

![image-20210514160754907][]

在SpringBoot中统一拦截处理只需要在配置类上添加`@RestControllerAdvice`注解，然后在具体方法中通过`@ExceptionHandler`指定需要处理的异常，具体代码如下：

@RestControllerAdvice
    @Slf4j
    public class GlobalExceptionHandler { 
        public static final String ERROR_MSG = "系统异常，请联系管理员。";
    
        @ExceptionHandler(value = { BindException.class, ValidationException.class, MethodArgumentNotValidException.class})
        public ResponseEntity<Result<String>> handleValidatedException(Exception e) { 
            Result<String> resp = null;
    
            if (e instanceof MethodArgumentNotValidException) { 
                // BeanValidation exception
                MethodArgumentNotValidException ex = (MethodArgumentNotValidException) e;
                resp = new Result<>(Integer.toString(HttpStatus.BAD_REQUEST.value()),
                        ex.getBindingResult().getAllErrors().stream().map(ObjectError::getDefaultMessage).collect(Collectors.joining(", "))
                        , getStackTrace(ex));
            } else if (e instanceof ConstraintViolationException) { 
                // BeanValidation GET simple param
                ConstraintViolationException ex = (ConstraintViolationException) e;
                resp = new Result<>(Integer.toString(HttpStatus.BAD_REQUEST.value()),
                        ex.getConstraintViolations().stream().map(ConstraintViolation::getMessage).collect(Collectors.joining(", "))
                        , getStackTrace(ex));
            } else if (e instanceof BindException) { 
                // BeanValidation GET object param
                BindException ex = (BindException) e;
                resp = new Result<>(Integer.toString(HttpStatus.BAD_REQUEST.value()),
                        ex.getAllErrors().stream().map(ObjectError::getDefaultMessage).collect(Collectors.joining(", "))
                        , getStackTrace(ex));
            }
    
            return new ResponseEntity<>(resp,HttpStatus.BAD_REQUEST);
        }
    
    
        private String getStackTrace(Exception e) { 
            //打印日志开关，可通过配置读取
            boolean printStrackTrace = false;
            if(printStrackTrace){ 
                StringWriter sw = new StringWriter();
                e.printStackTrace(new PrintWriter(sw));
                return sw.toString();
            }else{ 
                return ERROR_MSG;
            }
    
        }
    
    }

最终实现效果如下：

![image-20210517142708200][]

### 参数分组 ###

有下面一个实体类，我们需要对其进行参数校验。

@Data
    public class ValidEntity { 
        private int id;
    
        @NotBlank
        private String appId;
    
        @NotBlank
        private String name;
    
        @Email
        private String email;
    }

但是实际业务是在编辑的时候`appId`才是必填，在新增的时候`name`必填，这时候可以用groups分组功能来实现：同一个模型在不同场景下，动态区分校验模型中的不同字段。

#### 使用方式 ####

1.  首先我们定义一个分组接口ValidGroup，再在分组接口总定义出多个不同的操作类型，Create，Update，Query，Delete

public interface ValidGroup extends Default{ 
        
        interface Crud extends ValidGroup{ 
            
            interface Create extends Crud{ 
    
            }
          
            interface Update extends Crud{ 
    
            }
            
            interface Query extends Crud{ 
    
            }
        
            interface Delete extends Crud{ 
    
            }
        }
    }

这里的`ValidGroup`继承了Default，当然也可以不继承，具体区别我们后面再说。

1.  在模型中给校验参数分配分组

@Data
    @ApiModel(value="ValidEntity")
    public class ValidEntity { 
        private int id;
    
        @NotBlank(groups = ValidGroup.Crud.Update.class)
        private String appId;
    
        @NotBlank(groups = ValidGroup.Crud.Create.class)
        private String name;
    
        @Email
        private String email;
    }

> tips：这里@Email注解未指定分组，默认会属于Default分组，appId和name指定了分组就不会再属于Default分组了。

1.  在参数校验时通过value属性指定分组

![image-20210517113225944][]

这里通过`@Validated(value = ValidGroup.Crud.Update.class)`指定了具体的分组，上面提到的是否继承Default的区别在于：

*  如果继承了Default，@Validated标注的注解也会校验未指定分组或者Default分组的参数，比如email
 *  如果不继承Default则不会校验未指定分组的参数，需要加上`@Validated(value = {ValidGroup.Crud.Update.class, Default.class}`才会校验

### 快速失败（Fali Fast） ###

默认情况下在对参数进行校验时Spring Validation会校验完所有字段然后才抛出异常，可以通过配置开启`Fali Fast`模式，一旦校验失败就立即返回。

@Configuration
    public class ValidatedConfig { 
    
        @Bean
        public Validator validator() { 
            ValidatorFactory validatorFactory = Validation.byProvider(HibernateValidator.class)
                    .configure()
                    // 快速失败模式
                    .failFast(true)
                    .buildValidatorFactory();
            return validatorFactory.getValidator();
        }
    }

朋友们，你们学会了吗？

[image-20210514160525143]: /images/20221020/4cbda86ae5ba47f2a82cfebdec1b281f.png
[image-20210514160539021]: /images/20221020/e0e107f5b2a741c697621263931b2bc3.png
[image-20210514160754907]: /images/20221020/e8f5c1bbe25a4e4cb58ad574ff6c90db.png
[image-20210517142708200]: /images/20221020/01f0ef51d47e49bd83e010d7d92002f2.png
[image-20210517113225944]: /images/20221020/33a6407adcb14c8b880543920dccb543.png