当前位置：首页 > news >正文

带你搞懂@Valid和@Validated的区别

news 来源：原创 2025/7/21 15:07:02

前言

有参数传递的地方都少不了参数校验。在实际开发过程中，参数校验是保证程序健壮性的重要环节，前端的参数校验是为了用户体验，后端的参数校验是为了安全。试想一下，如果在 Controller 层中没有经过任何校验的参数通过 Service层、Dao层一路来到了数据库就可能导致严重的后果，最好的结果是查不出数据。严重一点就是报错，如果这些没有被校验的参数中包含了恶意代码，那就可能导致更严重的后果。因此，对于请求参数，一般上都需要进行参数合法性校验的，参数校验是确保数据完整性和一致性的重要手段。日常开发过程中，经常遇到大量的参数进行校验, 在业务中还要抛出异常等校验信息, 在代码中相当冗长, 充满了 if-else 这种校验代码, 代码不够优雅。@Valid、@Validated 是 Spring Boot 中用于参数校验的两个核心注解，本文将详细介绍这两个注解的用法、区别以及代码样例。

@Valid注解

功能介绍

@Valid 是 Java EE 提供的标准注解，它是 JSR 303 规范的一部分。在 Spring Boot 项目中，主要用于触发参数校验，确保请求参数的合法性。Javax.validation 是 Spring 集成自带的一个参数校验接口，可通过添加注解来设置校验条件。若是 Spring Boot 项目，就不用引入了，它已经存在于最核心的 web 开发包里面。

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><version>2.0.5.RELEASE</version>
</dependency>

如若不是 Spring Boot 项目，那么引入下面依赖即可：

<dependency><groupId>javax.validation</groupId><artifactId>validation-api</artifactId><version>x.y.z</version>
</dependency><dependency><groupId>org.hibernate</groupId><artifactId>hibernate-validator</artifactId><version>z.y.z</version>
</dependency>

使用场景

@Valid 可以用于方法参数、构造函数、方法参数和成员属性上。它主要用于嵌套校验，即对于对象中的属性值（可能是另一个对象）进行校验。例如：

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class SysUser {@NotBlank(message = "请输入姓名")@Length(message = "名称不能超过个 {max} 字符", max = 10)private String name;@NotNull(message = "请输入年龄")@Range(message = "年龄范围为 {min} 到 {max} 岁之间", min = 1, max = 100)private Integer age;@NotNull(message = "请选择性别")private Integer sex;private String phone;
}

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

