【Spring Boot】使用 Hibernate-Validator 优雅校验参数(1)

作者：Albert.Wen 添加时间：2022-07-31 23:27:13 修改时间：2024-12-13 15:06:19 分类：06.Java框架/系统编辑

在接口服务中，会有各种各样的入参，我们不可能完全不做任何校验就直接进入到业务处理的环节，通常会有一个基础的数据验证的机制，待这些验证过程完毕，结果无误后，参数才会进入到正式的业务处理中。

而数据验证又分为两种，一种是无业务关联的规则性验证，一种是根据现有数据进行的联动性数据验证。而 Hibernate-Validator 则适合做无业务关联的规则性验证，而这类验证的代码大多是可复用的。

一、基本使用

1、首先需要导入 maven 依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.1.5.Final</version>
</dependency>

2、添加一个普通的 Get 接口，参数 name 的长度需要在 1~10 之间，参数 age 的最小值为 0。

import org.springframework.validation.annotation.Validated;
import javax.validation.constraints.Min;
import javax.validation.constraints.Size;

@RestController
@Validated
public class UserController {

    @GetMapping("/validate1")
    public String validate1(@Size(min = 1, max = 10, message = "姓名长度必须为1到10") @RequestParam("name") String name,
                            @Min(value = 0, message = "年龄须大于0") @RequestParam("age") Integer age) {
        return "validate1";
    }
}

注意，Get 请求时，类名需要加注解 @Validated 才能对参数进行校验。当校验失败时，会抛出 ConstraintViolationException 异常。

3、添加 Post 接口。首先给 Model 类增加校验注解。

@Data
public class LoginVo {

    @Length(min = 5, max = 17, message = "userName长度须在[5,17]") // 可以为 null，若不为 null，则长度为 [5, 17]
    private String userName;

    // @Size不能验证Integer，适用于String
    @Size(min = 1, max = 3, message = "password长度须在[1,3]")
    private String password;

    @Size(min = 1,max = 5,message = "list的Size在[1,5]") // list 可以为 null，若不为 null，则长度为 [1, 5]
    private List<String> list;

    @NotNull
    @Valid // 级联校验，该注解将会校验自定义类
    private OrderItem detailInfo;
}
@Data
class DetailInfo {

    @NotEmpty(message = "name不能为空")
    private String name;

    @Pattern(regexp="^\\d+$", message = "itemCode需要数字") // 匹配任何数字
    private String itemCode;

    @Range(min = 10, max = 100, message = "range在[10,100]之间")
    private int age;
}

在控制器中增加一个 POST 请求接口。

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

    @GetMapping("/validate1")
    public String validate1(@Size(min = 1, max = 10, message = "姓名长度须为1到10") @RequestParam("name") String name) {
        return "validate1";
    }

    @PostMapping("/validate2")
    public String validate2(@Valid @RequestBody LoginVo loginVo) {
        System.out.println(loginVo);
        return "validate2";
    }
}

发起一个 POST 请求：

POST http://localhost:8080/user/validate2
Content-Type: application/json

{
  "userName": "Tom",
  "password": "1234",
  "list": [1,2,3],
  "detailInfo": {
    "name": "Tom",
    "itemCode": "510000",
    "age": 120
  }
}

服务器返回 400 的状态码。password的尺寸需在[1,3]之间 userName长度需在[5,17]之间 range在[10,100]之间。

二、校验模式

上面例子中一次性返回了所有验证不通过的集合，通常按顺序验证到第一个字段不符合验证要求时，就可以直接拒绝请求了。Hibernate Validator有以下两种验证模式：

普通模式（默认是这个模式）
普通模式时，会校验完所有的属性，然后返回所有的验证失败信息。

快速失败返回模式
快速失败时，只要有一个验证失败，则返回该失败信息。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;

@Configuration
public class ValidatorConfiguration {
    @Bean
    public Validator validator() {
        ValidatorFactory validatorFactory = Validation.byProvider(HibernateValidator.class).configure().failFast(true).buildValidatorFactory();
        return validatorFactory.getValidator();
    }
}

其中 failFast：true 快速失败返回模式；false 普通模式。

三、统一处理 Controller 层异常

当校验失败时，会抛出 MethodArgumentNotValidException 异常，但是我们不应该在 Controller 层处理异常，Controller 层不应该有过多的逻辑处理，异常也不用每个 Controller 都来处理一遍，因此需要全局捕获异常，统一处理。

import org.springframework.http.HttpStatus;
import org.springframework.util.CollectionUtils;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.ResponseStatus;

import javax.validation.ConstraintViolation;
import javax.validation.ConstraintViolationException;
/**
 * 统一异常处理类
 */
@ControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 统一捕获处理ConstraintViolationException异常
     */
    @ExceptionHandler(ConstraintViolationException.class)
    @ResponseBody
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String resolveConstraintViolationException(ConstraintViolationException ex) {
        Set<ConstraintViolation<?>> constraintViolations = ex.getConstraintViolations();
        StringBuilder msgBuilder = new StringBuilder();
        if (!CollectionUtils.isEmpty(constraintViolations)) {
            for (ConstraintViolation constraintViolation : constraintViolations) {
                String msg = constraintViolation.getMessage();
                msgBuilder.append(msg).append(",");
            }
        }
        return msgBuilder.toString();
    }

    /**
     * 统一捕获处理MethodArgumentNotValidException异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseBody
    @ResponseStatus(HttpStatus.OK)
    public String resolveMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
        List<ObjectError> objectErrors = ex.getBindingResult().getAllErrors();
        StringBuilder msgBuilder = new StringBuilder();
        if (!CollectionUtils.isEmpty(objectErrors)) {
            for (ObjectError objectError : objectErrors) {
                String msg = objectError.getDefaultMessage();
                msgBuilder.append(msg).append(" ");
            }
        }
        return msgBuilder.toString();
    }
}

在这里，统一处理了 ConstraintViolationException 和 MethodArgumentNotValidException 这两个异常。

在处理异常时，返回状态码通过 @ResponseStatus 定义。例如抛出 ConstraintViolationException 异常时，前端得到的状态码为 400，而抛出 MethodArgumentNotValidException 异常时，前端的状态码为 200。这都需要根据实际业务情况决定。

此外，方法的返回正也需要根据业务逻辑返回对应的值。

四、自定义校验器参数校验

除了默认提供的校验注解外，我们可以定义自己的校验注解，默认的注解总有不满足要求的时候。

例如需要一个校验性别的注解，要求传递一个只能时 man 或者 female 的字符串。

首先创建约束注解类。

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

@Target({ElementType.FIELD})
@Documented
@Constraint(validatedBy = {GenderValidator.class})
public @interface Gender {
    // 验证失败时显示的信息
    String message() default "gender error";
    // 分组的内容
    Class<?>[] groups() default { };
    // 错误验证的级别
    Class<? extends Payload>[] payload() default {};
}

使用 @interface 定义注解时，意味着它实现了 java.lang.annotation.Annotation 接口，即该注解就是一个Annotation。定义 Annotation 时，@interface 是必须的。

使用 @Documented 修饰该 Annotation，则表示它可以出现在 javadoc 中。定义 Annotation 时，@Documented 可有可无；若没有定义，则 Annotation 不会出现在 javadoc 中。

@Constraint(validatedBy = { GenderValidator.class})用来指定处理这个注解逻辑的类。

@Target 的作用，就是来指定 Annotation 的类型属性。@Target(ElementType.FIELD) 的意思就是指定该 Annotation 的类型是用来修饰“字段（包括枚举常量）”的注解。定义 Annotation 时，@Target 可有可无。若有 @Target，则该 Annotation 只能用于它所指定的地方；若没有 @Target，则该 Annotation 可以用于任何地方。其中，ElementType 可选的类型如下：

TYPE 意味着，它能标注"类、接口（包括注释类型）或枚举声明"。
FIELD 意味着，它能标注"字段声明"。
METHOD 意味着，它能标注"方法"。
PARAMETER 意味着，它能标注"参数"。
CONSTRUCTOR 意味着，它能标注"构造方法"。
LOCAL_VARIABLE 意味着，它能标注"局部变量"。

属性 message 用于显示错误信息，这个字段是必须的，groups 和 payload 也是必须的。

该注解的实现类如下。

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

public class GenderValidator implements ConstraintValidator<Gender, String> {

    private Gender gender;

    @Override
    public void initialize(Gender constraintAnnotation) {
        this.gender = constraintAnnotation;
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        return value.equals("man") || value.equals("female");
    }
}

注意需要实现 ConstraintValidator 接口，泛型的第一个参数是注解类（Gender），第二个参数是注解修饰属性的类型，这里需要修饰的是 String gender;，所以是 String。

使用如下：

@Data
public class LoginVo {

    @Length(min = 5, max = 17, message = "userName长度需在[5,17]之间")
    private String userName;

    @Size(min = 1, max = 3, message = "password的尺寸需在[1,3]之间")
    private String password;

    @Gender
    private String gender;
}

发一个 POST 请求：

POST http://localhost:8090/user/validate2
Content-Type: application/json

{
  "userName": "Tomas",
  "password": "1234",
  "gender": "unknow"
}

由于 gender 的内容不是我们定义的 man 或者 female，不符合校验规则，所以返回了错误信息 gender error 。

摘自：https://www.jianshu.com/p/d4c6effb0735

PHP笔记网

革命尚未成功，同志仍须努力下载JDK17

一、基本使用

二、校验模式

三、统一处理 Controller 层异常

四、自定义校验器参数校验