java

@Valid 和 @Validated 注解用法详解

目录
  1. 1. 案例引入
  2. 2. @Valid 详解
  3. 3. @Validated 详解
  4. 4. @Valid 和 @Validated 比较
    1. 4.1. 实际测试发现：使用@Valid进行校验的时候，不使用 BindingResult 接收校验结果，在统一异常处理时，也能拦截到MethodArgumentNotValidException错误。
  5. 5. 自定义校验注解：
  6. 6. @Validated分组功能
  7. 7. 嵌套类校验
  8. 8. requestParam/PathVariable参数校验
  9. 9. 全局统一异常处理
  10. 10. Hibernate-Validator注解
    1. 10.1. 常用注解
    2. 10.2. 不常用注解

案例引入

下面我们以新增一个员工为功能切入点，以常规写法为背景，慢慢烘托出 @Valid 和 @Validated 注解用法详解。

那么，首先，我们会有一个员工对象 Employee，如下 ：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
/**
 * 员工对象
 * 
 * @author sunnyzyq
 * @since 2019/12/13
 */
public class Employee {
 
    /** 姓名 */
    public String name;
 
    /** 年龄 */
    public Integer age;
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
    public Integer getAge() {
        return age;
    }
 
    public void setAge(Integer age) {
        this.age = age;
    }
 
}

然后 Cotroller 中会有一个对应都新增方法 add()，如下：

1
2
3
4
5
6
7
8
9
10
11
@Controller
public class TestController {
 
    @RequestMapping("/add")
    @ResponseBody
    public String add(Employee employee) {
        // TODO 保存到数据库
        return "新增员工成功";
    }
 
}

现在要求：员工的名称不能为空，且长度不能超过10个字符，那么我们以前的做法大致如下：

写完，我们启动项目测试下：

（1）名称为空情况

（2）正常情况

（3）超过长度情况

可以看到，和我们料想中的一样，毫无问题。

除了名称外，我们规定年龄也是必填项，且范围在1到100岁，那么此时，我们需要增加对应判定代码如下：

那么问题来了，现在员工对象 Employee 就 2 个字段，我们就写了 10 多行的代码验证，要是有20个字段，岂不是要写 100 多行代码？通常来说，当一个方法中的无效业务代码量过多时，往往代码设计有问题，当然这不是我们所想看到都结果。

那么如何解决呢？首先大家应该会想到将对应的验证过程抽成一个验证方法，如下：

这样来看，我们的业务方法就清爽多了。

但这种方式只是抽了一个方法，有一种换汤不换药的感觉，虽然业务方法看起来清爽了很多，但书写代码量并没有下降，反而还多出了一个方法，这也不是我们理想中的样子。

@Valid 详解

此时，我们引出 Spring 中的 @valid 注解，这些问题就可以迎刃而解了，具体如下：

首先，我们在 Maven 配置中引入 @valid 的依赖：

如果你是 springboot 项目，那么可以不用引入了，已经引入了，他就存在于最核心的 web 开发包里面。

1
2
3
4
5
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.0.5.RELEASE</version>
</dependency>

如果你不是 springboot 项目，那么引入下面依赖即可：

1
2
3
4
5
6
7
8
9
10
11
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>1.1.0.Final</version>
</dependency>
 
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>5.4.1.Final</version>
</dependency>

那么针对上面情景，我们可以对我们的代码进行优化了。

首先我们在 Employee 类的属性上打上如下注解：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
package com.zyq.beans;
 
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
 
import org.hibernate.validator.constraints.Length;
import org.hibernate.validator.constraints.Range;
 
/**
 * 员工对象
 * 
 * @author sunnyzyq
 * @since 2019/12/13
 */
public class Employee {
 
    /** 姓名 */
    @NotBlank(message = "请输入名称")
    @Length(message = "名称不能超过个 {max} 字符", max = 10)
    public String name;
 
    /** 年龄 */
    @NotNull(message = "请输入年龄")
    @Range(message = "年龄范围为 {min} 到 {max} 之间", min = 1, max = 100)
    public Integer age;
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
    public Integer getAge() {
        return age;
    }
 
    public void setAge(Integer age) {
        this.age = age;
    }
 
}

然后再 Controller 对应方法上，对这个员工标上 @Valid 注解，表示我们对这个对象属性需要进行验证，

