1. 四大元注解原理
1.1 Retention（保留策略）原理
在 Java 注解体系中，Retention 用于指定注解在什么时候可用，它决定了注解信息会不会被编译、打包以及运行时可见。常见取值包括 SOURCE、CLASS、RUNTIME，其中 RUNTIME 是可以通过反射在运行期读取的关键选项。理解它对于实现“Java注解详解”的核心原理至关重要。
实际应用中，若你需要在运行时通过反射读取注解，则必须将注解的保留期设为 RetentionPolicy.RUNTIME；若只在编译时或字节码阶段使用，则可以选择 SOURCE 或 CLASS。这一点对于设计灵活的注解驱动逻辑具有直接影响。
import java.lang.annotation.*;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface MethodInfo {String value() default "";
}
1.2 Target（可应用的位置）原理
Target 定义了注解可以应用的程序元素类型，例如类型、方法、字段等。通过限定注解的可用位置，可以在编译阶段提前捕获错误并提升代码的稳定性。理解这个原理有助于设计更具可读性和约束性的注解。
常见的目标类型包括 TYPE、METHOD、FIELD、CONSTRUCTOR 等。若注解不具备合适的目标类型，编译器将报错，避免了在不适用的位置误用注解的情况。
import java.lang.annotation.*;@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface MethodOnly {String description() default "";
}
1.3 Documented（文档化）原理
Documented 标记的注解会出现在 Javadoc 等文档中，帮助 API 使用者理解注解的含义与作用。若缺少该元注解，相关信息在官方文档或 IDE 的帮助中可能不易察觉。
从文档维护角度看，Documented 可以提升注解在公开 API 中的可见性，尤其是在团队协作和对外接口治理时具有积极作用。
import java.lang.annotation.*;@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface EntityConfig {String table();String id() default "id";
}
1.4 Inherited（可继承性）原理
Inherited 仅对类级别的注解有效，子类会继承父类的注解信息。这对于描述类型层级的元信息非常有用，但对方法、字段等成员没有自动继承效果。
在设计一个面向 ORM、REST 控制器等框架的注解时，若希望子类自动获得父类的注解以实现一致的行为，Inherited 可以作为一个有力的工具，帮助减少重复标注。
import java.lang.annotation.*;@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface RepositoryConfig {String value();
}
2. 四大元注解的用法
2.1 如何在自定义注解中应用元注解
在自定义注解时，Retention、Target、Documented 和 Inherited 共同决定注解的可用性、范围与文档化程度。通过组合使用这些元注解，可以实现对注解在不同维度上的严格控制，确保注解具有预期的行为。
为了实现一个可运行时读取的注解，通常需要在注解定义上同时声明 Retention(RUNTIME)，并给定合适的 Target，如 ElementType.METHOD；若希望注解出现在文档中，应加上 Documented。这也是 Java注解详解的核心实践之一。
import java.lang.annotation.*;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface ActionInfo {String value();
}
2.2 注解成员与默认值的设计要点
注解中的成员可以像方法一样声明，且可以设置默认值。合理设计成员，可以提升注解的表达能力与易用性。使用 默认值 可以让使用方在不显式设置的情况下保持简洁，同时也保留自定义的扩展点。
示例中，成员名称、类型和默认值的组合要与实际使用场景紧密对应，避免引入歧义的取值范围，从而提升代码的可读性和维护性。
import java.lang.annotation.*;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface EntityInfo {String table();String schema() default "public";
}
3. 实战：自定义注解的定义与应用
3.1 自定义注解的定义步骤
实现一个简单的实体映射注解，需要先定义注解的元信息，然后在实体类上进行标注，以实现运行期读取与动态处理。核心步骤包括：定义注解、设置保留策略、限制应用位置，以及在文档化和可继承性的设计上做出权衡。
通过这些步骤，可以将注解作为一个轻量级的元数据载体，驱动框架行为、数据映射以及文档生成等场景，形成可自描述的代码结构。
import java.lang.annotation.*;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface TableMapping {String table();String primaryKey() default "id";
}
3.2，将注解应用到实体并进行简单读取
在实际应用中，可以将注解应用到实体类上，随后通过反射在运行时读取注解信息以完成对象映射、校验或路由决定等逻辑。此处演示一个简易的读取流程，体现 Java注解详解 的实战价值。
通过读取注解，我们可以动态地获取数据库表名、主键字段等元信息，从而实现轻量级的 ORM 映射或自动化文档生成。
@TableMapping(table = "user", primaryKey = "user_id")
public class User {private String userId;private String name;
}
import java.lang.reflect.*;public class AnnotationReader {public static void main(String[] args) throws Exception {Class cls = User.class;if (cls.isAnnotationPresent(TableMapping.class)) {TableMapping tm = cls.getAnnotation(TableMapping.class);System.out.println("Table: " + tm.table());System.out.println("Primary Key: " + tm.primaryKey());}// 实例方法上的注解读取示例for (Field f : cls.getDeclaredFields()) {// 逻辑略，演示扩展点}}
}
4. 进阶：运行时读取与注解处理
4.1 运行时读取注解的示例
在运行时通过反射读取注解，是 实战实践 的核心能力之一。此能力使得注解不再只是文档标记，而是可驱动业务逻辑的元数据。
通过对类、方法、字段等进行遍历和检测，可以实现各种自动化行为，如组装对象、校验规则、自动生成 API 文档等，充分体现了 四大元注解原理 在实际场景中的落地效果。
public class ReflectiveUtil {public static void main(String[] args) throws Exception {Class cls = User.class;if (cls.isAnnotationPresent(TableMapping.class)) {TableMapping tm = cls.getAnnotation(TableMapping.class);System.out.println("Read table: " + tm.table());}for (Method m : cls.getDeclaredMethods()) {if (m.isAnnotationPresent(MethodInfo.class)) {MethodInfo mi = m.getAnnotation(MethodInfo.class);System.out.println("Method " + m.getName() + " info: " + mi.value());}}}
}
4.2 简单的注解处理思路与实践
除了直接的反射读取，若要在编译期或构建阶段对注解进行处理，可以设计一个简单的注解处理器思路：扫描类路径上的注解、收集元数据、生成辅助文档或代码。此处给出一个思路框架，便于后续扩展为自定义注解处理器。
在实现中，核心是对注解类型进行枚举、对比目标类型进行过滤，以及对元信息进行聚合与输出，这些步骤都与前述的 Retention、Target、Documented、Inherited 的原理密切相关。
import java.lang.annotation.*;
import java.lang.reflect.*;public class AnnotationProcessorDemo {public static void main(String[] args) throws Exception {for (Class c : new Class[]{User.class}) {if (c.isAnnotationPresent(TableMapping.class)) {TableMapping tm = c.getAnnotation(TableMapping.class);// 处理逻辑，例如生成映射配置System.out.println("Generate config for table: " + tm.table());}}}
}
