Spring Boot数据校验指南：@Valid与Hibernate Validator应用

本文深入剖析了Spring Boot中数据校验的常见陷阱与最佳实践，直击@Valid不生效、嵌套对象漏校验、异常返回500而非400、自定义注解失效、@Email校验宽松等高频痛点，系统梳理了从注解添加（@Valid/@Validated位置与层级）、依赖引入（jakarta.validation-api）、全局异常处理（精准捕获MethodArgumentNotValidException与ConstraintViolationException并统一返回400）、到自定义校验实现（Bean注册、事务规避）和生产级邮箱验证等关键环节，强调校验是环环相扣的工程实践，任何一环疏忽都会导致静默失败或服务端崩溃，帮你避开90%开发者踩过的坑。

Spring Boot里@Valid不生效，大概率是没加@Validated或没触发校验入口

Spring MVC默认不会自动校验控制器参数，光写@Valid没用。必须让校验逻辑被Spring的AOP拦截器捕获，而这个拦截器只认@Validated（或@Valid在特定位置）。常见错误是只在DTO字段上加@NotBlank等注解，却忘了在Controller方法参数前补@Valid，或者根本没给Controller类加@Validated。

• @Valid要放在方法参数前，且该参数类型需有JSR-303注解（如@NotNull）
• 如果校验嵌套对象（比如DTO里有个UserDetail字段），得在那个字段上加@Valid，否则子对象不校验
• Spring Boot 3+ 默认使用Jakarta EE namespace，确保引入的是jakarta.validation:jakarta.validation-api，不是老的javax.validation
• 若用@RequestBody接收JSON，校验由RequestResponseBodyMethodProcessor触发；但@RequestParam或@PathVariable需手动加@Validated类级注解才能生效

字段级校验报错但返回500而不是400，是因为没配全局异常处理器

校验失败时Hibernate Validator抛MethodArgumentNotValidException（@RequestBody）或ConstraintViolationException（@Validated方法参数），Spring Boot默认不捕获，直接500。必须自己写@ControllerAdvice处理。

• 不要只catch Exception，要专门处理MethodArgumentNotValidException和ConstraintViolationException
• MethodArgumentNotValidException里用getBindingResult().getAllErrors()取错误；ConstraintViolationException则从getConstraintViolations()里遍历
• 返回的HTTP状态码必须是400 BAD_REQUEST，否则前端难区分业务失败和参数错误
• 避免把原始message直接返回（含占位符如{min}），要用messageSource解析或自定义格式化

自定义校验注解写完不触发，关键是没实现ConstraintValidator接口或没注册Bean

自定义注解（比如@Phone）只是个标记，真正干活的是对应的ConstraintValidator实现类。Spring不会自动扫描它，必须声明为Bean，且泛型类型要匹配。

• 实现类必须继承ConstraintValidator，比如ConstraintValidator
• 类上加@Component，否则Spring找不到这个校验器
• initialize()方法可空着，但isValid()里别抛异常——校验失败就返回false，异常会导致整个请求崩溃
• 如果校验逻辑涉及数据库（如查手机号是否已存在），注意事务边界：ConstraintValidator不在Service事务内，需手动用TransactionTemplate或把校验逻辑移到Service层

用@Email校验邮箱却放过中文域名，是因为默认正则太宽松

@Email的默认正则只检查基础格式（a@b.c），不验证DNS、MX记录，也不拦中文域名（如张三@例子.中国）。生产环境若需严格控制，不能依赖它。

• 别改@Email的regexp属性——它只作用于本地校验，不影响Hibernate Validator内置逻辑
• 更可靠的做法是写自定义注解，用java.net.IDN转义后再校验ASCII域名，或调用InternetAddress尝试解析
• 如果项目已用Lombok，注意@Data生成的toString()可能暴露敏感字段，而@Email校验失败时日志会打印整个DTO，需确认日志脱敏配置
• 前端也做了邮箱校验？别信。前后端正则不一致是常态，服务端必须独立校验

以上就是《Spring Boot数据校验指南：@Valid与Hibernate Validator应用》的详细内容，更多关于的资料请关注golang学习网公众号！