Java 元注解

Love The Way You Lie 2024-03-27 02:30 76阅读 0赞

`元注解`是负责`对其它注解进行说明的注解`，自定义注解时可以使用元注解。Java 5 定义了 4 个注解，分别是 `@Documented`、`@Target`、`@Retention` 和 `@Inherited`。Java 8 又增加了 `@Repeatable` 和 `@Native` 两个注解。这些注解都可以在 `java.lang.annotation` 包中找到。下面主要介绍每个元注解的作用及使用。

### @Documented ###

@Documented 是一个标记注解，没有成员变量。用 @Documented 注解修饰的注解类会被 JavaDoc 工具提取成文档。默认情况下，JavaDoc 是不包括注解的，但如果声明注解时指定了 @Documented，就会被 JavaDoc 之类的工具处理，所以注解类型信息就会被包括在生成的帮助文档中。

#### IDEA Documented 文档生成 ####

> Tools -> Generate JavaDoc

![format_png][]

### @Target ###

@Target 注解用来指定一个注解的使用范围，即被 @Target 修饰的注解可以用在什么地方。@Target 注解有一个成员变量（value）用来设置适用目标，value 是 java.lang.annotation.ElementType 枚举类型的数组，下表为 ElementType 常用的枚举常量。

<table> 
 <thead> 
  <tr> 
   <th>类型</th> 
   <th>适用目标</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>TYPE</td> 
   <td>用于类、接口（包括注解类型）或 enum 声明</td> 
  </tr> 
  <tr> 
   <td>FIELD</td> 
   <td>用于成员变量（包括枚举常量）</td> 
  </tr> 
  <tr> 
   <td>METHOD</td> 
   <td>用于方法</td> 
  </tr> 
  <tr> 
   <td>PARAMETER</td> 
   <td>用于方法参数</td> 
  </tr> 
  <tr> 
   <td>CONSTRUCTOR</td> 
   <td>用于构造器</td> 
  </tr> 
  <tr> 
   <td>LOCAL_VARIABLE</td> 
   <td>用于局部变量</td> 
  </tr> 
  <tr> 
   <td>ANNOTATION_TYPE</td> 
   <td>用于注解</td> 
  </tr> 
  <tr> 
   <td>PACKAGE</td> 
   <td>用于包</td> 
  </tr> 
  <tr> 
   <td>TYPE_PARAMETER</td> 
   <td>用来类型参数（JDK 1.8新增）</td> 
  </tr> 
  <tr> 
   <td>TYPE_USE</td> 
   <td>能标注任何类型名称（JDK 1.8新增）</td> 
  </tr> 
 </tbody> 
</table>

### @Retention ###

@Retention 描述注解的生命周期，也就是该注解被保留的时间长短。@Retention 注解中的成员变量（value）用来设置保留策略，value 是 `java.lang.annotation.RetentionPolicy` 枚举类型。

> RetentionPolicy 有 3 个枚举常量，如下所示：

1.  **SOURCE**：在源文件中有效（即源文件保留）；
2.  **CLASS**：在 class 文件中有效（即 class 保留）；
3.  **RUNTIME**：在运行时有效（即运行时保留）；

生命周期大小排序为 `SOURCE < CLASS < RUNTIME`，前者能使用的地方后者一定也能使用。

如果需要在运行时去动态获取注解信息，那只能用 RUNTIME 注解，`如 @Documented 注解`；如果要在编译时进行一些预处理操作，比如生成一些辅助代码，就用 CLASS 注解，`如 @NonNull 注解`；如果只是做一些检查性的操作，则可选用 SOURCE 注解，`如 @Override 和 @SuppressWarnings 注解`。

### @Inherited ###

@Inherited 是一个标记注解，用来指定该注解可以被继承。使用 @Inherited 注解的 Class 类，表示这个注解可以被用于该 Class 类的子类。就是说如果某个类使用了被 @Inherited 修饰的注解，则其子类将自动具有该注解。

#### 示例 ####

> 创建一个自定义注解，代码如下所示：

@Target({ ElementType.TYPE })
    @Inherited
    @Retention(RetentionPolicy.RUNTIME)
    public @interface MyInherited {
    }
    复制代码

> 测试类代码如下：

@MyInherited
    public class TestA {
        public static void main(String[] args) {
            System.out.println(TestA.class.getAnnotation(MyInherited.class));
            System.out.println(TestB.class.getAnnotation(MyInherited.class));
            System.out.println(TestC.class.getAnnotation(MyInherited.class));
        }
    }
    
    class TestB extends TestA {
    }
    
    class TestC extends TestB {
    }
    复制代码

> 运行结果为：

@MyInherited()
    @MyInherited()
    @MyInherited()
    复制代码

### @Repeatable ###

@Repeatable 是 **Java 8 新增**，它允许在相同的程序元素中重复注解，在需要对同一种注解多次使用时，往往需要借助该注解。**Java 8 版本以前**，同一个程序元素前最多只能有一个相同类型的注解，如果需要在同一个元素前使用多个相同类型的注解，则必须使用注解“容器”。

#### 示例 ####

> Java 8 之前的相同类型的注解做法：

public @interface Roles {
        Role[] roles();
    }
    
    public @interface Role {
        String roleName();
    }
    
    public class RoleTest {
        @Roles(roles = {@Role(roleName = "roleA"), @Role(roleName = "roleB")})
        public String doString(){
            return "MingYue Repeatable 测试";
        }
    }
    复制代码

> Java 8 之后增加了重复注解，使用方式如下：

public @interface Roles {
        Role[] value();
    }
    
    @Repeatable(Roles.class)
    public @interface Role {
        String roleName();
    }
    
    public class RoleTest {
        @Role(roleName = "roleA")
        @Role(roleName = "roleB")
        public String doString(){
            return "MingYue Repeatable 测试";
        }
    }
    复制代码

两者不同的地方是，创建重复注解 Role 时加上了 @Repeatable 注解，指向存储注解 Roles，这样在使用时就可以直接重复使用 Role 注解。

### @Native ###

@Native 注解修饰成员变量，则表示这个变量可以被本地代码引用，常常被代码生成工具使用。

作者：九七年生于初夏  
链接：https://juejin.cn/post/7189219351164092471

[format_png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/89bc8bb109a747078c60f2d457920e18.png