Java 参数验证：@Valid 和 @Validated 的区别与最佳实践

当我们手动调用 Validator.validate(order) 时，Validator 不仅会验证 Order 自身属性（如 orderNo 不为 null），还会因为 user 字段上的 @Valid 注解，递归验证 User 对象内部的 username 和 email 字段。这就是级联验证的核心价值。

没有 @Valid 注解时，Validator 只会验证当前对象的直接约束，不会深入嵌套对象的内部。

使用场景

1. 在 Controller 方法参数上使用

Spring MVC 在处理 @RequestBody、@RequestPart 等参数绑定时，可以结合 @Valid 注解自动触发参数校验。例如：

@PostMapping("/orders")
public ResponseEntity<?> createOrder(@Valid @RequestBody Order order) {
    // 如果 order 校验失败，会抛出 MethodArgumentNotValidException
}

此时 Spring 会调用 Hibernate Validator（或其他 Provider）对 order 对象执行校验，并将校验结果封装在 BindingResult 或直接抛出异常。

2. 在 JPA/Hibernate 实体类上

在 JPA 实体类的字段上使用 @Valid 可以级联验证关联实体。例如：

@Entity
public class Parent {
    @OneToMany
    @Valid // 验证 cascade 的 Child 实体
    private List<Child> children;
}

当 EntityManager.persist() 或 Validator.validate() 触发验证时，会级联验证 Child 集合中的每一个元素。

3. 在自定义验证器中使用

当编写自定义的类级别验证器时，也可能会用到 @Valid 来级联验证内部属性。

局限性

@Valid 作为 Bean Validation 规范的核心注解，功能上只专注于级联验证，它本身不支持分组验证（group validation）。虽然我们可以通过 Validator.validate(Object, Class<?>...) 传入分组类，但是 @Valid 注解并没有提供指定分组的属性，因此在声明式使用（如 @Valid 标注在方法参数上）时，无法直接指定使用哪个分组。

这就引出了 Spring 的 @Validated 注解。

@Validated 注解详解

注解定义与来源

@Validated 是 Spring 框架提供的注解，定义在 org.springframework.validation.annotation 包中。它是对标准 @Valid 的补充扩展，专门用于适配 Spring 的验证体系。

package org.springframework.validation.annotation;

@Target({TYPE, METHOD, PARAMETER})
@Retention(RUNTIME)
@Documented
public @interface Validated {
    Class<?>[] value() default {};
}

可以看到，@Validated 可以标注在类型（类/接口）、方法、参数上。它有一个 value 属性，用于指定验证分组（group）。

核心功能：分组验证与 Spring 整合

1. 分组验证（Group Validation）

分组验证是 Bean Validation 2.0+ 提供的特性，允许为同一套实体定义不同的校验规则集合。例如，在'新增'场景下，ID 字段可以为空；在'更新'场景下，ID 字段必须非空。我们可以通过 groups 属性为约束指定分组，然后在校验时传入特定的分组类。

public interface CreateGroup {}
public interface UpdateGroup {}

public class User {
    @Null(groups = CreateGroup.class)
    @NotNull(groups = UpdateGroup.class)
    private Long id;
    
    @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
    private String name;
}

标准 Bean Validation 中，分组校验需要通过编程式 API 传入分组类：validator.validate(user, CreateGroup.class)。但是 @Valid 注解无法声明分组，导致在 Controller 方法参数上无法指定分组。@Validated 恰好弥补了这个缺口：在 Spring 环境中，使用 @Validated 标注在 Controller 方法参数或类上，并通过 value 属性指定分组，即可实现分组校验。

@PostMapping("/users")
public ResponseEntity<?> createUser(@Validated(CreateGroup.class) @RequestBody User user) {
    // 仅校验 CreateGroup 分组的约束
}

2. 类级别的方法验证

Spring 还支持对 Bean 的方法进行参数和返回值验证，这需要满足两个条件：

