Spring Validation 参数校验框架

一.Maven依赖

二.参数校验

常用注解

1.Body参数校验

2.Params参数校验

2.1.Query参数校验

2.2.Path参数校验

三.全局异常处理器捕获校验异常

四.分组校验

1.分组校验

2.案例

2.1.登录

2.2.注册

五.嵌套校验

六.集合校验

七.自定义校验

八.快速失败(Fail Fast)

在日常开发中为了防止非法参数对业务造成影响，不止前端会对参数进行校验，我们后端也要形成一个规范，需要对接口的参数进行校验！

spring boot 通过 Hibernate Validator（Bean Validation 的实现）对数据验证提供了强大的支持。

一.Maven依赖

从 Boot 2.3 开始，需要明确添加 spring-boot-starter-validation 依赖：

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

注：如果spring boot 版本低于2.3，spring-boot-starter-web会自动传入validation依赖。

二.参数校验

大部分情况下，请求参数分为以下两种形式：

Post和Put请求，一般参数携带在请求体中，参数类型为实体参数（Body参数）
Get和Delete请求，参数携带在请求行中，参数类型为简单参数（Query参数）或路径参数（Path参数）

常用注解

@Valid：用于方法参数，表示该参数需要进行数据校验。
@NotNull：用于字段，表示该字段不能为null。
@NotEmpty：用于集合或字符串字段，表示该字段不能为null并且长度/大小必须大于0。
@NotBlank：用于字符串字段，表示该字段不能为null并且去除首尾空格后的长度必须大于0。
@Size(min=, max=)：用于字符串或集合字段，表示该字段的长度/大小必须在指定的范围内。
@Min(value=) 和 @Max(value=)：用于数值字段，表示该字段的值必须在指定的范围内。
@Pattern(regexp=)：用于字符串字段，表示该字段的值必须匹配指定的正则表达式。
@Email：用于字符串字段，表示该字段的值必须是一个有效的电子邮件地址。
@Past 和 @Future：用于日期字段，表示该字段的值必须是一个过去的日期或一个未来的日期。
@Positive 和 @Negative：用于数值字段，表示该字段的值必须是正数或负数。

1.Body参数校验

这种情况下，后端通常使用DTO对象进行接收。只要给DTO对象加上@Validated注解就能实现自动参数校验。

在DTO字段上声明约束注解

@Data
public class TypeDTO {
    private Long typeId; // 类型ID
    @Length(min = 2, max = 16, message = ValidationConstant.TYPE_NAME_LENGTH)
    private String typeName; // 类型名称
    @Length(min = 4, max = 30, message = ValidationConstant.TYPE_DES_LENGTH)
    private String typeDes; // 类型描述
}

在方法参数上声明校验注解

使用@Valid和@Validated都可以

/**
     * 修改类型
     *
     * @return Result
     * CacheEvict
     */
    @Log
    @PutMapping
    @CacheEvict(value = "typeCache", allEntries = true)
    public Result updateType(@RequestBody @Validated TypeDTO typeDTO) {
        log.info("修改类型信息:{}", typeDTO);
        //判断是否存在相同名称的类型
        Type type = typeService.getTypeByName(typeDTO.getTypeName());
        if (type != null && !type.getTypeId().equals(typeDTO.getTypeId())) {
            throw new TypeExitException(MessageConstant.TYPE_NAME_FOUND);
        }
        typeService.updateType(typeDTO);
        return Result.success();
    }

2.Params参数校验

这种情况下，如果参数比较多，推荐使用DTO对象接收。否则，推荐将一个个参数平铺到方法入参中。

在这种情况下，必须在Controller类上标注@Validated注解，并在入参上声明约束注解。

2.1.Query参数校验

在DTO字段上声明约束注解

@Data
public class TypePageDTO {
    private Integer page;
    private Integer pageSize;
    @Length(min = 2, max = 16, message = ValidationConstant.TYPE_NAME_LENGTH)
    private String typeName;
}

在Controller类上标注@Validated注解

@Slf4j
@Validated
@RestController
@RequestMapping("/admin/type")
public class AdminTypeController {
    @Autowired
    private TypeService typeService;


    /**
     * 获取所有类型
     *
     * @return Result
     */
    @GetMapping("/page")
    @Cacheable(value = "typeCache", key = "'typePage：'+#typePageDTO.toString()")
    public Result<PageResult> getAllType(TypePageDTO typePageDTO) {
        log.info("获取所有类型信息:{}", typePageDTO);
        PageResult pageResult = typeService.getAllType(typePageDTO);
        return Result.success(pageResult);
    }

}

