为什么 @Valid 不生效？常见拦截链断点在这里
Spring Boot 中 @Valid 看似开箱即用，但实际常因缺少触发点而静默失效。它不会自动在任意方法上起作用，必须落在 Spring MVC 的参数绑定流程里——也就是 @RequestBody 或 @ModelAttribute 标记的入参上。
- Controller 方法参数没加
@RequestBody，只写了@Valid MyDto dto→ 校验完全不触发 - 用了
@Validated但没配分组，而自定义注解指定了groups→ 匹配失败，跳过校验 - 手动 new 对象并调用
validator.validate()，但没设置Configuration或没加载自定义约束校验器 → 报ConstraintDeclarationException
写一个能被 Validator 识别的自定义注解，三步不能少
不是加个 @Target + @Retention 就算完事。JSR-303 要求每个约束注解必须关联一个实现 ConstraintValidator 的校验器类，并通过 @Constraint(validatedBy = ...) 显式声明。
- 注解接口里必须声明
String message() default "...";、Class>[] groups() default {};、Class extends Payload>[] payload() default {}; - 校验器类（如
PhoneValidator）要实现ConstraintValidator<myphone string></myphone>，且泛型第二个参数必须和注解标注的字段类型一致 - 校验器类需被 Spring 扫描到（加
@Component），否则LocalValidatorFactoryBean初始化时找不到实现类，启动报No validator could be found for constraint
@Target({FIELD})
@Retention(RUNTIME)
@Constraint(validatedBy = PhoneValidator.class)
public @interface MyPhone {
String message() default "手机号格式错误";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
嵌套对象校验失效？别忘了 @Valid 要手动加在字段上
Spring 默认只校验 Controller 入参一层，子对象字段即使加了 @NotBlank 也不会递归检查。这不是 bug，是设计如此——避免无意中触发深层级校验带来性能或副作用。
- DTO 内部有
UserProfile profile字段，profile 里有@Email→ 必须在字段上加@Valid，否则 profile 的校验规则被忽略 - 集合类字段如
List<orderitem> items</orderitem>，想校验每个 item，得写成@Valid List<orderitem> items</orderitem> - 如果用了 Lombok 的
@Data，注意它默认不生成toString()或hashCode()可能导致校验器内部反射失败（极少见，但出现时错报IllegalArgumentException: object is not an instance of declaring class）
校验失败时怎么让响应体更可控？别直接依赖全局异常处理器
Spring 默认把 MethodArgumentNotValidException 转成 400 响应，但错误信息结构固定（BindingResult）、字段名裸露、国际化支持弱。真正在意 API 契约时，得自己接管。
立即学习“Java免费学习笔记（深入）”；
- 捕获
MethodArgumentNotValidException后，别直接返回ex.getBindingResult().getAllErrors()，里面混着FieldError和ObjectError，前端解析困难 - 推荐遍历
bindingResult.getFieldErrors()，提取field、defaultMessage，组装为Map<string string></string>或统一错误 VO - 如果 DTO 字段用了
@JsonProperty("user_name")，校验失败仍返回fieldName = "userName"（Java 名），不是 JSON key；需手动映射或改用error.getCode()+ 自定义 message source
