元注解不是“给代码加标签”的工具，而是定义注解行为规则的语言契约。它的设计核心是控制两个关键维度：注解能用在哪儿、能活到什么时候。

@Target：划定注解的“作用疆域”

它用 ElementType 枚举明确限制注解可标注的位置，避免误用导致语义混乱或解析失败。

• ElementType.TYPE：类、接口、枚举、注解本身——适合全局性配置，如 @RestController、@V1SecureApi
• ElementType.METHOD：方法级别——用于行为增强，如 @Transactional、@CheckAuth
• ElementType.PARAMETER：方法参数——常见于框架绑定（如 Spring 的 @RequestParam）
• ElementType.TYPE_USE（Java 8+）：可标注在泛型、数组、强制转换等任意类型使用处，支撑更精细的类型检查

@Retention：决定注解的“生命周期长度”

它通过 RetentionPolicy 枚举声明注解信息在哪个阶段仍有效，直接影响能否被反射读取或参与运行时逻辑。

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• RetentionPolicy.SOURCE：仅存在于源码，编译后即消失——适合编译期校验（@Override、@SuppressWarnings）
• RetentionPolicy.CLASS：保留在 .class 文件中，但运行时不加载——常用于字节码处理工具（如 ASM 增强）
• RetentionPolicy.RUNTIME：完整保留至 JVM 运行期——Spring、MyBatis 等主流框架依赖此策略实现动态行为注入

@Documented 与 @Inherited：扩展注解的“可见性契约”

这两个元注解不改变功能逻辑，而是约定元数据的传播方式。

立即学习“Java免费学习笔记（深入）”；

• @Documented 表示该注解应出现在 Javadoc 中——提升团队协作时的文档自明性，比如自定义的 @ApiNote
• @Inherited 仅对类级注解生效，子类自动继承父类所带的该注解——适用于统一基类策略（如 @SecuredBase），但不传递给方法或字段

@Repeatable：打破“单次使用”限制

默认注解不可重复添加在同一目标上。@Repeatable 允许同一位置多次使用某注解，前提是配套定义一个容器注解。

• 例如：@RolesAllowed("ADMIN") 和 @RolesAllowed("USER") 可同时存在，底层由 @RolesAllowed.List 容器聚合
• 使用时需确保容器注解的 value 属性返回原注解数组，且两者 @Target/@Retention 必须一致