Spring Validation 参数校验框架使用指北

r囧r小猫 2023-10-03 15:01 21阅读 0赞

#### 文章目录 ####

*  前言
 *  1. 依赖引入
 *  2. 使用指北
 *   *   *  2.1 代码示例
         *  2.2 校验分组
         *  2.3 方法维度校验
         *  2.4 嵌套校验
 *  3. 全局异常处理

## 前言 ##

参数校验是程序开发中必不可少的步骤，任何数据到了后端都需要对其进行合法性检查，以保持程序的健壮性。后端参数校验最简单的做法是直接在业务方法里面进行判断，判断成功之后才继续往下执行。但当多个地方都需要校验时，我们就必须在每一个地方进行校验动作，导致代码很冗余，这时 Spring 框架封装的 Validation 校验组件就可以大显身手

## 1. 依赖引入 ##

`springboot-2.3`之前的版本只需要引入 web 依赖即可，从`springboot-2.3`版本开始校验包被独立成了一个单独组件，所以高版本需要在 `pom.xml` 中添加如下依赖

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

## 2. 使用指北 ##

#### 2.1 代码示例 ####

以下为使用 Spring 参数校验框架进行校验的一个简单示例，大致分为了两个部分，下文将逐个解析

1.  控制器开启校验。这部分代码很简单，需要注意的主要有以下几点：
    
    > 1.  `@Validated` 标注方法入参对象，用于开启参数对象中各个属性的校验
    > 2.  `@Validated` 注解设置 `CheckOnly.class` 属性用于确定校验的分组
    > 3.  类上标注的 `@Validated` 用于开启对方法单个入参对象的校验
    
        @RestController
        @Validated
        public class ValidationController {
              
        
         @Autowired
         private BookService bookService;
        
         @PostMapping(value = "/book")
         public ApiResult save(@RequestBody @UniqueBook @Validated(value ={
              CheckOnly.class}) BookSaveReq req) {
              
             bookService.save(req);
             return ApiResult.success();
         }
        }
