SpringBoot校验：@Valid与HibernateValidator使用

Spring Boot中参数校验看似简单，实则暗藏诸多易踩坑细节：从必须手动引入spring-boot-starter-validation依赖（2.3+已移除默认支持），到@Valid与BindingResult的严格位置绑定；从@Validated支持分组校验而@Valid专注嵌套级联的本质区别，到自定义注解因泛型类型不匹配或Jakarta命名空间迁移导致静默失效；再到复杂场景下嵌套集合的分组传播需结合@ConvertGroup才能精准控制——每一步出错都会让校验形同虚设，而本文直击这些高频失效原因，帮你避开90%的校验陷阱，真正让接口数据安全落地。

Spring Boot里@Valid不生效？先检查是否引入了starter

很多人加了@Valid和@NotNull，接口调用却完全不校验——最常见原因是没引入校验依赖。Spring Boot 2.3+ 默认移除了spring-boot-starter-validation的自动依赖，必须手动加。

• Maven里确认有：org.springframework.bootspring-boot-starter-validation
• Gradle对应：implementation 'org.springframework.boot:spring-boot-starter-validation'
• 没有这个依赖，@Valid只是个空注解，连MethodValidationPostProcessor都不会注册

Controller层校验对象时，@Valid必须写在参数前，且不能漏掉BindingResult

校验失败默认抛MethodArgumentNotValidException，但你想自定义返回格式，就得显式接住错误。关键不是“要不要@Valid”，而是“怎么接住它”。

• @Valid必须直接修饰方法参数，比如：public ResponseEntity create(@Valid @RequestBody UserDTO user, BindingResult result)
• BindingResult必须紧跟@Valid参数之后，顺序错（比如中间插了个@RequestParam）会导致注入失败
• 如果没写BindingResult又没全局异常处理器，请求会直接500，日志里只有ConstraintViolationException或MethodArgumentNotValidException

@Validated和@Valid的区别：分组校验和嵌套校验场景下不能混用

单纯非空校验用@Valid够了，但涉及“新增时校验手机号、编辑时校验ID”这类逻辑，就得用@Validated配合分组接口。

• @Validated支持分组：@Validated(User.Create.class)，而@Valid不支持
• @Valid能用在字段上做嵌套校验（比如User类里有个@Valid Address address），@Validated不行
• Controller方法参数只能用@Validated或@Valid之一，同时写两个不会叠加生效，后者会被忽略

自定义校验注解失效？注意ConstraintValidator的泛型类型必须严格匹配

写了个@Phone注解，实现ConstraintValidator，但校验始终跳过——大概率是泛型声明和字段类型对不上。

• 如果字段是private Long phone，ConstraintValidator得写成ConstraintValidator，不能写String
• 自定义注解类上必须有@Constraint(validatedBy = PhoneValidator.class)
• Spring Boot 3+ 使用Jakarta EE命名空间，注解包名要是jakarta.validation.constraints，旧的javax.*会静默失效

复杂点在于嵌套对象的级联校验和分组传播——比如@Valid List里的Item想用不同分组，光靠@Validated搞不定，得用@Validated({Default.class, Item.Create.class})再配合@ConvertGroup，这个细节多数人第一次踩坑时根本想不到。

到这里，我们也就讲完了《SpringBoot校验：@Valid与HibernateValidator使用》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！