Java 元注解

在本教程中，我们将通过示例介绍 Java 中内置的几个元注解。

Java 元注解是用于注解的注解，用来指示注解类保留策略、应用目标、是否可重复等信息。Java 元注解包括：

• @Retention: 指示注解的保留策略
• @Documented: 指示注解可被 javadoc 工具生成文档
• @Target: 指示可应用注解的目标元素
• @Inherited: 指示注解可以从超类继承到子类
• @Repeatable: 指示注解可重复标注到一个目标元素上

如果您不知道什么是注解，请访问 Java 注解教程。

@Retention

@Retention 注解指示了注解的保留策略。它的语法是：

@Retention(RetentionPolicy)

有 3 种类型的保留策略：

• RetentionPolicy.SOURCE - 注解仅在源级别可用，编译器将文件编译成 class 文件时会忽略。
• RetentionPolicy.CLASS - 该注解被保留到 class 文件，但 JVM 加载 class 文件时会忽略。
• RetentionPolicy.RUNTIME - 该注解被保留到 class 文件， JVM 加载 class 文件时也会加载。

例如，

@Retention(RetentionPolicy.RUNTIME)
public @interface MyCustomAnnotation{ ... }

@Documented

默认情况下，Javadoc 生成工具不生成自定义注解的文档。为了在 Javadoc 文档中包含我们的注解，需要在自定义注解上使用 @Documented 注解。

例如，

@Documented
public @interface MyCustomAnnotation{ ... }

@Target

@Target 注解指示了注解可应用在哪些目标元素上。它的语法是：

@Target(ElementType)

ElementType 可选择包括：

• ElementType.ANNOTATION_TYPE: 注解类型
• ElementType.TYPE: 类
• ElementType.FIELD: 字段
• ElementType.METHOD: 方法
• ElementType.CONSTRUCTOR: 构造函数
• ElementType.PARAMETER: 参数
• ElementType.LOCAL_VARIABLE: 局部变量
• ElementType.PACKAGE: 包

例如，

@Target(ElementType.METHOD)
public @interface MyCustomAnnotation{ ... }

在此示例中，我们将此注解的使用仅限于方法。

! **注意：**如果未定义目标类型，则注解可用于任何元素。

@Inherited

@Inherited 注解指示注解可以从父类/超类继承到子类。默认情况下，注解不会从超类集成到子类。

它的语法是：

@Inherited

例如，

@Inherited
public @interface MyCustomAnnotation { ... }

@MyCustomAnnotation
public class ParentClass{ ... }

public class ChildClass extends ParentClass { ... }

@Repeatable

一个被标记为 @Repeatable 的注解可以多次应用于同一个声明。

@Repeatable(Universities.class)
public @interface University {
  String name();
}

public @interface Universities {
  University[] value();
}

@Repeatable 注解需要个参数来指定多个注解时对应的容器注解。上例中 Universities 就是一个容器注解。

现在， @University 注解可以在同一个声明中多次使用。

@University(name = "TU")
@University(name = "KU")
private String uniName;

当我们没有位注解声明 @Repeatable(Universities.class) 时，就要配合容器注解一起使用，如下所示：

@Universities({
  @University(name = "TU"),
  @University(name = "KU")
})
private String uniName;

可见 @Repeatable 简化了注解的使用，让代码更加简洁。

如果我们需要检索注解数据，就要用到 Java 反射的知识了。为了检索注解值，我们使用反射 API 中定义的 getAnnotationsByType() 或 getAnnotations() 方法。