java 8 的 @repeatable 注解需配合容器注解才能生效，因其底层仍遵循单值映射设计，编译器将多个同类型注解自动收拢至容器的 value 数组中；容器必须命名规范、含 permission[] value() 成员、不可标 @repeatable 且 retention 至少为 class。
Java 8 引入了 @Repeatable 注解，让同一个注解可以在同一位置多次使用。但要真正生效，必须配合一个“容器注解”（Container Annotation）——它不是可选的装饰，而是编译器识别重复注解的必要结构。
为什么需要容器注解？
Java 的注解系统底层仍遵循“单值映射”设计：每个注解类型在目标元素上最多存在一个实例。@Repeatable 本质是语法糖，编译器会把多个同类型注解自动“收拢”进容器注解的 value 数组中。没有容器，重复声明会被编译器拒绝或静默忽略。
容器注解必须满足三个硬性条件：
- 名称通常为原注解名 + “s” 或 “Container”（如
@Roles对应@Role） - 必须声明一个名为
value()的数组类型成员，元素类型为被标记为@Repeatable的注解类 - 自身不能标注
@Repeatable，且必须保留RetentionPolicy.SOURCE或CLASS（运行时需反射读取时建议用RUNTIME）
标准写法：两步定义缺一不可
以权限校验场景为例，定义可重复的 @Permission：
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(Permissions.class) // 指向容器
public @interface Permission {
String value() default "";
String action() default "read";
}
对应容器注解：
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Permissions {
Permission[] value(); // 唯一且必需的成员，名称固定为 value，类型为原注解数组
}
之后就能在方法上这样使用：
@Permission("user")
@Permission(value = "admin", action = "delete")
public void updateUser() { ... }
运行时通过 method.getAnnotation(Permissions.class) 获取全部实例，而非逐个调用 getAnnotation(Permission.class)（后者只返回第一个）。
常见陷阱与避坑建议
实际开发中容易踩的坑集中在命名、类型和元注解配置上：
-
容器名不匹配：若容器类名不是编译器预期形式（如误写为
@PermissionList），即使结构正确，@Repeatable也不会生效 -
value 成员缺失或类型错误：比如写成
Permission value();（非数组）或String[] value();，编译直接报错 -
容器注解的 Retention 不足：如果容器用了
@Retention(SOURCE)，而代码在运行时通过反射读取，将始终得到null -
重复注解未被容器包裹：JDK 9+ 支持直接读取重复注解（
getAnnotationsByType），但旧版反射 API 仍依赖容器，兼容性要考虑
运行时如何安全获取所有实例？
推荐统一使用 getAnnotationsByType（JDK 8+），它自动处理重复逻辑，无需关心容器：
Permission[] perms = method.getAnnotationsByType(Permission.class); // 直接拿到全部 @Permission 实例，无论是否显式声明容器
如果需兼容 JDK 7 或明确依赖容器结构，才手动查容器：
Permissions container = method.getAnnotation(Permissions.class);
if (container != null) {
Permission[] perms = container.value();
}
注意：getAnnotation(Permission.class) 永远只返回第一个，切勿用于重复场景。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
