@Valid 注解详解 Java Bean Validation的前世今生

1 @Valid 介绍

1.1 前言

在我们日常开发中，数据校验的实现是一件比较痛苦的事情，繁琐且无趣，对于一般的业务而言，极少出现一些过于复杂的校验，常常都是非空，长度，最大最小值，正则，数据关联，定值等等。我在开发过程中为了减少我写这些代码的coding成本，由此认识了javax.validation包下的 @Valid 注解 和 Java 的 Bean Validation 规范。

1.2 Bean Validation

首先了解下JSR（Java Specification Requests）

JSR：Java Specification Requests的缩写，意思是Java 规范提案。是指向JCP(Java Community Process)提出新增一个标准化技术规范的正式请求。任何人都可以提交JSR，以向Java平台增添新的API和服务。JSR已成为Java界的一个重要标准。

Bean Validation 是一个运行时的数据验证框架，在验证之后验证的错误信息会被马上返回。

Java 在2009年的 JAVAEE 6 中发布了 JSR303以及javax下的validation包内容。

这项工作的主要目标是为java应用程序开发人员提供 基于java对象的 约束（constraints）声明 和 对约束的验证工具（validator），以及约束元数据存储库和查询API。
但是该内容并没有具体的实现， Hibernate-Validator框架 提供了 JSR 303 规范中所有内置 constraint 的实现，除此之外还有一些附加的 constraint。

注意：此处的Hibernate 不是 Hibernate ORM

后续关于Bean Validation 的规范提案 和 各个版本的实现 陆续得以迭代，各个版本的信息如下：

Bean Validation Version	release year	JSR Version	Hibernate impl version	apache BVal impl version
Bean Validation 1.0	2009年	JSR 303	Hibernate-Validator-4.3.1.Final	org.apache.bval 0.5
Bean Validation 1.1	2013年	JSR 349	Hibernate-Validator-5.1.1.Final	org.apache.bval 1.1.2
Bean Validation 2.0	2017年	JSR 380	Hibernate-Validator-6.0.1.Final	org.apache.bval 2.0.3(最新版本)

本文主要基于 Hibernate-Validator 框架的实现为主。

1.3 关于validation包

Java-Api文档
其中 javax.validation.constraints包下是 bean validation 支持的约束，以注解的形式使用。

1.3 关于Spring Hibernate Validator支持的约束集信息（constraints）

截取自 IBM JSR 303

表 1. Bean Validation 中内置的 constraint

表 2. Hibernate Validator 附加的 constraint

2 简单的使用

2.1配置项

2.1.1 maven – jar包引入

如果使用springMVC ，需要在 pom文件中引入对应的jar包。

<!--        hibernate.validator jar包-->
        <dependency>
            <groupId>org.hibernate.validator</groupId>
            <artifactId>hibernate-validator</artifactId>
            <version>6.0.17.Final</version>
        </dependency>

这里不需要引入 javax.validation包，hibernate-validator框架中已经有引入了。

如果使用springboot，笔者使用的 2.1.7.RELEASE 版本，其中 spring-boot-starter-web 包中已经引入了 hibernate-validator 6.0.17.RELEASE了，不需要我们手动添加。

如果使用的非maven项目，需要下载对应的jar引入到项目中。

2.1.2 SpringMVC配置

<!--配置中需要注意的地方：
LocalValidatorFactoryBean ：
validationMessageSource通过set方法注入,然后转换为MessageInterpolator对象，如果不配置validationMessageSource信息源，那么会使用默认的信息源HibernateValidations_xx_xx.properties,位于org.hibernate.validator包下，具体使用哪个文件由Locale.getDefaultLocale()决定。-->
<bean id="validator" class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean">
         <property name="providerClass" value="org.hibernate.validator.HibernateValidator" />
         <property name="validationMessageSource" ref="hibernate_validator_messages"/>
</bean>

2.2 实现方式

这部分介绍关心实现的小伙伴也可以略过，直接看实现。

2.2.1 @Valid + BindingResult + javax.validation.constraints.*