既然验证，那么就肯定会有验证结果，所以我们需要用一个东西来存放验证结果，做法也很简单，在参数直接添加一个BindingResult，具体如下：

对应获取验证结果的代码如下：

需要注意的是@Valid和BindingResult是一一对应的，如果有多个@Valid，那么每个@Valid后面都需要添加BindingResult用于接收bean中的校验信息

1
2
3
4
5
6
//获取错误信息
FieldError fieldError = bindingResult.getFieldError();
//获取验证失败字段名
String field = fieldError.getField();
//获取验证失败的message
String defaultMessage=fieldError.getDefaultMessage();

OK ! 万事俱备 ！我们进行测试下：

（1）名称为空

（2）名称正常，年龄为空

（3）名称超出范围，年龄正常

（4）名称正常，年龄超出范围

可以看到，代码不但简洁了很多，结果和预期的也一模一样！很棒吧！！

常用注解：

除了刚刚都注解，最后再附加2个常用注解，我就直接贴图了，基本上这6个注解可以解决99%的字段，其他注解我就不贴图了，如果不满足，自己问百度。

@Validated 详解

上面，我们讲述了 @Valid 注解，现在我们来说说 @Validated 这个注解，在我看来，@Validated 是在 @Valid 基础上，做的一个升级版。

我们可以看到，我们在使用 @Valid 进行验证的时候，我们需要用一个对象去接收校验结果，最后根据校验结果判断，从而提示用户。

如果我们把手动校验的这段代码删除或注释掉，那么即使当我们的字段不满足规则时，方法种的程序也是能够被执行的。

比如，我们将字段值置空时，正常情况是会进行提示的。

 当我们把校验逻辑注释掉后，再次执行上面的请求后。

可以看到我们的程序继续往后面去执行完成了。

现在，我们去掉方法参数上的 @Valid 注解和其配对的 BindingResult 对象，

然后再校验的对象前面添加上 @Validated 注解。

这个时候，我们再次请求，可以看到，我们请求报400错误了。

而我们通过程序的异常日志来看，提示说是 age 和 name 字段为了空，致使请求失败。

那么，从这里我们可以得知，当我们的数据存在校验不通过的时候，程序就会抛出

org.springframework.validation.BindException 的异常。

在实际开发的过程中，我们肯定不能讲异常直接展示给用户，而是给能看懂的提示。

于是，我们不妨可以通过捕获异常的方式，将该异常进行捕获。

首先我们创建一个校验异常捕获类 ValidExceptionHandler ，然后打上 @RestControllerAdvice 注解，该注解表示他会去抓所有 @Controller 标记类的异常，并在异常处理后返回以 JSON 或字符串的格式响应前端。

在异常捕捉到后，我们同上面的 @valid 校验一样，只返回第一个错误提示。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package com.zyq.config;
 
import org.springframework.validation.BindException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
 
@RestControllerAdvice
public class ValidExceptionHandler {
 
    @ExceptionHandler(BindException.class)
    public String validExceptionHandler(BindException exception) {
        return exception.getAllErrors().get(0).getDefaultMessage();
    }
 
}

那么，我们现在重启程序，然后重新请求，就可以发现界面已经不报400错误了，而是直接提示了我们的错误信息。

@Valid 和 @Validated 比较

最后我们来对 @Valid 和 @Validated 两个注解进行总结下：

（1）@Valid 和 @Validated 两者都可以对数据进行校验，待校验字段上打的规则注解（@NotNull, @NotEmpty等）都可以对 @Valid 和 @Validated 生效；

（2）@Valid 进行校验的时候，需要用 BindingResult 来做一个校验结果接收。当校验不通过的时候，如果手动不 return ，则并不会阻止程序的执行；

（3）@Validated 进行校验的时候，当校验不通过的时候，程序会抛出400异常，阻止方法中的代码执行，这时需要再写一个全局校验异常捕获处理类，然后返回校验提示。

（4）总体来说，@Validated 使用起来要比 @Valid 方便一些，它可以帮我们节省一定的代码，并且使得方法看上去更加的简洁。

实际测试发现：使用@Valid进行校验的时候，不使用 BindingResult 接收校验结果，在统一异常处理时，也能拦截到MethodArgumentNotValidException错误。

自定义校验注解：

