本文介绍如何通过 java 8 的 @repeatable 机制解决 spring boot 自定义校验注解重复声明时的编译错误，使同一字段可同时应用多个带不同参数的约束注解。
本文介绍如何通过 java 8 的 @repeatable 机制解决 spring boot 自定义校验注解重复声明时的编译错误，使同一字段可同时应用多个带不同参数的约束注解。
在 Spring Boot 应用中，当我们需要为同一个字段（或参数）配置多个条件校验逻辑（例如：根据不同的功能开关 FeatureFlag 拦截不同取值），直接重复使用同一自定义约束注解（如 @BlockedWithoutEnabledFeatureFlag）会导致编译报错：“Duplicate annotation”。这是因为 Java 默认不允许对同一元素重复声明相同类型的注解——除非该注解被显式声明为 可重复（repeatable）。
要解决该问题，需按以下三步改造注解设计：
✅ 步骤一：定义容器注解（Container Annotation）
首先创建一个专门用于容纳多个同类型注解的“容器”注解。它必须：
- 使用 @Retention(RUNTIME) 和 @Target（与原注解保持一致，通常为 FIELD 或 PARAMETER）；
- 声明一个名为 value() 的数组属性，类型为原注解类。
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface RepeatableBlockedWithoutEnabledFeatureFlag {
BlockedWithoutEnabledFeatureFlag[] value();
}⚠️ 注意：容器注解的 @Target 必须包含原注解所支持的所有目标类型（如 FIELD 和 PARAMETER），否则运行时反射可能无法正确解析。
✅ 步骤二：标记原注解为可重复
在原有 @BlockedWithoutEnabledFeatureFlag 注解上添加 @Repeatable 元注解，并指向刚定义的容器注解：
@Constraint(validatedBy = BlockedWithoutEnabledFeatureFlagValidator.class)
@Target({FIELD, PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@ReportAsSingleViolation
@Repeatable(RepeatableBlockedWithoutEnabledFeatureFlag.class) // ← 关键改动
public @interface BlockedWithoutEnabledFeatureFlag {
String message() default "{validation.constraints.BlockedWithoutEnabledFeatureFlag.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
FeatureFlag feature();
String[] values() default {};
}✅ 此时，Java 编译器会自动将多个 @BlockedWithoutEnabledFeatureFlag 合并为单个 @RepeatableBlockedWithoutEnabledFeatureFlag 容器实例，Spring Validation 框架亦能正常识别并逐个调用其 ConstraintValidator。
✅ 步骤三：验证器保持不变，但需支持多实例校验
你的 BlockedWithoutEnabledFeatureFlagValidator 实现无需修改逻辑，因为 Spring 会为每个 @BlockedWithoutEnabledFeatureFlag 实例分别调用 initialize() 和 isValid() 方法。即：
✅ 每个注解独立初始化 blocked 列表和 feature；
✅ isValid() 会被多次执行（每次对应一个注解），任一校验失败即整体不通过。
示例字段声明（现在合法）：
@JsonProperty("name")
@BlockedWithoutEnabledFeatureFlag(feature = FeatureFlag.AAA, values = {"aaa", "bbb"})
@BlockedWithoutEnabledFeatureFlag(feature = FeatureFlag.BBB, values = {"ccc", "ddd"})
private String parameter;? 补充说明与最佳实践
- 验证顺序不可控：多个重复注解的校验顺序由 JVM 反射决定，不应依赖执行先后；
- 错误消息聚合：若需统一提示，可在 ConstraintValidatorContext 中禁用默认消息并手动添加多个 ConstraintViolation；
- 兼容性：@Repeatable 自 Java 8 起支持，Spring Boot 2.0+（基于 Hibernate Validator 6.x）完全兼容；
- 命名规范：容器注解名建议体现“Repeatable”语义（如 RepeatableXXX），避免与业务注解混淆。
完成上述改造后，即可安全、清晰地为同一字段配置多组功能开关校验规则，既符合语义表达，又保持代码可读性与可维护性。