BindingResult 是 spring 对于 Hibernate-Validator的进一步封装，主要处理 约束违反信息 的处理。也就是当 判断 校验不通过时 所获取的 默认的或者自定义的 错误信息。
使用 @Valid 结合 BindingResult实例，Spring将对被注解的实体进行约束校验，原理是AOP。

2.2.2 validator.validate()

springboot 自动将 ValidatorFactory 加载到了IOC容器中，不需要进行配置（注意：SpringMVC 需要进行配置）。我们可以使用自动注入的方式获取 ValidatorFactory接口的实现的实例，进而获取 Validator接口的实现的实例，调用.validate(T var1, Class<?>… var2)方法对 java bean 进行约束检验。基于此，还可以用作AOP切面的开发。
validator接口源码

package javax.validation;

import java.util.Set;
import javax.validation.executable.ExecutableValidator;
import javax.validation.metadata.BeanDescriptor;

public interface Validator {
    <T> Set<ConstraintViolation<T>> validate(T var1, Class<?>... var2);

    <T> Set<ConstraintViolation<T>> validateProperty(T var1, String var2, Class<?>... var3);

    <T> Set<ConstraintViolation<T>> validateValue(Class<T> var1, String var2, Object var3, Class<?>... var4);

    BeanDescriptor getConstraintsForClass(Class<?> var1);

    <T> T unwrap(Class<T> var1);

    ExecutableValidator forExecutables();
}

ValidatorFactory 工厂接口源码

package javax.validation;

public interface ValidatorFactory extends AutoCloseable {
    Validator getValidator();

    ValidatorContext usingContext();

    MessageInterpolator getMessageInterpolator();

    TraversableResolver getTraversableResolver();

    ConstraintValidatorFactory getConstraintValidatorFactory();

    ParameterNameProvider getParameterNameProvider();

    ClockProvider getClockProvider();

    <T> T unwrap(Class<T> var1);

    void close();
}

2.2.3 代码示例

下面我们用一个简单的示例来完成上诉提到的两种实现。
首先我们创建一个 简单的 po 类，也就是我们的业务实体类。
假设一个后台管理系统的职员信息管理模块，需要新增员工信息。
新建一个Employee类 用于 封装 职员的基础信息

package com.onesport.kern.beanValidationTest.dao;
//看包名就知道这个是hibernate附加的constraints
import org.hibernate.validator.constraints.Length;
//javax.validation.constraints包下所支持的一些约束类型
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Past;
import javax.validation.constraints.Pattern;
import java.util.Date;

/**
 * @author Kern
 * @Title: Employee
 * @ProjectName kern-demo
 * @Description: TODO
 * @date 2019/9/1718:53
 */
public class Employee {

    @NotNull(message = "姓名必填!")
    @Length(max = 20, message = "姓名过长!")
    private String name;

    @NotNull(message = "工牌必填!")
    @Pattern(regexp = "^[0-9]\\d{10}",message = "请输入10位数字工牌!")//长度10，0-9
    private String badgeCode;

    @Pattern(regexp = "^[1-2]",message = "性别参数错误!")
    @NotNull(message = "性别必填!")
    private String gender;

    @Past(message = "无效的出生日期!")
    private Date birthDate;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getBadgeCode() {
        return badgeCode;
    }

    public void setBadgeCode(String badgeCode) {
        this.badgeCode = badgeCode;
    }

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    public Date getBirthDate() {
        return birthDate;
    }

    public void setBirthDate(Date birthDate) {
        this.birthDate = birthDate;
    }

    @Override
    public String toString() {
        return "Employee{" +
                "name='" + name + '\'' +
                ", badgeCode='" + badgeCode + '\'' +
                ", gender=" + gender +
                ", birthDate=" + birthDate +
                '}';
    }
}

无论是@Valid注解 + BindingResult 这种形式 或者是 直接调用Validator.validate() 方法，我们都可以直接使用这个 po 对象。
接下来我们简便点来，直接写出来两种实现方式的controller层方法。这里忽略了service层，如有其他的业务可以在service层写。代码如下：

