Java可重复注解需显式定义业务注解与容器注解，二者@Retention、@Target必须一致，容器注解须命名为复数形式、仅含value()数组元素；@Repeatable指向容器类；运行时应使用getAnnotationsByType()获取。
Java 可重复注解不是语法糖，而是一套编译器与反射 API 协同工作的机制。它要求你显式定义两个注解：一个业务注解（如 @Role），一个容器注解（如 @Roles）。关键在于二者必须严格匹配，否则编译失败或运行时取不到数据。
容器注解的命名与结构必须规范
容器注解不是随意起名的“包装类”，它有硬性约束：
- 名称通常为业务注解的复数形式（如
@Role→@Roles），虽非强制，但能降低团队理解成本 - 必须声明
@Retention和@Target，且值要与业务注解完全一致（例如都用ElementType.METHOD和RetentionPolicy.RUNTIME） - 必须仅含一个名为 value 的元素，类型为对应业务注解的数组（如
Role[] value()） - 不能额外添加其他字段，否则编译器无法识别其为合法容器
业务注解必须正确指向容器
@Repeatable 的作用是“声明归属”，不是“自动创建容器”。它的括号里填的是容器注解的 Class 对象，不是业务注解自身：
- ✅ 正确：
@Repeatable(Roles.class)（指向你手动写的@Roles） - ❌ 错误：
@Repeatable(Role.class)或@Repeatable(Roles)（缺少.class，或指错类） - IDE 可能标红但编译通过？说明容器注解缺失、
value字段类型不匹配，或@Target范围没覆盖业务注解位置
运行时获取必须用专用反射方法
容器注解的存在是为了兼容旧反射 API，但开发者应优先使用新接口：
立即学习“Java免费学习笔记（深入）”；
- ✅ 推荐：
method.getAnnotationsByType(Role.class)—— 自动合并所有独立@Role和隐式打包进@Roles的实例 - ⚠️ 可用但不推荐：
method.getAnnotation(Roles.class)—— 需手动调用.value()解包，且单个@Role时返回null - ❌ 失效：
method.getAnnotation(Role.class)—— 永远只返回第一个（如果存在），其余被忽略
常见报错原因与自查清单
编译失败或反射拿不到数据，往往卡在这几个点：
- 容器注解的
@Target没包含业务注解的目标（比如@Role支持METHOD，但@Roles只声明了TYPE） -
value()字段名写成values、list或大小写错误（必须是小写value） - 数组类型写错，如
Role value()（缺[]）或Object[] value()（类型不匹配） - 同时显式写了
@Role和@Roles({@Role})—— 编译器拒绝这种歧义写法
