@Valid 和 @Validated 的区别

前言

参数校验是保证程序健壮性的重要环节，前端校验为用户体验，后端校验为系统安全。Spring Boot 中常用 @Valid 和 @Validated 实现参数校验，本文将详细解析两者的区别、用法及代码示例。

一、@Valid 注解

1. 功能与依赖

• 标准规范：属于 Java EE 标准注解（JSR 303 规范），用于触发参数合法性校验。
• 依赖引入：
  • Spring Boot 项目：已包含在 spring-boot-starter-web 中，无需额外引入。
  • 非 Spring Boot 项目：需手动添加 javax.validation 和 hibernate-validator 依赖。

<!-- 非Spring Boot项目依赖 -->  
<dependency>  
    <groupId>javax.validation</groupId>  
    <artifactId>validation-api</artifactId>  
</dependency>  
<dependency>  
    <groupId>org.hibernate</groupId>  
    <artifactId>hibernate-validator</artifactId>  
</dependency>  

2. 使用场景

• 适用位置：方法参数、构造函数、成员属性（field）、方法返回值。
• 核心功能：支持嵌套校验（对对象中的属性值，甚至嵌套对象进行校验）。

• 代码示例：

  // 实体类  
  @Data  
  public class SysUser {  
    @NotBlank(message = "姓名不能为空")  
    @Length(max = 10, message = "名称不能超过{max}字符")  
    private String name;  
  
    @NotNull(message = "年龄不能为空")  
    @Range(min = 1, max = 100, message = "年龄范围为{min}到{max}岁")  
    private Integer age;  
  }  

  // 控制器  
  @RestController  
  @RequestMapping("/sysUser")  
  public class SysUserController {  
    @PostMapping("/add")  
    public String addUser(@RequestBody @Valid SysUser sysUser, BindingResult bindingResult) {  
        if (bindingResult.hasErrors()) {  
            return bindingResult.getAllErrors().get(0).getDefaultMessage(); // 返回第一条错误信息  
        }  
        return "操作成功！";  
    }  
  }  

  说明：需通过 BindingResult 手动捕获校验结果，若不处理错误，程序不会中断执行。

二、@Validated 注解

1. 功能与定位

• Spring 专属：Spring 框架特有的注解，是 @Valid 的增强版，支持分组验证。
• 无嵌套校验：仅能对单一对象进行校验，无法递归验证嵌套对象。

2. 使用场景

• 适用位置：类、方法、方法参数（不能用于成员属性）。

• 分组验证：针对同一对象的不同操作（如新增、更新），设置不同的校验规则。

  // 分组接口  
  public interface CreationGroup {} // 新增分组  
  public interface UpdateGroup {} // 更新分组  

  // 实体类（分组校验示例）  
  @Data  
  public class SysUser {  
    @NotNull(message = "更新时ID不能为空", groups = UpdateGroup.class)  
    private String id;  
  
    @NotBlank(message = "名字不能为空", groups = {CreationGroup.class, UpdateGroup.class})  
    @Size(min = 6, max = 12, message = "名字长度在6-12之间")  
    private String name;  
  }  

  // 控制器（分组校验应用）  
  @RestController  
  public class SysUserController {  
    @PostMapping("/insert")  
    public String insertUser(@Validated(CreationGroup.class) @RequestBody SysUser sysUser, BindingResult bindingResult) {  
        if (bindingResult.hasErrors()) {  
            return "插入失败：" + bindingResult.getFieldError().getDefaultMessage();  
        }  
        return "插入成功";  
    }  
  
    @PostMapping("/update")  
    public String updateUser(@Validated(UpdateGroup.class) @RequestBody SysUser sysUser, BindingResult bindingResult) {  
        // 同上逻辑  
    }  
  }  

3. 全局异常处理

• 自动抛异常：使用 @Validated 时，若校验失败，程序会自动抛出 MethodArgumentNotValidException。
• 统一捕获：通过 @RestControllerAdvice 全局捕获异常，返回友好提示。

  @RestControllerAdvice  
  public class ValidatedExceptionHandler {  
    @ExceptionHandler(MethodArgumentNotValidException.class)  
    @ResponseBody  
    @ResponseStatus(HttpStatus.BAD_REQUEST)  
    public Result handleValidationException(MethodArgumentNotValidException ex) {  
        String errorMessage = ex.getBindingResult().getAllErrors().get(0).getDefaultMessage();  
        return Result.error("参数校验失败：" + errorMessage);  
    }  
  }  

三、核心区别对比

四、参数校验常用注解

1. 值校验

2. 范围校验

3. 长度校验

4. 格式校验

五、总结

• 选择建议：
  • 需要嵌套校验（如对象中包含子对象）时，使用 @Valid。
  • 需要分组验证（如不同业务场景执行不同校验规则）时，使用 @Validated。
• 最佳实践：
  • 统一使用 @Validated 简化代码，通过全局异常处理统一返回错误信息。
  • 复杂校验场景结合分组验证，提高代码可维护性。

掌握 @Valid 和 @Validated 的区别，能更灵活地实现参数校验，保障系统数据的完整性和安全性。