package com.onesport.kern.beanValidationTest.control;

import com.onesport.kern.beanValidationTest.dao.Employee;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.*;
import java.util.List;
import java.util.Set;

/**
 * @author Kern
 * @Title: EmployeeControl
 * @ProjectName kern-demo
 * @Description: TODO
 * @date 2019/9/1722:26
 */
@RequestMapping(path = "/employee")
@RestController
public class EmployeeControl {

    //换行符
    private static String lineSeparator = System.lineSeparator();

    /**
     * 注解实现
     * 使用@Valid 注解 实体， 并传入参数bindResult以获取校验结果信息
     * @param employee
     * @param bindingResult
     * @return
     */
    @PostMapping("/bindingResult")
    public Object addEmployee(@RequestBody @Valid Employee employee, BindingResult bindingResult){
        if (bindingResult.hasErrors()){
            //校验结果以集合的形式返回，当然也可以获取单个。具体可以查看bindResult的API文档
            List<FieldError> fieldErrorList = bindingResult.getFieldErrors();
            //StringBuilder组装异常信息
            StringBuilder builder = new StringBuilder();
            //遍历拼装
            fieldErrorList.forEach(error -> {
                builder.append(error.getDefaultMessage() + lineSeparator);
            });
            builder.insert(0,"use @Valid n BingdingResult :" +lineSeparator);
            return builder.toString();
        }

        //TODO there can invoke service layer method to do someting
        return "添加职员信息成功:" + employee.toString();
    }

    //Spring boot 已帮我们把 validation 的关键对象的实例装载如 IOC 容器中
    @Autowired
    private ValidatorFactory autowiredValidatorFactory;
    @Autowired
    private Validator autowiredValidator;
    /**
     * 调用validator实现
     * @param employee
     * @return
     */
    @PostMapping("/validator")
    public Object addEmployee(@RequestBody Employee employee){
        System.out.println("这里将导入 由 Springboot 的 IOC 容器中获取的 校验器工厂和 校验器类");
        System.out.println("validator工厂类:"+ autowiredValidatorFactory.toString());
        System.out.println("validator类："+ autowiredValidator.toString());

        /**
         * 下述的工厂类和校验器类也可以使用上述由IOC容器中获取的对象实例代替
         */

        //实例化一个 validator工厂
        ValidatorFactory validatorFactory = Validation.buildDefaultValidatorFactory();
        //获取validator实例
        Validator validator = validatorFactory.getValidator();
        //调用调用，得到校验结果信息 Set
        Set<ConstraintViolation<Employee>> constraintViolationSet = validator.validate(employee);
        //StringBuilder组装异常信息
        StringBuilder builder = new StringBuilder();
        //遍历拼装
        constraintViolationSet.forEach(violationInfo -> {
            builder.append(violationInfo.getMessage() + lineSeparator);
        });
        if (builder.toString().length() > 0){
            builder.insert(0,"use validator :" +lineSeparator);
            return builder.toString();
        }
        //TODO there can invoke service layer method to do someting
        return "添加职员信息成功:" + employee.toString();
    }
}

上下两个方法，分别对应两种实现。我们测试一下结果。这里直接使用yapi接口管理工具来测试了。
首先调用一下第一个实现 @Valid + BingdingResult：
参数：

结果：

再调用一下第二个实现 直接调用 validator
参数： 这次我们只把姓名和工牌写错

结果：
控制台console：

返回信息：

2.2.4 对比不同实现的一些总结。

我们回过头来看一下上述两种实现，第一种实现 BindingResult是 Spring 提供的再封装工具，底层是调用 spring aop ，在我们业务开发中实现也相对简单，method body 也可以很方便的进行封装成一个通用的工具方法供调用，以免重复写这些代码。但是总是要带这个bindResult 参数还是比较烦。
而第二种实现方法就相对较为灵活，同样也是可编程的，在对一些Excel批量导入的数据校验等等的场景会较为灵活。

3 补充 @Validated 注解 + javax.validation.constraints.*

