@Repeatable注解需配对容器注解才能生效，容器必须声明value()方法返回该注解数组，且@Target与@Retention须完全一致；运行时应通过getAnnotationsByType()获取全部实例，而非getAnnotation()。
Java 8 引入的 @Repeatable 注解，让同一个注解类型可以在同一声明上多次使用，解决了早期版本中必须借助容器注解（如 @Annotations）来包裹多个同类型注解的繁琐问题。它的核心不是语法糖，而是编译器与反射机制协同工作的结果——关键在于“如何定义可重复注解”以及“如何在运行时正确提取全部实例”。
定义可重复注解的两步结构
要让一个注解支持重复使用，必须满足两个硬性条件：
- 目标注解本身需标注
@Repeatable(ContainerAnnotation.class)，其中ContainerAnnotation是它的“容器注解”； - 容器注解必须是单值数组型注解，返回类型为该注解类型的数组，且 value 方法必须存在（也可用其他名称，但需在
@Repeatable中显式指定）。
例如：
@Repeatable(Permissions.class)
public @interface Permission {
String value();
String action() default "read";
}
public @interface Permissions {
Permission[] value();
}
编译器会自动将多个 @Permission 合并进一个 @Permissions 容器中，供反射读取。
立即学习“Java免费学习笔记（深入）”；
运行时获取全部重复注解实例
反射 API 不直接返回重复注解的多个实例，而是返回其容器注解。因此，正确提取方式是：
- 先调用
getAnnotation(ContainerAnnotation.class)获取容器； - 再从容器中取出数组字段（通常是
value()），遍历每个元素； - 若需兼容非重复用法（即只写了一个注解），也建议统一走容器路径，避免逻辑分支。
示例：
Permissions permissions = method.getAnnotation(Permissions.class);
if (permissions != null) {
for (Permission p : permissions.value()) {
System.out.println(p.value() + " → " + p.action());
}
}
常见陷阱与注意事项
实际使用中容易忽略几个细节：
- 容器注解的
@Target和@Retention必须与目标注解保持一致，否则编译报错； - 容器注解不能被直接使用（即不允许手动写
@Permissions({@Permission("a"), @Permission("b")})），它由编译器自动生成； - IDE 或字节码工具可能显示“重复注解已合并”，这是正常行为，不代表丢失数据；
- 若通过 ASM、ByteBuddy 等操作字节码，需注意容器注解在 class 文件中的真实存在形式。
适用场景与设计权衡
可重复注解适合表达“一组同类策略/配置/权限”的语义，比如权限控制、校验规则、路由映射等：
- 比嵌套数组更直观（
@Roles({"admin", "user"})vs@Role("admin") @Role("user")）； - 比自定义集合类更轻量，无需额外实体或 builder；
- 但不适用于需要顺序敏感或带索引操作的场景——注解本身不保证声明顺序（尽管多数 JVM 实现按源码顺序返回）。
若逻辑复杂度上升（如需组合条件、动态生成、依赖注入），建议及时迁移到配置类或注解处理器，而非强行堆叠注解语义。