import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.*;@RestControoler
@RequestMapping("/sysUser")
public class SysUserController {@PostMapp("/add")public String addUser(@ResuestBody @Valid SysUser sysUser BindingResult bindingResult){// 所有字段是否验证通过，true-数据有误，false-数据无误if (bindingResult.hasErrors()){// 有误，则返回第一条错误信息return bindingResult.getAllErrors().get(0).getDefaultMessage();}retrun "操作成功！";}
}

在上述代码中，在 SysUserController 中，addUser 方法使用了 @Valid 注解对传入的 SysUser 对象进行校验，并使用 BindingResult 捕获校验错误。

@Validated注解

功能介绍

@Validated 是 Spring 框架特有的注解，属于 Spring 的一部分，也是 JSR 303 的一个变种。简单来说，@Validated 可以说是 @Valid 注解的一个升级版。它提供了一些 @Valid 所没有的额外功能，比如分组验证。@Validated注解可以用在类、方法和方法参数上，但不能用于成员属性。

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Person {@NotNull(message = "id添加时可以为空，更新时不能为空", groups = {UpdateGroup.class})private Integer id;@NotBlank(message = "名字不能为空", groups = {UpdateGroup.class, AddGroup.class})@Size(min = 6, max = 12, message = "名字的长度在6到12之间", groups = {UpdateGroup.class, AddGroup.class})private String username;@NotNull(message = "年龄不能为空", groups = {UpdateGroup.class, AddGroup.class})@Min(value = 20, message = "最小年龄要大于20", groups = {UpdateGroup.class, AddGroup.class})private Integer age;
}

使用场景

@Validated 注解主要用于支持分组验证，可以更细致地控制验证过程。一般在对同一个对象进行保存或修改时，会使用同一个类作为入参。那么在创建时，就不需要校验id，更新时则需要校验用户id，这个时候就需要用到分组校验了。分组验证是为了在不同的验证场景下能够对对象的属性进行灵活地验证，从而提高验证的精细度和适用性。

/*** 用于创建时指定的分组*/
public interface CreationGroup {
}/*** 用于更新时指定的分组*/
public interface UpdateGroup {
}@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class SysUser {@NotBlank(message="id添加时可以为空，更新时不能为空", groups={UpdateGroup.class})private String id;@NotBlank(message="名字不能为空", groups={CreationGroup.class, UpdateGroup.class})@Size(min=6, max=12, message="名字的长度在6到12之间", groups={CreationGroup.class, UpdateGroup.class})private String name;@NotNull(message="年龄不能为空", groups={CreationGroup.class, UpdateGroup.class})@Min(value = 1, message = "年龄不能小于1", groups=ValidationGroups.Insert.class)private int age;
}

在上述代码中，我们定义了一个 CreationGroup、UpdateGroup 两个接口，用于分组验证。SysUser 类中的 id 属性在 Update 分组下必填，而 age 属性在 Insert 分组下必填且不能小于1。

@RestController
public class SysUserController {@PostMapping("/insert")public String insertUser(@Validated(value=CreationGroup.class) @RequestBody SysUser sysUser, BindingResult bindingResult) {if (bindingResult.hasErrors()) {return "参数校验失败: " + bindingResult.getAllErrors().get(0).getDefaultMessage();}return "插入成功";}@PostMapping("/update")public String updateUser(@Validated(value=UpdateGroup.class) @RequestBody SysUser sysUser, BindingResult bindingResult) {if (bindingResult.hasErrors()) {return "参数校验失败: " + bindingResult.getAllErrors().get(0).getDefaultMessage();}return "更新成功";}
}

在 SysUserController 中，insertUser 方法使用 @Validated(value=CreationGroup.class) 对传入的 SysUser 对象进行 Insert 分组的校验，而 updateUser 方法则使用 @Validated(value=UpdateGroup.class) 进行 Update 分组的校验。对于定义分组有两点要特别注意：

定义分组必须使用接口。
要校验字段上必须加上分组，分组只对指定分组生效，不加分组不校验。

异常统一处理

我们可以看到，在使用 @Valid 进行验证时，需要用一个对象去接收校验结果，最后根据校验结果判断，从而提示用户。现在，我们去掉方法参数上的 @Valid 注解和其配对的 BindingResult 对象，然后再校验的对象前面添加上 @Validated 注解。

import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;@RestControoler
@RequestMapping("/sysUser")
public class SysUserController {@PostMapp("/add")public String addUser(@ResuestBody @Validated SysUser){// 所有字段是否验证通过，true-数据有误，false-数据无误if (bindingResult.hasErrors()){// 有误，则返回第一条错误信息return bindingResult.getAllErrors().get(0).getDefaultMessage();}retrun "操作成功！";}
}

这个时候若是请求，可以看到程序报异常了。那么，从这里可以得知，当数据存在校验不通过的时候，程序就会抛出 org.springframework.validation.BindException 的异常。在实际开发的过程中，肯定不能讲异常直接展示给用户，而是给能看懂的提示。于是，不妨可以通过捕获异常的方式，将该异常进行捕获。首先创建一个校验异常捕获类 ValidExceptionHandler ，然后加上 @RestControllerAdvice 注解，该注解表示会捕获所有 @Controller 标记类的异常，并在异常处理后返回以 JSON 或字符串的格式响应前端。在异常捕捉到后，同上面的 @valid 校验一样，只返回第一个错误提示。

import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.validation.*;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.*;
import java.util.List;@ControllerAdvice
public class ValidatedExceptionHandler {/*** 处理@Validated参数校验失败异常*/@ResponseBody@ResponseStatus(HttpStatus.BAD_REQUEST)@ExceptionHandler(MethodArgumentNotValidException.class)public Result<String> exceptionHandler(MethodArgumentNotValidException exception) {BindingResult result = exception.getBindingResult();StringBuilder stringBuilder = new StringBuilder();if (result.hasErrors()) {List<ObjectError> errors = result.getAllErrors();errors.forEach(p -> {FieldError fieldError = (FieldError) p;stringBuilder.append(fieldError.getDefaultMessage());});}return Result.error(stringBuilder.toString());}}

知识拓展

@Valid 和 @Validated 区别

@Validated 和 @Valid 在检验参数符合规范的功能上基本一致，两者都可以对数据进行校验，在校验字段上加上规则注解（@NotNull, @NotEmpty等）都可以对 @Valid 和 @Validated 生效。只不过 validated 是 Spring Validation 验证框架对参数的验证机制，而 valid 是 javax 提供的参数验证机制。先看下两者的源码：

@Target({ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Valid {
}@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Validated {Class<?>[] value() default {};
}

适用场景：@Valid 适用于使用Hibernate validation框架的情况，而 @Validated 则适用于使用Spring Validator校验机制的场景。因此，选择合适的注解要根据实际使用的框架来决定。
验证方式：@Valid 可以进行嵌套验证，这意味着它可以对复合对象进行深层次的验证。而 @Validated 则不具备嵌套验证的功能，它只能对单一对象进行校验。因此，在需要进行复合对象验证时，应选择 @Valid 注解。
使用范围：@Valid 可以用在方法、构造函数、方法参数和成员属性（field）上，支持在多种场合下进行参数校验。而 @Validated 则主要用于类、方法和方法参数上，不能用于成员属性（field）。因此，在使用成员属性（field）进行校验时，应选择 @Valid 注解。
自定义校验规则：@Validated 提供了分组功能，可以在参数验证时根据不同的分组采用不同的验证机制。这意味着可以根据实际需求将参数分为不同的组，并为每组设置特定的校验规则。而 @Valid 注解则没有分组功能，其校验规则较为固定。因此，在需要自定义校验规则时，应选择@Validated注解。
校验结果：@Valid 进行校验的时候，需要用 BindingResult 来做一个校验结果接收。当校验不通过的时候，如果手动不 return ，则并不会阻止程序的执行。@Validated 进行校验的时候，当校验不通过的时候，程序会抛出400异常，阻止方法中的代码执行，这时需要再写一个全局校验异常捕获处理类，然后返回校验提示。

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

参数校验常用注解

值校验

注解	说明	示例
@Null	任意类型，被注解的元素必须为null	@Null(message = “人数必须为null”) private Integer num;
@NotNull	任意类型，被注解的元素必须不为null	@NotNull(message = “人数不能为null”) private Integer num;
@NotBlank	只能作用于字符串，验证注解的元素值不为空。字符串长度必须大于0，至少包含一个非空字符串	@NotBlank(message = “姓名不能为空”) private String name;
@NotEmpty	验证注解的元素值不为null且不为空。字符串长度必须大于0，空字符串（“ ”）可以通过校验	@NotEmpty(message = “组织部门不能为空”) private List<String> userList;
@AssertTrue	被注解的元素必须为true，并且类型为boolean	@AssertTrue(message = “状态必须为true”) private boolean status;
@AssertFalse	被注解的元素必须为false，并且类型为boolean	@AssertFalse(message = “状态必须为false”) private boolean status;
@Positive	被注解的元素必须为正数	@Negative(message = “金额必须是正数或0”) private BigDecimal amount;
@PositiveOrZero	被注解的元素必须为正数或 0	@Negative(message = “金额必须是正数或0”) private BigDecimal amount;
@Negative	被注解的元素必须为负数	@Negative(message = “金额必须是负数”) private BigDecimal amount;
@NegativeOrZero	被注解的元素必须为负数或 0	@Negative(message = “金额必须是负数或0”) private BigDecimal amount;

范围校验

注解	说明	示例
@Min	被注解的元素其值必须大于等于最小值	@Min(value = 18, message = “必须大于等于18岁”) private int age;
@Max	被注解的元素其值必须小于等于最小值	@Max(value = 120, message = “必须小于等于120岁”) private int age;
@DecimalMin	验证注解的元素值大于等于指定的value值，并且类型为BigDecimal	@DecimalMin(value = “1”, message = “必须大于等于1”) private BigDecimal money;
@DecimalMax	验证注解的元素值小于等于指定的value值，并且类型为BigDecimal	@DecimalMax(value = “10”, message = “必须小于等于10”) private BigDecimal money;
@Range	验证注解的元素值在最小值和最大值之间	@Range(max = 80, min = 18, message = “必须大于等于18或小于等于80”) private int age;
@Past	被注解的元素必须为过去的一个时间	@Past(message = “必须为过去的时间”) private Date createDate;
@PastOrPresent	被注解的元素必须为当前时间或之前的时间	@PastOrPresent(message = “必须为当前或过去的时间”) private Date createDate;
@Future	被注解的元素必须为未来的一个时间	@Future(message = “必须为未来的时间”) private Date createDate;
@FutureOrPresent	被注解的元素必须为当前或之后的时间	@FutureOrPresent(message = “必须为当前或未来的时间”) private Date createDate;

长度校验

注解	说明	示例
@Size	被注解的元素的长度必须在指定范围内	@Size(max = 11, min = 7, message = “长度必须大于等于7或小于等于11”) private String mobile;
@Length	验证注解的元素值长度在min和max区间内，并且类型为String	@Length(max = 11, min = 7, message = “长度必须大于等于7或小于等于11”) private String mobile;

格式校验

注解	说明	示例
@Digits	验证注解的元素值的整数位数和小数位数上限	@Digits(integer=3,fraction = 2,message = “整数位上限为3位，小数位上限为2位”) private BigDecimal money;
@Pattern	被注解的元素必须符合指定的正则表达式，并且类型为String	@Pattern(regexp = “^1[1-9]\d{9}$”, message = “手机号格式错误”) private String mobile;
@Email	被注解的元素值是Email，也可以通过regexp和flag指定自定义的email格式	@Email(message = “必须是邮箱”) private String email;
@Valid	指定递归验证关联的对象。	@Valid private UserDto userDto;
@URL	被注解的元素必须是一个有效的url地址，并且类型为String	@URL(message = “无效的url地址”) private String url;

小结

@Valid、@Validated 在 Spring Boot 的参数校验中扮演着重要角色，在实际开发中，选择合适的注解进行参数校验需要考虑多个因素，了解注解的使用限制和特点也有助于我们更好地规避潜在的问题和提高代码的可维护性。总之，了解并正确使用 @Valid 和 @Validated 注解是保障程序健壮性的关键之一。掌握这两个注解的用法和区别，可以帮助开发者更灵活地进行参数校验，确保数据的完整性和一致性，从而提高程序的稳定性和可靠性。

前言

@Valid注解

功能介绍

使用场景

@Validated注解

功能介绍

使用场景

异常统一处理

知识拓展

@Valid 和 @Validated 区别

参数校验常用注解

值校验

范围校验

长度校验

格式校验

小结

相关文章：