这部分一直没有补充，趁五一前补充一下，源码看了个大概，没有细研究，但大体上应该没错。
自spring 3.1 版本起提供了 @Validated 注解用于方法参数的表单校验， 同样也是基于 JSR-303 标准，是spring mvc对表单校验支撑框架的进一步封装。

前景提要，需要依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
            <version>你的springboot版本</version>
        </dependency>

下面的介绍内容建议结合源码一起看。

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Validated {

	/**
		指定验证组, 可以看下 javax.validation.groups.Default 接口, 就是校验的时候注解指定组，然后两两对应，
		支持继承关系
	 */
	Class<?>[] value() default {};
}

这个注解可以注释到类，方法，参数上，意思也很简单，如果注解到类上，则类的所有方法的所有参数都进行表单校验，以此类推方法级别和参数级别的。

该注解结合基于BeanPostProcessor的 MethodValidationPostProcessor , 在bean构建后搜索相关的注解和 validation注解，如果匹配到参数需要进行校验，插入切面和配置的校验器在请求时拦截并校验。

@Configuration
@ConditionalOnClass({ExecutableValidator.class})
@ConditionalOnResource(
    resources = {"classpath:META-INF/services/javax.validation.spi.ValidationProvider"}
)
@Import({PrimaryDefaultValidatorPostProcessor.class})
public class ValidationAutoConfiguration {
    public ValidationAutoConfiguration() {
    }

    @Bean
    @Role(2)
    @ConditionalOnMissingBean({Validator.class})
    public static LocalValidatorFactoryBean defaultValidator() {
        LocalValidatorFactoryBean factoryBean = new LocalValidatorFactoryBean();
        MessageInterpolatorFactory interpolatorFactory = new MessageInterpolatorFactory();
        factoryBean.setMessageInterpolator(interpolatorFactory.getObject());
        return factoryBean;
    }

    @Bean
    @ConditionalOnMissingBean
    public static MethodValidationPostProcessor methodValidationPostProcessor(Environment environment, @Lazy Validator validator) {
        MethodValidationPostProcessor processor = new MethodValidationPostProcessor();
        boolean proxyTargetClass = (Boolean)environment.getProperty("spring.aop.proxy-target-class", Boolean.class, true);
        processor.setProxyTargetClass(proxyTargetClass);
        processor.setValidator(validator);
        return processor;
    }
}

关于校验器
如果你不对校验器进行配置，springboot自动注入的是LocalValidatorFactoryBean, 即一个支持国际化语言翻译的校验器工厂类，题外话(简单说你可以使用例如 i18n 等国际化技术来 翻译 你 校验注解上的 消息 ， 例如 @NotNull(message="Validation.UserId.NotNull") ，然后根据语言环境转换这个message。)

上面

关于切面拦截器
我们做好配置和编码后程序织入的切面如何处理呢？一段代码可以很简单的说明

// ==================================== part1  自动注入 ========================================

public class ValidationAutoConfiguration {

