spring boot自定义校验注解生效需满足三要素：一是注解必须标注@target({field, parameter})和@retention(runtime)，并用@constraint关联校验器；二是校验器需实现constraintvalidator接口，重写isvalid方法；三是controller参数须配合@valid或@validated使用，dto字段直接标注即可。
自定义校验注解要在 Spring Boot 的 Controller 入参和 DTO 上生效，核心是让 Spring 的校验机制（基于 Hibernate Validator）识别并执行你的注解逻辑。关键点有三个：注解定义要规范、校验器实现要正确、使用位置要符合约束条件。
注解定义必须包含 @Constraint 和正确元注解
自定义注解本身只是标记，需通过 @Constraint 关联校验器，并声明作用目标（如 FIELD、PARAMETER）和保留策略（RUNTIME）。否则 Spring 不会扫描或触发校验。
- 必须标注 @Target({FIELD, PARAMETER}) —— FIELD 用于 DTO 字段，PARAMETER 用于 Controller 方法参数（含 @RequestBody、@RequestParam 等）
- 必须标注 @Retention(RetentionPolicy.RUNTIME) —— 运行时保留才能被 Validator 读取
- 必须标注 @Constraint(validatedBy = YourValidator.class) —— 指向具体的校验逻辑实现类
- 建议包含 message()、groups()、payload() 标准属性，保持与内置注解兼容
校验器实现类必须继承 ConstraintValidator
校验逻辑写在 ConstraintValidator
- 重写 isValid(T value, ConstraintValidatorContext context)，返回 true/false 表示是否通过
- 如需自定义错误消息，调用 context.disableDefaultConstraintViolation() + context.buildConstraintViolationWithTemplate(...).addConstraintViolation()
- 不要在 validate 方法里抛异常 —— 这由框架统一处理；校验器只负责“判断”，不负责“报错”
Controller 和 DTO 中的使用方式有区别
DTO 上直接加注解即可触发校验；Controller 方法参数则需配合 @Valid 或 @Validated 才能激活。Spring 不会对所有参数默认校验，必须显式声明。
- DTO 示例：public class UserDTO { @MyCustomValid String username; }
- Controller 参数示例：@PostMapping("/user") public String create(@Valid @RequestBody UserDTO dto) —— @Valid 是关键
- 若用 @RequestParam 或路径变量（@PathVariable），需对整个方法参数加 @Validated（注意：@Valid 对单个基本类型参数无效，@Validated 支持分组校验且更灵活）
- 全局开启校验：确保项目引入 spring-boot-starter-validation（2.3+ 版本需显式添加，因 validation 被移出 starter-web）
常见失效原因和排查建议
注解写了但没生效？大概率卡在这几个环节：
- 忘记在 Controller 参数上加 @Valid 或 @Validated
- 自定义注解未加 @Target(PARAMETER)，导致无法用于方法参数
- 校验器类没有无参构造函数，或未被 Spring 扫描到（确保在 component scan 范围内，或加 @Component）
- DTO 字段类型与校验器泛型不匹配（比如注解标在 String 字段，但校验器声明为 ConstraintValidator
） - 使用了 Lombok 的 @Data/@Setter 但没生成正确的 getter/setter —— 校验依赖反射读值，字段必须可通过标准 JavaBean 方式访问
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