• 在 Bean 类上标注 @Validated（可指定分组）。
• 在方法参数或返回值上标注 @Valid 或其他约束注解（如 @NotNull）。

然后通过 Spring AOP 拦截方法调用，在方法执行前验证参数，执行后验证返回值。

@Service
@Validated
public class UserService {
    public void createUser(@Valid @NotNull(groups = CreateGroup.class) User user) {
        // 方法执行前会验证 user 不为 null，并触发 @Valid 级联验证
    }
}

这种功能是 @Valid 单独无法实现的。

3. Spring 环境无缝集成

@Validated 是 Spring 自己的注解，因此在 Spring 的各种组件（Controller、Service、Repository）中使用，可以获得更好的框架集成体验。例如，Spring MVC 在处理 @Validated 方法参数时，会使用 Spring 定制的 DataBinder 和 ValidatorAdapter，与 @Valid 的处理路径基本一致，但额外支持分组。

使用场景

1. Controller 方法参数分组验证

这是最常见的使用场景，当同一个 DTO（数据传输对象）在不同接口中有不同的验证规则时，通过 @Validated 指定分组，避免为每个场景创建独立的 DTO 类。

2. Service 层方法参数验证

通过在 Service 实现类上标注 @Validated，并在方法参数上使用 @Valid 或约束注解，可以前置校验业务方法的入参，确保进入核心业务逻辑的数据是合法的。

3. 表单/命令对象验证

在 Spring MVC 中，使用 @ModelAttribute 绑定表单对象时，同样可以在参数上使用 @Validated 触发分组验证。

局限性

• @Validated 是 Spring 框架特有的，如果项目脱离 Spring 环境（纯 Java EE 或 Jakarta EE 应用），则无法使用。
• @Validated 不能直接用于嵌套属性的级联验证标记（例如，在父对象的字段上标注 @Validated 并不会递归验证子对象），此时仍然需要依赖 @Valid。

@Valid 与 @Validated 详细对比

为了清晰掌握两者的异同，下面从多个维度进行对照分析。

核心结论：

• 如果你需要分组验证，必须使用 @Validated。
• 如果你需要级联验证嵌套对象，必须使用 @Valid。
• 两者可以同时使用，例如 @Validated 标注在 Controller 方法参数上，而参数对象内部的字段用 @Valid 标记嵌套验证。

分组验证深度解析

分组的作用与定义

分组验证允许将验证规则划分到不同的逻辑组中。这在同一实体在不同操作场景下约束不同时非常有用。例如：

• 新增（Create）：ID 必须为 null（自动生成），名称不能为空。
• 更新（Update）：ID 必须非 null，名称不能为空。
• 删除（Delete）：只需要验证 ID 非空。

定义分组很简单，只需创建空接口（或类）作为组标识：

public interface Create {}
public interface Update {}
public interface Delete {}

然后在约束注解中使用 groups 属性指定所属组：

public class User {
    @Null(groups = Create.class)
    @NotNull(groups = Update.class)
    private Long id;
    
    @NotBlank(groups = {Create.class, Update.class})
    private String username;
    
    @Email(groups = Create.class) // 新增时验证邮箱格式，更新时不验证
    private String email;
}

如果某个约束没有显式指定 groups，则属于默认组 javax.validation.groups.Default。默认组通常包含了所有未分组的约束。

@Validated 分组验证机制

在 Spring MVC 中，使用 @Validated 注解并传入分组类，即可在校验时仅验证指定组（以及默认组？）——需要特别注意：当指定分组时，默认组（Default）不会被包含在内，除非显式指定。这一点容易踩坑。

@PostMapping("/users")
public ResponseEntity<?> createUser(@Validated(Create.class) @RequestBody User user) {
    // 只会验证属于 Create 组的约束，以及级联对象中属于 Create 组的约束
    // 未指定组的约束（即 Default 组）不会被验证！
}

如果想要同时验证默认组和特定组，可以传入组数组：

@Validated({Create.class, Default.class})