2.2.Path参数校验


/**
 * @author <HL>
 *     用户控制器
 */
@Slf4j
@Validated
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService userService;
    @Autowired
    private JwtProperties jwtProperties;
    @Autowired
    private StringRedisTemplate stringRedisTemplate;
    
    /**
     * 用户修改密码
     */
    @PutMapping("/{userPassword}")
    @CacheEvict(value = "userCache", allEntries = true)
    public Result updatePassword(@PathVariable("userPassword")
                                 @Length(min = 4, max = 16,message = ValidationConstant.PASSWORD_LENGTH) String userPassword,
                                 @RequestHeader("token") String token) {
        log.info("用户修改密码:{}", userPassword);
        Long userId = BaseContext.getCurrentId();
        userService.updatePassword(userPassword,userId);
        //删除redis中对应的token
        ValueOperations<String, String> operations = stringRedisTemplate.opsForValue();
        operations.getOperations().delete(token);
        return Result.success();
    }

}

@Valid和@Validated区别：

三.全局异常处理器捕获校验异常

对于Body参数的校验，如果校验失败，会抛出MethodArgumentNotValidException异常。

对于Params参数的校验，如果校验失败，会抛出ConstraintViolationException异常。

package com.hl.server.handler;

import com.hl.common.constant.MessageConstant;
import com.hl.common.exception.BaseException;
import com.hl.common.result.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.util.StringUtils;
import org.springframework.validation.BindException;
import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import javax.validation.ConstraintViolationException;
import java.util.ArrayList;
import java.util.List;

/**
* 全局异常处理器
 * */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {


    /**
     * MethodArgumentNotValidException异常：
     *      当 @Validated 修饰 java 对象时，如 (@RequestBody @Validated LoginDto loginDto)
     *      此时当 javabean 中的属性验证失败时，会抛出所有不符合属性的msg
     *
     * @param ex
     * @return
     */
    @ExceptionHandler({MethodArgumentNotValidException.class})
    public Result handleMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
        BindingResult bindingResult = ex.getBindingResult();
        // 定义返回给前端的内容，只返回给前端最先报错的信息
        String msg = bindingResult.getFieldError().getDefaultMessage();
        log.error("校验失败，错误信息：{}", ex.getMessage());
        return Result.error(msg);
    }
    /**
     * ConstraintViolationException异常：
     *      当 @Validated 修饰单个参数时（此时 @Validated 在类上而不是在方法中），
     *      会抛出ConstraintViolationException异常。
     *
     * @param ex
     * @return
     */
    @ExceptionHandler({ConstraintViolationException.class})
    public Result handleConstraintViolationException(ConstraintViolationException ex) {
        String message = ex.getMessage();
        log.error(message, ex);
        String msg = message.substring(message.indexOf(":") + 1).trim();
        return Result.error( msg);
    }

    /**
     * 处理异常
     * @param e
     * @return
     */
    @ExceptionHandler(BindException.class)
    public Result validationExceptionHandler(BindException e) {
        BindingResult bindingResult = e.getBindingResult();
        List<String> errorList = new ArrayList<>();
        String msg = bindingResult.getFieldError().getDefaultMessage();
        for (FieldError fieldError : bindingResult.getFieldErrors()) {
            errorList.add(fieldError.getDefaultMessage());
        }
        log.debug(String.join(",", errorList));
        return Result.error(msg);
    }

    /**
    *    全局异常
    */
    @ExceptionHandler(Exception.class)
    public Result handleException(Exception e){
        log.error(e.getMessage(), e);
        return Result.error(MessageConstant.UNKNOWN_ERROR);
    }

}

四.分组校验

1.分组校验

在实际项目中，可能多个方法需要使用同一个DTO类来接收参数，而不同方法的校验规则很可能是不一样的。这个时候，简单地在DTO类的字段上加约束注解无法解决这个问题。因此，spring-validation支持了分组校验的功能，专门用来解决这类问题。

如下：

分组后的校验只会对该分组生效

实体类建立分组，使用groups属性进行分组

@Data
public class UserLogAndRegDTO {
    // 用户注册校验组
    public interface UserRegister extends Default {}

    @Length(min = 2, max = 10, message = ValidationConstant.USERNAME_LENGTH,groups = {UserRegister.class})
    private String userName;
    @Pattern(regexp = "^\\d{10}$",message = ValidationConstant.USER_NUMBER_LENGTH)
    private String userNumber;
    @Length(min = 4, max = 16, message = ValidationConstant.PASSWORD_LENGTH)
    private String userPassword;
}