创建注解：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Target({ElementType.METHOD,ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = {MyConstraintValidator.class})//引入自定义验证规则文件
public @interface MyValid {

    //自定义属性,最小长度，可以设置默认值，也可以不设置
    int min() default 3;

    String message() default "{javax.validation.constraints.NotBlank.message}";

    Class<?>[] groups() default { };

    Class<? extends Payload>[] payload() default { };
}

创建自定义验证规则文件，简单的实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/*
 *需要实现ConstraintValidator<A extends Annotation, T>
 *A extends Annotation:需要设置为自定义注解类型
 *T:需要校验数据的类型
 **/
public class MyConstraintValidator implements ConstraintValidator<MyValid, Object> {
    /**
    *初始化验证器，可以初始化验证注解
    *@param constraintAnnotation 验证注解的实例
    */
    @Override
    public void initialize(MyValid constraintAnnotation) {
        int min = constraintAnnotation.min();
        System.out.println("Exception");
    }
    /**
    *实现验证逻辑，判断name长度是否大于min()中定义的长度
    *@param  o 需要验证的对象
    *@param constraintValidatorContext 约束验证器的上下文
    */
    @Override
    public boolean isValid(Object o, ConstraintValidatorContext constraintValidatorContext) {
        if (o.toString().length()>min){
            return true;
        }
        return false;
    }
}

实体类：

1
2
3
4
public class Person {
    @MyValid(min = 3,message = "姓名长度不能低于3")
    private String name;
}

@Validated分组功能

比@Valid多了分组功能，用法和@Valid相同，并且自定义注解也一样

​ 扩展性高，可以根据不同的业务需求，根据设置分组进行校验

1
2
3
4
5
6
7
8
9
10
11
public interface aa {
}
public interface bb {
}

public class Person {
    @NotBlank(message = "name不能为空",groups = aa.class)
    private String name;
    @NotBlank(message = "id不能为空",groups = bb.class)
    private String id;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
@RequestMapping("/valid")
public void valid(@RequestBody @Validated(aa.class) Person person,BindingResult bindingResult) {
   Map<String, Object> model = bindingResult.getModel();
}
只会校验name

@RequestMapping("/valid")
public void valid(@RequestBody @Validated(bb.class) Person person,BindingResult bindingResult) {
   Map<String, Object> model = bindingResult.getModel();
}
只会校验id

@RequestMapping("/valid")
public void valid(@RequestBody @Validated(aa.class,bb.class) Person person,BindingResult bindingResult) {
    Map<String, Object> model = bindingResult.getModel();
}
会校验id和name

注意：分组的class只能为接口

嵌套类校验

1
2
3
@Validated：可以用在类型、方法和方法参数上。但是不能用在成员属性（字段）上
@Valid：可以用在方法、构造函数、方法参数和成员属性（字段）上
两者是否能用于成员属性（字段）上直接影响能否提供嵌套验证的功能

嵌套验证：

1
2
3
4
5
6
7
8
public class Person {
    @NotBlank(message = "name不能为空")
    private String name;
    @NotBlank(message = "id不能为空")
    private String id;
    @NotNull(message = "stus不能为空")
    private List<Stu> stus;
}

嵌套类就是一个类中包含另一个类

1
2
3
4
5
6
public class Stu {
    @NotBlank(message = "stu_name不能为空")
    private String stu_name;
    @NotBlank(message = "stu_id不能为空")
    private String stu_id;
}

如上图Person类中只能校验stus，不能校验Stu类中的stu_name和stu_id

如果想要嵌套验证，必须在Person的stus字段上面标明这个字段的实体也要进行验证，由于@Validated不能用在成员属性（字段）上，但是@Valid能加在成员属性（字段）上，而且@Valid类注解上也说明了它支持嵌套验证功能，那么我们能够推断出：@Valid加在方法参数时并不能够自动进行嵌套验证，而是用在需要嵌套验证类的相应字段上，来配合方法参数上@Validated或@Valid来进行嵌套验证。

例如：

1
2
3
4
5
6
7
8
9
10
11
public class Person {
    @NotBlank(message = "name不能为空")
    private String name;
    @NotBlank(message = "id不能为空")
    private String id;

    @Valid
    @NotNull(message = "stus不能为空")
    private List<Stu> stus;
}

就可以校验实体类Person中字段stus对应实体类中的属性了。

1
2
3
4
@RequestMapping("/valid")
public void valid(@RequestBody @Valid Person person,BindingResult bindingResult) {
    Map<String, Object> model = bindingResult.getModel();
}

@Validated： 用在方法入参上无法单独提供嵌套验证功能。不能用在成员属性（字段）上，也无法提示框架进行嵌套验证。能配合嵌套验证注解@Valid进行嵌套验证。

@Valid： 用在方法入参上无法单独提供嵌套验证功能。能够用在成员属性（字段）上，提示验证框架进行嵌套验证。能配合嵌套验证注解@Valid进行嵌套验证。

requestParam/PathVariable参数校验

GET请求一般会使用requestParam/PathVariable传参。如果参数比较多(比如超过6个)，还是推荐使用DTO对象接收。

否则，推荐将一个个参数平铺到方法入参中。在这种情况下，必须在Controller类上标注@Validated注解（添加 @Valid 不会生效），并在入参上声明约束注解(如@Min等)。如果校验失败，会抛出ConstraintViolationException异常。

代码示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@RequestMapping("/api/user")
@RestController
@Validated
public class UserController {
    // 路径变量
    @GetMapping("{userId}")
    public Result detail(@PathVariable("userId") @Min(10000000000000000L) Long userId) {
        // 校验通过，才会执行业务逻辑处理
        UserDTO userDTO = new UserDTO();
        userDTO.setUserId(userId);
        userDTO.setAccount("11111111111111111");
        userDTO.setUserName("xixi");
        return Result.ok(userDTO);
    }
 
    // 查询参数
    @GetMapping("getByAccount")
    public Result getByAccount(@Length(min = 6, max = 20) @NotNull String  account) {
        // 校验通过，才会执行业务逻辑处理
        UserDTO userDTO = new UserDTO();
        userDTO.setUserId(10000000000000003L);
        userDTO.setAccount(account);
        userDTO.setUserName("hello");
        return Result.ok(userDTO);
    }
}

全局统一异常处理

在实际项目开发中，@Validated通常会用统一异常处理来返回一个更友好的提示。比如我们系统要求无论发送什么异常，http的状态码必须返回对应业务码，由业务码去区分系统的异常情况。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import java.util.List;
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;
 
@RestControllerAdvice
public class CommonExceptionHandler {
 
    //处理请求参数格式错误 @RequestBody上validate失败后抛出的异常是MethodArgumentNotValidException异常。
    @ExceptionHandler({MethodArgumentNotValidException.class})
    public Result handleMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
        BindingResult bindingResult = ex.getBindingResult();
        StringBuilder sb = new StringBuilder("校验失败:");
        for (FieldError fieldError : bindingResult.getFieldErrors()) {
            sb.append(fieldError.getField()).append("：").append(fieldError.getDefaultMessage()).append(", ");
        }
        String msg = sb.toString();
       return Result.fail(BusinessCode.参数校验失败, msg);
    }
 
    //处理请求参数格式错误 @RequestParam上validate失败后抛出的异常是javax.validation.ConstraintViolationException
    @ExceptionHandler({ConstraintViolationException.class})
    public Result handleConstraintViolationException(ConstraintViolationException ex) {
        return Result.fail(BusinessCode.参数校验失败, ex.getMessage());
    }
}

上文说 @Valid进行校验的时候，需要用 BindingResult 来做一个校验结果接收，其实可以使用AOP技术来做全局统一异常处理。方法如下：

第一步，在需要验证的字段上加上 Hibernate Validator 提供的校验注解。

比如说我现在有一个用户名和密码登录的请求参数 UsersLoginParam 类：

1
2
3
4
5
6
7
8
9
10
11
12
13
@Data
@ApiModel(value="用户登录", description="用户表")
public class UsersLoginParam implements Serializable {
    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "登录名")
    @NotBlank(message="登录名不能为空")
    private String userLogin;

    @ApiModelProperty(value = "密码")
    @NotBlank(message="密码不能为空")
    private String userPass;
}