@Valid 与分组的结合方式

@Valid 本身不支持分组，但在 Spring 环境中，可以通过以下两种方式变相实现分组验证：

(1) 在 Controller 参数上使用 @Validated 代替 @Valid，这是推荐做法。

(2) 在 Service 方法验证时：类上 @Validated 指定分组，方法参数 @Valid 触发校验，此时验证的分组是类上 @Validated 指定的分组。

@Service
@Validated(Create.class)
public class UserService {
    public void createUser(@Valid User user) {
        // 此处校验只会应用 Create 组
    }
}

分组继承与组序列

分组支持继承，例如 Create extends Default 可以将默认组的约束包含在内。同时也支持 @GroupSequence 定义组的先后顺序，按顺序验证，一旦前面组有失败，后续组不再验证。这些高级特性在复杂的验证场景中非常实用。

嵌套验证深度解析

嵌套验证的需求

实际业务对象往往是多层嵌套结构，例如：

public class Order {
    @NotNull
    private Long orderId;
    
    @Valid // 级联验证收货地址
    private Address shippingAddress;
    
    @Valid // 级联验证订单项列表
    private List<OrderItem> items;
}

public class Address {
    @NotBlank
    private String receiver;
    
    @NotBlank
    private String phone;
}

如果不加 @Valid，即使 Address 内部的字段有约束注解，Validator 也不会自动校验它们。嵌套验证必须显式使用 @Valid。

@Valid 是嵌套验证的唯一标准方式

无论是标准 Bean Validation，还是 Spring 环境，触发嵌套验证的唯一方式就是在持有嵌套对象的字段或方法参数上标记 @Valid。

注意：@Validated 不能替代 @Valid 来触发嵌套验证。例如：

public class Order {
    @Validated // ❌ 错误用法，不会触发 Address 内部的验证
    private Address shippingAddress;
}

这种写法既不符合规范，也不会被任何验证框架识别。因此嵌套验证必须使用 @Valid。

容器元素的验证

Bean Validation 2.0 开始支持对泛型容器内部元素的验证，如 List<@Email String> emails。但是对于自定义对象的集合，仍需在容器属性上标注 @Valid 来验证每个元素。

public class Order {
    @Valid
    private List<OrderItem> items; // 每个 OrderItem 对象都会递归验证
}

组合使用 @Validated 与 @Valid

在 Controller 参数中，常常组合使用：

@PostMapping("/orders")
public ResponseEntity<?> createOrder(@Validated(Create.class) @Valid @RequestBody Order order) {
    // 1. 分组：只验证 Create 组
    // 2. 嵌套验证：order 内部的 @Valid 字段会级联验证，且级联验证也遵循 Create 分组（继承自顶层分组）
}

这里同时使用了 @Validated 和 @Valid：前者指定分组，后者触发嵌套验证。二者各司其职，完美协作。

方法级别的参数与返回值验证

Spring 方法验证（Method Validation）原理

Spring Framework 从 4.1 开始支持基于 AOP 的方法验证。其核心是 MethodValidationPostProcessor，它会为标注了 @Validated 的 Spring Bean 创建切面，在方法调用前拦截参数，调用 Validator 进行验证，并在方法返回后验证返回值（如果方法上标注了验证注解）。

启用方法验证需要在配置类中注册 MethodValidationPostProcessor（Spring Boot 自动配置了该处理器，前提是 classpath 中有 Bean Validation 相关实现）。

@Configuration
public class ValidationConfig {
    @Bean
    public MethodValidationPostProcessor methodValidationPostProcessor() {
        return new MethodValidationPostProcessor();
    }
}

方法参数验证

在 Service 层使用：

@Service
@Validated // 启用方法验证
public class PaymentService {
    public void pay(@NotNull @Valid PaymentRequest request) {
        // request 不能为 null，且 request 内部的 @Valid 约束会被验证
    }
    
