反射实现多规则链式校验框架

本文深入剖析了基于Java反射构建多规则链式校验框架的核心要点与高频陷阱，揭示了从字段扫描（必须用`getDeclaredFields()`+`setAccessible(true)`）、注解位置（须标注在字段而非getter）、继承递归处理、Kotlin字段名适配，到`groups`/`payload`动态分组、`ConstraintValidator`泛型正确声明、级联校验必需显式`@Valid`标注等关键细节；强调该框架的“链式”本质是依赖注解元数据动态组装规则流，而非硬编码逻辑，但任何一环疏漏——如漏传group、泛型擦除、上下文未提取或级联未开启——都会导致校验静默失效，表面无错实则形同虚设，极具隐蔽性与破坏性。

反射获取字段和注解时，getDeclaredFields() 和 getFields() 别混用

校验框架第一步是扫字段，但很多人一上来就用 getFields()，结果 private 字段全丢了——它只返回 public 成员。必须用 getDeclaredFields()，再手动设 setAccessible(true) 才能读 private 字段值。

常见错误现象：NullPointerException 或校验跳过某些字段，实际是字段根本没被扫描到。

• 所有校验注解（如 @NotNull、@Min）都该加在字段上，不是 getter 方法上，否则反射取不到值
• 如果类有继承，getDeclaredFields() 不会返回父类字段，得递归调用 getSuperclass() 向上遍历
• 注意 Kotlin 编译后字段名可能带 $ 或重命名（如 name → name$delegate），Java 反射直接按源码名取会失败

规则链执行顺序依赖注解的 groups 和 payload，但多数人忽略验证上下文传递

所谓“链式匹配”，不是硬编码 if-else，而是靠注解元信息动态组装规则链。比如 @NotBlank(groups = Create.class) 和 @NotBlank(groups = Update.class) 必须在触发校验时显式传入 group 类型，否则默认不生效。

使用场景：同一对象在创建和更新时校验逻辑不同，靠 group 分离规则，而不是写两套校验器。

• 调用 validator.validate(target, Create.class) 才会命中 Create.class 组的规则；漏传参数等于白标注解
• payload 通常用于携带自定义校验上下文（如租户 ID、业务通道），但标准 Validator 不解析它，得自己在 ConstraintValidator 实现里从 ConstraintValidatorContext 提取
• 多个注解在同一字段上时，执行顺序由 JVM 返回的注解数组顺序决定，不保证声明顺序，别依赖“先写哪个就先校验”

自定义 ConstraintValidator 里拿不到运行时值？检查 initialize() 是否覆盖了泛型参数

写一个 CheckInListValidator 校验字段是否在枚举白名单里，结果 isValid() 里 value 总是 null——大概率是 initialize() 方法签名写成了 initialize(CheckInList constraintAnnotation)，而没继承泛型父类。

正确写法必须显式声明泛型类型，否则运行时擦除导致约束注解实例为空：

public class CheckInListValidator implements ConstraintValidator<CheckInList, String> {
    private String[] allowedValues;

    @Override
    public void initialize(CheckInList constraintAnnotation) {
        this.allowedValues = constraintAnnotation.value(); // 这里才能取到注解属性
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        return value != null && Arrays.asList(allowedValues).contains(value);
    }
}

• 忘写 implements ConstraintValidator 中的泛型，initialize() 参数就是 raw type，反射取不到注解值
• 如果校验逻辑涉及 Spring Bean（如查数据库），不能在 ConstraintValidator 里直接 @Autowired，得通过 ValidationConfiguration 注入或用 ApplicationContext.getBean()
• 性能影响：每次校验都会 new 一个 validator 实例，所以 initialize() 里适合做一次性的配置解析，别放耗时操作

嵌套对象校验失效？@Valid 必须显式标注，且不能只靠级联

用户对象里有个 Address address 字段，Address 类也有 @NotBlank 注解，但改了 address.street 为 null 却没报错——因为没在 address 字段上加 @Valid。

JSR-303 的级联校验不是默认开启的，必须主动标注，而且只对字段/方法有效，对集合元素要配合 @Valid + @Size 等组合使用。

• @Valid 只作用于当前字段，不会自动递归进 List 的每个元素；List 校验需写成 List<@Valid Address>（Java 8+ type annotation）或用 @Valid 配合 @Size 在字段上
• Map 的 value 校验同理，Map 才行；key 不支持 @Valid
• Spring MVC 里 Controller 参数用 @Valid，但嵌套对象仍需字段级 @Valid，两者缺一不可

反射做通用校验，最麻烦的从来不是怎么扫字段，而是怎么让注解元数据、运行时值、上下文环境三者对齐。少设一个 groups、漏标一个 @Valid、或者泛型擦除没处理好，整条链就静默失效——它不会报错，只会假装校验过了。

本篇关于《反射实现多规则链式校验框架》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！