第二步，在对应的请求接口（UsersController.login()）中添加 @Validated 注解，并注入一个 BindingResult 参数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@Controller
@Api(tags="用户")
@RequestMapping("/users")
public class UsersController {
    @Autowired
    private IUsersService usersService;

    @ApiOperation(value = "登录以后返回token")
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    @ResponseBody
    public ResultObject login(@Validated UsersLoginParam users, BindingResult result) {
        String token = usersService.login(users.getUserLogin(), users.getUserPass());
        if (token == null) {
            return ResultObject.validateFailed("用户名或密码错误");
        }
        Map<String, String> tokenMap = new HashMap<>();
        tokenMap.put("token", token);
        tokenMap.put("tokenHead", tokenHead);
        return ResultObject.success(tokenMap);
    }
}

第三步，为控制层（UsersController）创建一个切面，将通知注入到 BindingResult 对象中，然后再判断是否有校验错误，有错误的话返回校验提示信息，否则放行。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@Aspect
@Component
@Order(2)
public class BindingResultAspect {
    @Pointcut("execution(public * com.codingmore.controller.*.*(..))")
    public void BindingResult() {
    }

    @Around("BindingResult()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        Object[] args = joinPoint.getArgs();
        for (Object arg : args) {
            if (arg instanceof BindingResult) {
                BindingResult result = (BindingResult) arg;
                if (result.hasErrors()) {
                    FieldError fieldError = result.getFieldError();
                    if(fieldError!=null){
                        return ResultObject.validateFailed(fieldError.getDefaultMessage());
                    }else{
                        return ResultObject.validateFailed();
                    }
                }
            }
        }
        return joinPoint.proceed();
    }
}