    @NotNull
    public String generateReceipt(@Size(min = 10) String orderNo) {
        // 方法返回 String 不能为 null，参数 orderNo 长度不能小于 10
        return "RECEIPT-" + orderNo;
    }
}

注意事项：

• 方法参数上的约束注解（如 @NotNull）需要由 Bean Validation 提供，不限于 @Valid。
• 必须使用 Spring AOP 代理，因此方法不能是 private，并且需要通过 Spring 容器获取 Bean 实例（直接 new 不会触发验证）。

分组与方法验证

@Validated 的 value 属性可以指定方法验证所使用的分组：

@Service
@Validated(Update.class)
public class UserService {
    public void updateUser(@Valid User user) {
        // 仅验证 Update 组
    }
}

也可以在方法上单独指定分组（方法上的注解覆盖类级别的分组）：

@Service
@Validated
public class UserService {
    @Validated(Create.class)
    public void createUser(@Valid User user) {
        // 验证 Create 组
    }
    
    @Validated(Update.class)
    public void updateUser(@Valid User user) {
        // 验证 Update 组
    }
}

Controller 方法参数验证的本质

很多人误以为 Controller 方法参数上使用 @Valid 或 @Validated 是'方法验证'的一部分，其实 Controller 中的参数验证是由 Spring MVC 的 HandlerMethodValidationHandler（或 ModelAttributeMethodProcessor）触发的，它并不依赖 AOP，也不依赖 @Validated 类级别标注。因此，Controller 方法参数上的 @Validated 仅用于分组指定，不会自动启用 Service 风格的方法验证。

源码级原理解析

Spring MVC 对 @Valid 和 @Validated 的处理

Spring MVC 处理请求参数绑定时，会调用 HandlerMethodArgumentResolver 来解析方法参数。对于 @RequestBody，使用的是 RequestResponseBodyMethodProcessor；对于 @ModelAttribute，使用的是 ModelAttributeMethodProcessor。这些参数解析器都会检查参数是否标注了 @Valid 或 @Validated，如果是，则在校验时构建相应的验证器。

关键流程如下（以 RequestResponseBodyMethodProcessor 为例）：

1. readWithMessageConverters() 将 HTTP 报文反序列化为参数对象。
2. 调用 validateIfApplicable(WebDataBinder, MethodParameter)。
3. 该方法通过 MethodParameter 获取参数上的注解，如果存在 @Valid 或 @Validated，则调用 validate() 执行验证。
4. 验证委托给 WebDataBinder.validate()，最终调用 Validator 实现（通常为 Spring 的 ValidatorAdapter 包装的 Hibernate Validator）。
5. 如果 @Validated 存在，则将其 value 作为分组传入验证调用；否则使用默认分组。

因此，在 Controller 参数上，@Validated 只是作为 @Valid 的功能增强版——增加了分组支持。

MethodValidationPostProcessor 如何工作

MethodValidationPostProcessor 实现了 BeanPostProcessor，在 Bean 初始化后，为其创建 AOP 代理（使用 DefaultAopProxyFactory）。代理逻辑是：拦截目标方法的调用，提取方法参数上的约束注解（包括 @Valid 和 JSR-380 约束），通过 org.springframework.validation.beanvalidation.SpringValidatorAdapter 执行验证。

如果方法有返回值且返回值上标注了约束注解，也会在方法执行后进行验证，并抛出 ConstraintViolationException。

两种验证路径的区别总结

实际应用场景与代码示例

1. Controller 参数验证（无分组）

@RestController
@RequestMapping("/api/users")
public class UserController {
    @PostMapping
    public Result createUser(@Valid @RequestBody UserDTO userDTO) {
        // 使用默认分组验证
        return Result.success(userService.create(userDTO));
    }
}

2. Controller 参数验证（分组）

@RestController
@RequestMapping("/api/users")
public class UserController {
    @PostMapping
    public Result createUser(@Validated(Create.class) @RequestBody UserDTO userDTO) {
        // 仅验证 Create 分组
    }
    