	//自动注入注入了 MethodValidationPostProcessor  注意参入了一个懒加载的校验器，这个是可以配置的
	@Bean
	public static MethodValidationPostProcessor methodValidationPostProcessor(Environment environment, @Lazy Validator validator) {
	}
}
// ==================================== part2  Bean初始化 ========================================
public class MethodValidationPostProcessor extends AbstractBeanFactoryAwareAdvisingPostProcessor
		implements InitializingBean {
	@Nullable
	private Validator validator;
	/**
	 * Validator 也是可以配置的
	 */
	public void setValidator(Validator validator) {// 忽略实现}

	/**
	 * 工厂同理
	 */
	public void setValidatorFactory(ValidatorFactory validatorFactory) {// 忽略实现}

	/**
	这个类是 InitializingBean 的实现，初始化完成后会构造一个默认的切面advice, 最终构造的默认就是 MethodValidationInterceptor
	**/
	@Override
	public void afterPropertiesSet() {
		Pointcut pointcut = new AnnotationMatchingPointcut(this.validatedAnnotationType, true);
		this.advisor = new DefaultPointcutAdvisor(pointcut, createMethodValidationAdvice(this.validator));
	}
	protected Advice createMethodValidationAdvice(@Nullable Validator validator) {
		return (validator != null ? new MethodValidationInterceptor(validator) : new MethodValidationInterceptor());
	}
}

// ==================================== part3  拦截器实现 ========================================

public class MethodValidationInterceptor implements MethodInterceptor {

	// 直接看invoke方法，去掉了多余的代码，直接看流程
	@Override
	@SuppressWarnings("unchecked")
	public Object invoke(MethodInvocation invocation) throws Throwable {
		Set<ConstraintViolation<Object>> result = execVal.validateParameters(invocation.getThis(), methodToValidate, invocation.getArguments(), groups);
		Object returnValue = invocation.proceed();
		result = execVal.validateReturnValue(invocation.getThis(), methodToValidate, returnValue, groups);
		if (!result.isEmpty()) {
			/**
			*  如果 ConstraintViolation 集合不为空，就抛出一个 ConstraintViolationException 异常
			*/
			throw new ConstraintViolationException(result);
		}
		return returnValue;
	}

结果就很清晰了，使用 @Valid + BindingResult 的方式，我们在Controller中判断BindingResult ，然后自己处理异常，这样也挺好，但是代码整体不够优美，当然我们可以自己实现切面。

而 @Validated 是Spring 默认实现的一个切面，他提供了类级别，方法级别，参数级别的表单校验识别， 只要你使用了注解， 方法就会被织入切面。 最终的结果是当表单校验发生错误时，抛出一个 ConstraintViolationException。 一提到异常处理，我们接下来就可以使用全局异常捕获这种方式来进行处理了。如下

@RestControllerAdvice
@Component
public class GlobalExceptionHandler {

	// 当直接校验具体参数时会出现javax.validation.ConstraintViolationException
    @ExceptionHandler(value = ConstraintViolationException.class)
    public HttpResult<?> handleException(ConstraintViolationExceptione e) {
        log.error("表单校验异常信息 msg={}, requestId={}", e.getMessage(), RoutedInnerRequestHelper.getRequestId(), e);
        // 拼接参数
        String errorMsg = ex.getConstraintViolations().stream().map(ConstraintViolation::getMessage).collect(Collectors.joining(", "));
        return HttpResult.fail(ResultCodeEnum.EXCEPTION.getCode(), errorMsg);
    }

}

做好上面的配置后, 我们要做的事情和 使用 @Valid + BindingResult 的事情差不多

// 请求参数加 javax.validation.constraints包下的注解注解
@Data
public class Employee {

    @NotNull(message = "姓名必填!")
    @Length(max = 20, message = "姓名过长!")
    private String name;

    @NotNull(message = "工牌必填!")
    @Pattern(regexp = "^[0-9]\\d{10}",message = "请输入10位数字工牌!")//长度10，0-9
    private String badgeCode;

    @Pattern(regexp = "^[1-2]",message = "性别参数错误!")
    @NotNull(message = "性别必填!")
    private String gender;

    @Past(message = "无效的出生日期!")
    private Date birthDate;
}

// controller 加注解    这里加了好几个注解方便说明，一般按需加注就可以了
@RequestMapping(path = "/employee")
@RestController
@Validated //注解到类上, 则所有方法都会扫描 javax.validation.constraints包下的注解
public class EmployeeControl {

    //换行符
    private static String lineSeparator = System.lineSeparator();

    @PostMapping("/bindingResult")
    @Validated //注解到方法上, 就这个方法的所有参数都进行校验扫描
    public Object addEmployee(@RequestBody @Validated Employee employee){  //注解到参数, 只有这个参数校验 
        //TODO there can invoke service layer method to do someting
        return "添加职员信息成功:" + employee.toString();
    }
}

这样就完成了表单校验部分的编码。 是不是比 @Valid 用起来更优雅。

最后一个， 如果有小伙伴需要了解 @Validted + 国际化语言的实现方案的，可以留言， 我再出一篇博文