元注解的本质是Java为注解定义的元数据规则，用于声明注解的使用位置（@Target）、保留策略（@Retention）、文档可见性（@Documented）和继承性（@Inherited），它不参与业务逻辑，而是向编译器和处理器提供强制契约，确保注解被正确、可预期地使用。

元注解的本质，是 Java 为注解本身定义的“元数据规则”——它不参与业务逻辑，也不被运行时直接处理，而是告诉编译器或处理器：“这个注解该怎么被使用、生效范围多大、保留到哪个阶段”。它的语义核心不在“修饰”，而在“约束与声明”。

元注解不是装饰器，而是契约声明

比如 @Target(ElementType.METHOD) 并非给注解“加个花边”，而是立下契约：该注解只允许写在方法上，若误用在类或字段上，编译器会报错（javac 检查阶段）。这种限制发生在代码编写期，属于编译期强制契约，而非运行时动态行为。

• @Target 声明“能标在哪”——限定适用位置（如 TYPE、FIELD、METHOD 等）
• @Retention 声明“能活多久”——决定注解信息保留在源码（SOURCE）、字节码（CLASS）还是运行时（RUNTIME）
• @Documented 声明“要不要进 API 文档”——影响 Javadoc 是否包含该注解的使用信息
• @Inherited 声明“能不能被子类继承”——仅对类级别注解有效，且仅作用于 extends 关系（不适用于实现接口或组合）

真正起作用的是“注解处理器”对元注解的响应

元注解本身没有行为，但像 javac、APT（Annotation Processing Tool）、Spring 的 BeanFactoryPostProcessor、或自定义的 javax.annotation.processing.Processor，会读取元注解的声明，并据此执行动作。例如：

java-api-doc-generator

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

下载

• 一个 @Retention(RUNTIME) 的注解，才能被 Class.getAnnotation() 反射读取
• 一个 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE}) 的元注解（如 @Target 自身），说明它只能用于修饰类或其它注解——这体现了元注解的“自指性”和层级性

理解关键：分清三个层级的“存在意义”

Java 注解体系天然有三层：

• 第一层（使用者）：程序员写 @Override 或自定义 @Log —— 这是面向问题域的标记
• 第二层（定义者）：用元注解定义 @Log 的行为边界，比如 @Retention(RUNTIME) @Target(METHOD) —— 这是面向工具链的契约
• 第三层（执行者）：框架或处理器根据第二层的声明，决定是否扫描、何时读取、如何响应 —— 这是面向运行环境的实现

所谓“修饰注解”，只是表象；实质是第二层通过元注解，向第三层传递结构化元信息，让整个生态可预期、可验证、可扩展。

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南