可以看得出，Hibernate Validator 带来的优势有这些：

  • 验证逻辑与业务逻辑进行了分离，降低了程序耦合度；
  • 统一且规范的验证方式，无需再次编写重复的验证代码。

不过，也带来一些弊端，比如说：

  • 需要在请求接口的方法中注入 BindingResult 对象，而这个对应在方法体中并没有用到
  • 只能校验一些非常简单的逻辑，涉及到数据查询就无能为力了。

处理比较复杂的逻辑校验，可以在校验失败的时候直接抛出自定义异常，然后进行捕获处理就可以了。

实际开发中把两者结合在一起用，就可以弥补彼此的短板了，简单校验用 Hibernate Validator，复杂一点的逻辑校验，比如说需要数据库查询用全局自定义异常来实现。

为了把 Spring Boot 逻辑校验这块单独拉出来做一个 demo 的例子，我新建了一个 codingmore-validator 的项目，放在 codingmore-learning 项目下面了，想要参考的，直接戳下面的两个链接。

完整的编程喵整个项目的源码戳第一个，只想看逻辑校验的戳第二个。

Hibernate-Validator注解

常用注解

注解 使用
@NotNull 被注释的元素（任何元素）必须不为 null, 集合为空也是可以的。没啥实际意义
@NotEmpty 用来校验字符串、集合、map、数组不能为null或空 （字符串传入空格也不可以）（集合需至少包含一个元素）
@NotBlank 只用来校验字符串不能为null，空格也是被允许的 。校验字符串推荐使用@NotEmpty
@Size(max=, min=) 指定的字符串、集合、map、数组长度必须在指定的max和min内 允许元素为null，字符串允许为空格
@Length(min=,max=) 只用来校验字符串，长度必须在指定的max和min内 允许元素为null
@Range(min=,max=) 用来校验数字或字符串的大小必须在指定的min和max内 字符串会转成数字进行比较，如果不是数字校验不通过 允许元素为null
@Min() 校验数字（包括integer short long int 等）的最小值，不支持小数即double和float 允许元素为null
@Max() 校验数字（包括integer short long int 等）的最小值，不支持小数即double和float 允许元素为null
@Pattern() 正则表达式匹配，可用来校验年月日格式，是否包含特殊字符（regexp = “^[a-zA-Z0-9\u4e00-\u9fa5

除了@Empty要求字符串不能全是空格，其他的字符串校验都是允许空格的。
message是可以引用常量的，但是如@Size里max不允许引用对象常量，基本类型常量是可以的。
注意大部分规则校验都是允许参数为null，即当不存在这个值时，就不进行校验了

不常用注解

注解 说明
@Null 被注释的元素必须为 null
@AssertTrue 被注释的元素必须为 true
@AssertFalse 被注释的元素必须为 false
@DecimalMin(value) 被注释的元素必须是一个数字，其值必须大于等于指定的最小值
@DecimalMax(value) 被注释的元素必须是一个数字，其值必须小于等于指定的最大值
@Digits (integer, fraction) 被注释的元素必须是一个数字，其值必须在可接受的范围内
@Past 被注释的元素必须是一个过去的日期
@Future 被注释的元素必须是一个将来的日期
@Email 被注释的元素必须是电子邮箱地址