    @PutMapping("/{id}")
    public Result updateUser(@Validated(Update.class) @RequestBody UserDTO userDTO) {
        // 仅验证 Update 分组
    }
}

3. 嵌套对象验证

public class OrderDTO {
    @NotNull
    private String orderNo;
    
    @Valid
    private CustomerDTO customer;
    
    @Valid
    private List<OrderItemDTO> items;
}

public class CustomerDTO {
    @NotBlank
    private String name;
    
    @Email
    private String email;
}

@PostMapping("/orders")
public Result createOrder(@Valid @RequestBody OrderDTO orderDTO) {
    // 验证 OrderDTO 自身属性 + 级联验证 CustomerDTO 和 OrderItemDTO
}

4. Service 方法验证

@Service
@Validated
public class OrderService {
    public Order createOrder(@Valid @NotNull(groups = Create.class) OrderDTO orderDTO) {
        // 1. orderDTO 不能为 null
        // 2. orderDTO 内部的 @Valid 约束会级联验证
        // 3. 由于类上 @Validated 没有指定分组，因此验证默认组
    }
    
    @Validated(Update.class)
    public Order updateOrder(@Valid OrderDTO orderDTO) {
        // 方法级别分组覆盖类级别，验证 Update 组
    }
    
    @NotNull(message = "生成单号不能为空")
    public String generateOrderNo() {
        return "SN" + System.currentTimeMillis();
    }
}

调用 orderService.createOrder(null) 将抛出 ConstraintViolationException，包含 "不能为 null" 的约束违例。

5. 分组继承与组序列示例

public interface BasicInfo {}
public interface AdvancedInfo extends BasicInfo {}

@GroupSequence({BasicInfo.class, AdvancedInfo.class})
public interface FullValidation {}

public class User {
    @NotBlank(groups = BasicInfo.class)
    private String username;
    
    @Email(groups = AdvancedInfo.class)
    private String email;
}

@PostMapping("/users")
public Result createUser(@Validated(FullValidation.class) @RequestBody User user) {
    // 先验证 BasicInfo 组，全部通过后再验证 AdvancedInfo 组
}

6. Spring Boot 中的自动配置

Spring Boot 2.3+ 默认不再包含 spring-boot-starter-validation 依赖，需要手动引入：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

引入后自动配置了 LocalValidatorFactoryBean、MethodValidationPostProcessor（当存在 @Validated 标注的 Bean 时）等。

常见问题与误区

1. 误区：@Validated 能代替 @Valid 做嵌套验证

错误。嵌套验证必须使用 @Valid，@Validated 没有级联语义。

2. 误区：Controller 参数上同时加 @Validated 和 @Valid 是多余的

不是多余的。如果同时需要分组验证和嵌套验证，必须两个都用：@Validated(Create.class) @Valid。如果只写 @Validated(Create.class) 而没有 @Valid，则嵌套对象内部的约束不会被验证。

3. 误区：@Validated 标注在 Controller 类上可以启用方法参数验证

半对。在 Controller 类上标注 @Validated 不会影响 MVC 参数验证机制，它主要用于支持 Service 风格的方法验证（对 Controller 方法也适用，但通常不推荐，因为 Controller 已经由 MVC 验证覆盖）。但如果你在 Controller 的方法参数上仅使用 @Valid 而没有 @Validated，那么类级别的 @Validated 不会为这个参数添加分组信息。

4. 问题：@Validated 加在 @RequestParam 和 @PathVariable 上为什么不生效？

@RequestParam 和 @PathVariable 是简单类型参数，不能进行对象图验证。想要验证单个参数，可以在 Controller 类上标注 @Validated，然后在方法参数上直接加约束注解（如 @Min、@NotBlank），并配合 Spring 的 @EnableMethodValidation 或自动配置。但这种方式其实走的是方法验证（AOP），不是 MVC 参数验证。示例：