2.  Bean 定义校验规则。为 Bean 中各个字段添加校验注解，确定其校验规则。常见的校验注解有 `@NotNull、@NotBlank、@NotEmpty` 等，每个注解的配置属性都基本一致
    
        public class CommonReq {
              
        
         @NotNull(message = "id 参数为空，请检查", groups = Default.class)
         private Long id;
        
        }
    
        public class BookSaveReq extends CommonReq {
              
        
         @NotBlank(message = "名称不能为空", groups = {
              CheckOnly.class, Default.class}
         private String name;
        
        }

#### 2.2 校验分组 ####

校验分组的适用场景是同一个 DTO 的某些属性在特定场景下需要区分校验，比如新增用户和修改用户的 DTO 可以共用一个，但是新增时 DTO 中一般是没有主键 id 的，这就需要使用分组来对字段进行场景区分了。校验的分组定义没有严格的形式，可以直接用接口，如本例中使用的 `CheckOnly` 只是个空接口，默认的分组 `Default` 也是个空接口

public interface CheckOnly {
        
    }

> 在 2.1 节的 Bean 定义中，我们定义了 `BookSaveReq` 中的 name 的校验分组为 `CheckOnly.class` 和 `Default.class`，则当使用 `@Validated(value = {CheckOnly.class})` 标注 `BookSaveReq` 入参对象时，最终开启属性校验只会校验存在指定分组 `CheckOnly.class` 的 Bean 属性

#### 2.3 方法维度校验 ####

当我们需要使用一个入参对象的多个字段来进行业务校验的时候，可以在类上添加 `@Validated` 注解，并结合自定义注解将整个 Bean 对象入参完成业务校验。如本文例子中使用了注解 `@UniqueBook` 在添加书籍时对书籍的唯一性进行校验，该注解的核心是通过 `@Constraint(validatedBy = UniqueBookValidator.class)` 指定了对应的校验器 `UniqueBookValidator`

> Spring 框架实现方法维度参数校验的底层原理其实就是 AOP，具体来说是通过 `MethodValidationPostProcessor` 注册AOP切面，然后使用`MethodValidationInterceptor` 对切点方法进行增强

@Target({
        METHOD, FIELD, CONSTRUCTOR, PARAMETER, TYPE})
    @Retention(RUNTIME)
    @Documented
    @Constraint(validatedBy = UniqueBookValidator.class)
    public @interface UniqueBook {
        
    
        String message() default "该书已存在，请重试";
    
        Class<?>[] groups() default {
        };
    
        Class<? extends Payload>[] payload() default {
        };
    
    }

`UniqueBookValidator` 校验器的实现如下，其实就是使用 `BookSaveReq` 入参对象整体进行业务逻辑校验，非常方便

public class UniqueBookValidator implements ConstraintValidator<UniqueBook, BookSaveReq> {
        
    
        @Resource
        BookService bookService;
    
        @Override
        public boolean isValid(BookSaveReq req, ConstraintValidatorContext context) {
        
            return !bookService.exist(req.getName());
        }
    
    }

#### 2.4 嵌套校验 ####

当要校验的 Bean 对象内部还嵌套了其他需校验的对象时，可以使用 `@Valid` 注解实现嵌套的校验，如下所示

> 注意，在 Spring 中 `@Valid` 和 `@Validated` 可以混用，但是二者特性不同：
> 
>  *  `@Valid`  
>     不支持分组，支持嵌套校验
>  *  `@Validated`  
>     支持分组，不支持嵌套校验，可用于类上开启方法维度入参校验

public class BookSaveReq extends CommonReq {
        
    
        @NotBlank(message = "名称不能为空", groups = {
        CheckOnly.class, Default.class}
        private String name;
        
    	@Valid
    	private Author author;
    
       }

public class Author {
        
    
        @NotBlank(message = "名称不能为空", groups = {
        CheckOnly.class, Default.class}
        private String name;
        
    	 @Min(value = 1, message = "年龄不能小于1")
    	private Integer age;
    
       }

## 3. 全局异常处理 ##

当校验失败抛出异常时，最好要有一个统一的处理方式，以约定的格式将异常信息返回给调用方，这就需要用到全局异常处理。全局异常处理类只需要在类上标注 `@RestControllerAdvice`，并在处理相应异常的方法上使用`@ExceptionHandler`注解写明处理哪个异常即可

@ControllerAdvice
    public class GlobalExceptionHandler {
        
    
        // 处理 form data 形式调用接口校验失败抛出的异常
    	// 处理 GET 方法校验失败抛出的异常
        @ResponseBody
        @ExceptionHandler(BindException.class)
        public ApiResult bindExceptionHandler(BindException e) {
        
            List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors();
            String collect = fieldErrors.stream()
                    .map(DefaultMessageSourceResolvable::getDefaultMessage)
                    .collect(Collectors.joining(";"));
            return ApiResult.fail(400, collect);
        }
    
        // 处理方法单个入参校验失败抛出的异常
        @ResponseBody
        @ExceptionHandler(ConstraintViolationException.class)
        public ApiResult constraintViolationException(ConstraintViolationException e) {
        
            String str = e.getLocalizedMessage();
            if (!StringUtils.isEmpty(str)) {
        
                String[] array = str.split(":");
                int index = 0;
                if (array.length == 2) {
        
                    index = 1;
                }
                str = array[index];
            }
            return ApiResult.fail(400, str);
        }
    
        // WebMVC 处理 json 请求体调用接口校验失败抛出的异常
        @ResponseBody
        @ExceptionHandler(MethodArgumentNotValidException.class)
        public ApiResult methodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {
        
            List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors();
            String collect = fieldErrors.stream()
                    .map(DefaultMessageSourceResolvable::getDefaultMessage)
                    .collect(Collectors.joining(";"));
            return ApiResult.fail(400, collect);
        }
    
    }