@Validated注解上指定校验分组

/**
     * 登录接口
     * @param userLoginDTO 登录参数
     * @return 登录结果
     */
    @PostMapping("/login")
    public Result<UserLoginVO> login(@RequestBody @Validated UserLogAndRegDTO userLoginDTO) {
        log.info("员工登录：{}", userLoginDTO);
        return Result.success();
    }
    /**
     * 注册接口
     */
    @PostMapping("/register")
    @CacheEvict(value = "userCache", allEntries = true)
    public Result register(@RequestBody @Validated(UserLogAndRegDTO.UserRegister.class) UserLogAndRegDTO userRegisterDTO) {
        log.info("用户注册：{}", userRegisterDTO);
        return Result.success();
    }

2.案例

例如：登录和注册操作，我们使用一个DTO来接收参数

2.1.登录

前端：登录Post请求传入两个参数字段

后端：后端通过校验，可见并未对分组的userName字段进行校验

2.2.注册

前端：注册Post请求传入3个字段

后端：后端通过了注册分组中对userName字段的校验

五.嵌套校验

实际场景中，有可能某个字段是一个对象，这种情况下，可以使用嵌套校验，此时DTO类的对应字段必须标记@Valid注解。

@Data
public class UserDTO {
   
    private Long userId;

    @Length(min = 2, max = 10)
    private String userName;

    @NotNull
    private String userNumber;

    @Length(min = 6, max = 20)
    private String password;

    @NotNull
    @Valid
    private Address address;

    @Data
    public class Address{

        private Long addressId;

        @NotNull
        @Length(min = 2, max = 10)
        private String addressName;

    }

}

嵌套集合校验会对集合里面的每一项都进行校验，例如List<User>字段会对这个list里面的每一个User对象都进行校验。

六.集合校验

如果请求体直接传递了json数组给后台，并希望对数组中的每一项都进行参数校验。此时，如果我们直接使用java.util.Collection下的list或者set来接收数据，参数校验并不会生效！我们可以使用自定义list集合来接收参数：

public class ValidationList<E> implements List<E> {

    @Delegate // @Delegate是lombok注解
    @Valid // 一定要加@Valid注解
    public List<E> list = new ArrayList<>();

    // 一定要记得重写toString方法
    @Override
    public String toString() {
        return list.toString();
    }
}

@PostMapping("/saveList")
public Result saveList(@RequestBody @Validated(UserDTO.Save.class) ValidationList<UserDTO> userList) {
    // 校验通过，才会执行业务逻辑处理
    return Result.ok();
}

七.自定义校验

业务需求总是比框架提供的这些简单校验要复杂的多，已有的注解不能满足所有的校验要求，特殊的情况需要自定义校验（自定义校验注解）

自定义约束注解

@Documented//元注解
//@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER})
/**
*元注解 标明注解可以用在哪里，属性，方法，类....我们这里用到属性上，只需有field即可
*/
@Target({ElementType.FIELD})
//标明我们的注解会在哪个阶段保留，源码，编译，运行，
@Retention(RetentionPolicy.RUNTIME)
//用来指定谁给注解提供校验规则
@Constraint(
        validatedBy = {StateValidation.class}//指定提供校验规则的类
)
public @interface State {//自定义注解
    String message() default "state 参数的值只能是已发布或待审核";//提供校验失败后的提示信息
    //制定分组
    Class<?>[] groups() default {};
    //负载    获取到State注解的附加信息
    Class<? extends Payload>[] payload() default {};
}

自定义规则类实现 ConstraintValidator 接口

/**
 * ConstraintValidator<给那个注解提供校验,校验的数据类型>
 */
public class StateValidation implements ConstraintValidator<State,String> {

    /**
     *
     * @param value 需要校验的数据
     * @param constraintValidatorContext
     * @return true：校验通过  false：校验不通过
     */
    @Override
    public boolean isValid(String value, ConstraintValidatorContext constraintValidatorContext) {
        //提供校验规则
        if(value==null){
            return false;//校验不通过
        }
        if(value.equals("已发布")||value.equals("待审核")){
            return true;
        }
        return false;
    }
}

在需要校验的地方使用自定义注解

八.快速失败(Fail Fast)

Spring Validation默认会校验完所有字段，然后才抛出异常。可以通过一些简单的配置，开启Fali Fast模式，一旦校验失败就立即返回。

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