@RestController
@Validated // 启用 Spring AOP 方法验证
public class UserController {
    @GetMapping("/users/{id}")
    public Result getUser(@PathVariable @Min(1) Long id) {
        // id 必须 >=1，否则抛出 ConstraintViolationException
    }
}

但这种方式不推荐，因为 Controller 层更适合用 MVC 验证机制。建议还是通过实体类封装参数或使用自定义验证器。

5. 问题：分组验证时默认组为什么丢失？

如前所述，@Validated 只验证你传入的分组，不会自动包含 Default.class。如需同时验证默认组，需要显式传入 {YourGroup.class, Default.class}。

6. 问题：Spring Data JPA 中 @Valid 在实体类上的作用？

JPA 2.0 支持 Bean Validation 自动校验，可以在 PrePersist、PreUpdate 等生命周期事件中触发验证。实体字段上的 @Valid 会级联验证关联实体。但这与 Spring MVC 或 Spring 容器无关，是 JPA 实现（如 Hibernate）的功能。

性能考虑与最佳实践

性能影响

Bean Validation 的反射和约束验证通常性能开销较小，但在极高并发场景下，频繁创建 Validator 和 ConstraintViolation 对象可能带来压力。建议：

• 缓存 Validator 实例（Spring 默认单例，无需担心）。
• 避免在热点代码中使用复杂的类级别自定义约束。
• 使用 @GroupSequence 尽早失败，避免不必要的验证。

最佳实践总结

1. 明确分工：
   • 级联验证 → @Valid
   • 分组验证 → @Validated
   • Controller 参数验证：@Validated + @Valid（需要分组时）
   • Service 方法验证：类上 @Validated + 参数上 @Valid / 约束注解
2. 优先使用分组 DTO 而非单一实体：如果分组差异过大，建议为每个场景创建独立的 DTO 类，避免分组复杂化。
3. 自定义错误消息：使用国际化资源文件，提供友好的错误提示。
4. 异常处理统一：全局捕获 MethodArgumentNotValidException（Controller 参数验证）和 ConstraintViolationException（Service 方法验证、路径/请求参数验证），统一返回格式。
5. 谨慎使用方法验证：Service 层方法验证会为每个标注 @Validated 的 Bean 创建 AOP 代理，影响启动速度和运行时性能（微乎其微）。但若某个类完全没有约束注解，就不必标注 @Validated。
6. 注意方法可见性：Spring AOP 不能拦截 private 方法，方法验证对 private 方法无效。
7. 测试：针对验证逻辑编写单元测试，确保约束按预期工作。

扩展：自定义约束与组合注解

除了内置约束，可以自定义约束注解，例如 @IdCard、@PhoneNumber，并结合 @Valid 或 @Validated 使用。也可以使用组合注解，将多个常用约束组合成一个。

总结

本文从 Java Web 开发中参数验证的核心痛点出发，深入剖析了 @Valid 与 @Validated 的本质区别、适用场景、内部原理以及常见陷阱。总结关键点如下：

• @Valid 是标准 Bean Validation 注解，唯一使命是触发级联验证，不涉及分组。
• @Validated 是 Spring 注解，提供分组验证和方法级别验证的支持，是对 @Valid 的功能增强。
• 在 Controller 层，如果需要分组验证，必须使用 @Validated；如果需要嵌套验证，必须同时使用 @Valid。
• 在 Service 层，通过 @Validated 类注解启用方法验证，参数上的 @Valid 触发嵌套验证，参数上的约束注解触发单个参数验证。
• 分组验证时，@Validated 指定的分组不会自动包含默认组，需要显式添加 Default.class。
• Spring MVC 参数验证与 Spring AOP 方法验证是两套独立的机制，但底层都依赖于 Bean Validation 实现。

掌握 @Valid 与 @Validated 的精髓，能够让你在构建健壮、灵活的 Java Web 应用时游刃有余。无论是简单的增删改查，还是复杂的业务验证场景，都可以用声明式验证替代冗长的 if-else，让代码更加优雅、安全、易于维护。