Java 注解

什么是注解

注解(Annotations)是 Java5 开始提供的功能特性，注解的定义和接口有些相似，最直观感觉就是比接口时多一个 @ 符号。

public @interface MyAnnotation {
    String value();
}

通过 "@ + 注解名" 来使用注解。

@MyAnnotation(value = "hahaha")
public class AnnotationUse {
    // ...
}

那么注解有什么用呢? 注解是用来为类、接口、方法和字段等提供元数据信息，这些信息可以被编译器，开发工具和其他程序等识别，能够在编译和运行时访问元数据信息，然后程序根据这些信息来做一些事情。

例如，编译器根据注解来提示错误和警告信息，文档工具可以通过读取注解生成文档，程序运行时读取元数据(配置信息)来执行某些操作等。

换个方式说，注解就是贴在类上的标签。

打个比方，比如我们去超市买面包，如果把自己看做是运行的程序或编译器，把面包看做 Java 类，面包上的标签就相当于注解，标签上有生产日期，保质期，通过这些标签直接从面包上获得了一些信息，通过读取这些信息我们可以做一些选择或行为，买或者不买，或买几个。注解可以这样理解，就是标签。

商品上有多个标签，不同用途。Java 注解也一样，也可以标注多个注解。

定义注解

通过 @interface 来定义注解，注解里包含方法声明，方法可称为注解元素或属性。

public @interface MyAnnotation {
   int id();
   String value();
   // ... 
}

标记注解

标记注解就是没有任何元素的注解类型，称之为标记注解。

public @interface MyAnnotation {
}

单元素注解

具有一个方法元素的注解类型称为单元素注解，单元素注解中唯一元素的名称应该为 value（也可以不为 value, 但 value 在使用时有特殊的约定支持）。

public @interface MyAnnotation {
	String value();
}

单元素注解元素名为 value 时，使用注解时可以省略指定属性名称。

@MyAnnotation("hahaha")
public class AnnotationUse {
	// ...
}

如果不为 value 时，比如为 valuexxx，这时必须指定元素名称。

@MyAnnotation(valuexxx = "hahaha")
public class AnnotationUse {
	// ...
}

注解的元素

注解中定义的元素(方法)不能带参数或抛出(throws)异常，也不能是默认的方法(接口 default 方法)

public @interface MyAnnotation {
    //int id() throws Exception; // 错误的
    //String value(String val);  // 错误的，不能带参数
    //default String description() { // 错误的，不能是默认方法
    //  return "return value";
    //}
}

默认值

注解元素可以通过 default="default value xxx" 来设置默认值，如果指定的默认值类型与元素的类型不一致会导致编译报错。

有默认值的注解元素使用时不设置值时会直接使用默认值，如果是没有默认值的注解元素，使用时必须指定值。

public @interface MyAnnotation {
    // int id() default "666"; // 错误的，默认值与元素类型不一致
    int id();
    String value() default "default value";
}

// **********************

// value 会使用默认值
@MyAnnotation(id = 666)
public class AnnotationUse {
}

// 编译报错，id 没有默认值，必须定义属性 id
@MyAnnotation(value = "hahaha")
public class AnnotationUse {
}

默认值不会被编译到类上的注解中，而是在使用时动态获取的。所以，修改注解元素的默认值，不管使用注解的类没有重新编译，其获得的默认值均已改变。

注解的元素类型

注解中的元素的声明返回类型是有限制的，必须是下列类型之一:

• 八种基本类型
• String
• Class
• enum
• annotation
• 以上类型的一维数组

例如：

public @interface MyAnnotation {
    Class<?> clazz(); 
    Class<? extends List> clazz2(); 
}


// clazz2 元素值受泛型有界通配符约束，只能是 List 的子类
@MyAnnotation(clazz = Object.class, clazz2 = ArrayList.class)
public class AnnotationUse {
    // ...
}

public @interface MyAnnotation {
    String[] arrValue(); 
}

// arrValue 属性是数组，通过 “{}” 来使用，多个值用 ‘,’ 隔开
@MyAnnotation(arrValue = { "value1", "value2" })
public class AnnotationUse {
    // ...
}

如果元素类型不是约定的那几种类型，则会编译错误。

不能使用的元素

每个注解都默认继承 java.lang.annotation.Annotation 接口，自定义的注解不能覆盖Annotation 接口中的方法，否则会编译错误。

Annotation 接口包含如下方法:

public @interface MyAnnotation {
    int hashCode();   // 错误的，不能覆盖 Annotation 接口中的方法
    String toString();// 错误的
}

注解循环引用

注解类型元素不能直接或间接地包含本身类型(不能循环引用)，否则编译错误。

public @interface MyAnnotation2 {
	MyAnnotation myannotation();
}

public @interface MyAnnotation {
    MyAnnotation myannotation();   // 不能使用自身作为元素类型
    MyAnnotation2 myannotation2(); // 也不能间接使用自身作为元素类型
}

元注解

Java 为我们提供了多个元注解(标记其他注解的注解)。如 @Target 用来约束和限定注解在哪些位置使用(如在类、方法、局域变量上使用等)，使用 @Repeatable 来设置在某个位置重复使用，@Inherited 用来标注注解能被其他注解继承，通过 @Retention 指定注解的生命周期等。

元注解详情见下方"Java 的内置注解":

Java内置注解

@Override
用于指定重写超类型中的方法声明。如果加上这个注解的方法不是重写方法，编译器会报告一个错误。

@SuppressWarnings
用来抑制编译器警告。

@Deprecated
用于标注已被弃用的程序元素(如类，接口，构造方法， 方法等等)，当使用不推荐的程序元素时，编译器会发出警告，不建议使用该程序元素。

@SafeVarargs
1.7 版本
用于方法或构造函数，抑制关于不可具体化变量(vararg)类型的未检查警告。

@FunctionalInterface
1.8 版本
用于指定接口为函数接口，函数接口只能有一个抽象方法，如果不符合函数式接口定义编译器将报错。函数接口可以使用 lambda 表达式。

@Target
用来约束注解的使用范围。

@Retention
用来指定注解的生命周期，分别为 SOURCE, CLASS(没该注解时默认为CLASS), RUNTIME。

@Inherited
用于指定注解是否可以被继承，即允许子类继承父类的注解。

@Repeatable
1.8 版本
指定注解可以重复使用 。

@Documented
它的作用是将被修饰的注解生成到 javadoc 中去。

其中 @Retention，@Target，@Inherited，@Repeatable，@Documented 等是元注解，在定义注解时会用到他们，下面详细了解一下元注解：

@Retention

用来指定注解的生命周期。使注解保留到源码、字节码还是运行时。

@Retention 注解有一个 RetentionPolicy 类型的 value 属性。

// ...
public @interface Retention {
    RetentionPolicy value();
}

RetentionPolicy 为一个枚举类型。

public enum RetentionPolicy {
    /**
     * 注解只会在源码中，编译时类上的注解会被编译器丢弃。
     */
    SOURCE,
    /**
     * 编译器把注解记录在 class 文件中，但是在运行时不需要由 VM 保留。
     * 如不指定 @Retention 时，值默认为 CLASS。
     */
    CLASS,
    /**
     * 编译器把注解记录在 class 文件中，并在运行时 VM 会保留，
     * 因此可以通过 Java 反射来读取注解信息。
     */
    RUNTIME
}

所以三种生命周期长短顺序为 SOURCE < CLASS < RUNTIME 。

完整代码示例请前往 Github 查看: https://github.com/newobjectcc/code-example/tree/master/basic/annotation/AnnotaionDemo/src/retention

@Target

该元注解用来约束注解使用范围。@Target 注解只有一个 ElementType[] 类型的 value 属性。

// ...
public @interface Target {
    ElementType[] value();
}

@Target 注解相同的枚举值在 value 属性上只能出现一次，否则会编译时报错。

如果声明的注解上没有 @Target，那么适用于除类型参数声明外的所有情况下。

其中 ElementType 是一个枚举类型：

public enum ElementType {
    // 用于类, 接口 ,注解, 枚举类型
    TYPE, 
    // 用于域,包括枚举常量
    FIELD, 
    // 用于方法，包括注解类型的元素
    METHOD,
    // 用于形参声明
     PARAMETER, 
    // 可用于构造函数
    CONSTRUCTOR,
    // 用于局部变量声明，包括for语句的循环变量和try-with-resources语句的资源变量
    LOCAL_VARIABLE,
    // 用于其他注解上
    ANNOTATION_TYPE,
    // 用于包声明
    PACKAGE, 
    // 用于泛型类、接口、方法和构造函数的type参数声明，从JDK8开始
    TYPE_PARAMETER,
    /** 标注使用类型，从JDK8开始
     * https://docs.oracle.com/javase/specs/jls/se12/html/jls-4.html#jls-4.11
     */
    TYPE_USE,
    // 用于模块, 从JDK9开始 
    MODULE
}

完整代码示例请前往 Github 查看: https://github.com/newobjectcc/code-example/tree/master/basic/annotation/AnnotaionDemo/src/target

@Inherited

通过 @Inherited 修饰的注解用在某个类上后，这个注解能被这个类的子类继承。

但接口的实现类不能继承接口上 @Inherited 修饰的注解，以及类的方法并不从它所重载的方法继承注解（如果是继承父类中的方法，方法上的注解不管是否用 @Inherited 修饰的，注解随着方法一起被继承下来的）。

完整代码示例请前往 Github 查看: https://github.com/newobjectcc/code-example/tree/master/basic/annotation/AnnotaionDemo/src/inherited

@Repeatable

被该元注解修饰的注解在同一位置是可重复使用的，从 Java8 版本开始支持。

Java8 之前注解是不能像如下这样重复使用的。

@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {
	String value();
}

@MyAnnotation ("A")
@MyAnnotation ("B") // 此时重复使用会编译错误
public class AnnotationUse {	
}

Java8 后开始支持重复使用，需要用 @Repeatable 来修饰注解。

// 使用 @Repeatable 声明为可重复且指定一个容器
@Repeatable(MyAnnotations.class) 
@Retention(value = RetentionPolicy.RUNTIME)
public @interface MyAnnotation {
    String value();
}

// 注解容器
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotations {
    MyAnnotation [] value();    
}

@MyAnnotation ("A")
@MyAnnotation ("B") // 此时可以重复使用了
public class AnnotationUse {    
}

如果对 AnnotationUse.class 反编译后发现，重复注解其实被隐式转换成：

所以 @Repeatable 才需要你指定一个注解容器，用来“存放”声明的注解，注解的容器中要定义一个要和存放类型一致的属性名为 value 的数组。

@MyAnnotation 是我们定义的一个可重复注解，@MyAnnotations 是为这个注解定义的一个注解容器，那么在这两个注解上的元注解有一些需要注意的地方：

对于 @Retention：
注解容器上 @Retention 设置的生命周期至少要长于注解的生命周期。

对于 @Inherited:
如果注解为可继承的，那么注解容器也得声明为可继承的。反之，注解容器声明为可继承的，并不要求注解声明为可继承的。

对于 @Target:
如果注解上没有 @Target 元注解且注解容器也没有 @Target 元注解，则注解可以用任何支持该注解的元素上。
如果注解上没有 @Target 元注解，但注解容器有 @Target 元注解，则注解只能在注解容器支持的元素上使用。
如果注解上有 @Target 元注解，那么注解容器上的 @Target 值必须与注解上的@Target 种类值相同或为他的子集。但注解只能在注解容器支持的元素上使用。

如果没什么特殊要求，以上的最好都保持一致。

完整代码示例请前往 Github 查看: https://github.com/newobjectcc/code-example/tree/master/basic/annotation/AnnotaionDemo/src/repeatable

@Documented

被 @Documented 修饰的注解会被 javadoc 工具记录到文档中，默认情况下 javadoc 是不会将注解生成到类的文档上。

@Documented
public @interface MyAnnotation {}

public @interface MyAnnotation2 {}

@MyAnnotation
@MyAnnotation2
public class AnnotationUse {}

通过 javadoc 生成文档。

G:>javadoc -d doc AnnotationUse.java MyAnnotation.java MyAnnotation2.java

所以，添加 @Documented 元注解的 @MyAnnotation 注解出现在了 AnnotationUse 上，而没有添加 @Documented 的 @MyAnnotation2 没有出现，@Documented 起到了该作用。

注解的面纱

注解是一种特殊的接口类型，通过关键字 interface 前面加 @ 符号来声明注解，其实 @ 符号和关键字 interface是不同的标记，他们之间可以有空格的，但不建议这样做。

public @  interface MyAnnotation {
}

每个注解类型都默认继承 java.lang.annotation.Annotation 接口。

我们通过反编译一探究竟，对如下注解编译后的 .class 进行反编译。

public @interface MyAnnotation {
}

反编译结果：

由反编译结果可以看的出来，注解确实是继承 Annotation 接口。

既然是这样，我能否直接定义一个接口然后在继承 Annotation 接口呢。

public interface MyAnnotation3 extends Annotation{
}

然后把它当做注解来用，就像这样：

@MyAnnotation3
public class AnnotationUse {
}

当然是不可以的，编译失败。

提示 MyAnnotation3 不是注解类型，我们再次通过反编译 .class 字节码来对比一下。

MyAnnotation3.class 和 MyAnnotation.class 的反编译结果非常相似，差别是后者 flags 多出一个 ACC_ANNOTATION 标识。

编译器在编译注解类时除了自动继承 Annotation 接口，还会给注解添加访问标志(access flags)ACC_ANNOTATION，标识他是一个注解类型。

注解的本质就是继承 java.lang.annotation.Annotation 接口的特殊接口。

这么看来，那么一个类能不能 implements 一个注解呢，试了下是可以的，比如这样：

public @interface MyAnnotation {
	String value();
 }
 
public class Demo4 implements MyAnnotation{
	@Override
	public String value() {
		return "hello world";
	}
 
    public static void main(String[] args) {
		System.out.println(new Demo4().value());
	}
	// ... 
}

当然这么做没什么意义，但也间接的从另一角度说明注解和接口是近亲关系。

注解的解析

类添加注解目的是提供元数据信息给编译器，开发工具，程序员等使用，这时就需要提取注解的信息（没有被任何处理和解析的注解就是代码垃圾），这时涉及到了注解的生命周期问题，@Retention 元注解可以设置三种生命周期 SOURCE，CLASS，RUNTIME。

在运行时只能读取生命周期为 RUNTIME 的注解，通过反射技术来对注解进行读取和解析。

生命周期为 SOURCE 和 CLASS 的注解信息在运行时是读取不到的，这时在编译期间通过定义注解处理器（Annotation Processor）来对注解进行处理和解析，主要是用来实现检查性操作或生成某些辅助代码或文件。

运行时注解解析

运行时使用反射获取注解信息，反射相关类都各自实现了java.lang.reflect.AnnotatedElement 接口，该接口定义了获取注解信息相关方法。

你可以通过这些方法访问具有运行时生命周期的注解。

以获取类上注解为例：

@MyAnnotation("类 AnnotationUse 上注解")
public class AnnotationParse<@MyAnnotation T> {
    // ...
    public static void main(String[] args) {
          // ① 
          // System.getProperties().put("sun.misc.ProxyGenerator.saveGeneratedFiles", "true");

          MyAnnotation annotation = AnnotationParse.class.getAnnotation(MyAnnotation.class);
          // 输出结果为：类 AnnotationUse 上注解
          System.out.println(annotation.value());
          
         // 输出结果为：com.sun.proxy.$Proxy1
         // $Proxy1 是个代理类，这个 annotation 对象就是通过 JDK 代理生成的 @MyAnnotation(本质为接口)的一个代理类的对象
         // 想查看 class 字节码文件，可以设置一下系统属性将内存中的 class 字节码文件保存在本地，参考 ① 。
         System.out.println(annotation.getClass().getName());  
    }
}

完整代码示例请前往 Github 查看: https://github.com/newobjectcc/code-example/tree/master/basic/annotation/AnnotationParse/src/reflect

编译期注解解析

在 JDK5 中提供了 APT(Annotation Processing Tool) 工具来进行编译期的注解处理，它是 Oracle 提供的私有实现（包名都是 com.sun.mirror 开头的）。到 JDK6 时对注解处理器进行了规范化，提供了可插式注释处理 API(Pluggable Annotation Processing API)，并增强了 javac 编译器API来使用注解处理器。JDK7 时 APT 功能已经被标准化的注解处理器取代，运行 APT 工具会打印一个警告，提示它将在下一个主要版本中被删除。JDK8 时已经移除了 APT 工具。

定义可插式注释处理器通过继承 javax.annotation.processing.AbstractProcessor 类实现 process(...) 抽象方法,然后结合 javac 编译器来使用(编译器内部会调用注解处理器)。

例如定义一个简单的检查方法命名的注解处理器：

完整代码示例请前往 Github 查看: https://github.com/newobjectcc/code-example/tree/master/basic/annotation/AnnotationProcessor

使用注解处理器

1. 通过 javac -processor <class> 在编译时指定调用的注解处理器。

首先编译注解和注解处理器。

使用注解处理器。

如上，编译时注解处理器执行了，输出了警告信息。

2. 除此之外，当不指定 -processor 参数选项时，会默认通过 SPI(Service Provider Interface) 机制调用注解处理器，前提是得根据约定正确的配置 SPI，需要创建一个 META-INFservices 目录和注解处理器接口名称的文件，文件中指定注解处理器实现。

然后将项目打成 jar 包，然后编译 Annotation.java。

同样，编译时注解处理器执行了且输出了警告信息。

3. 可以把注解处理器集成到开发工具，以 Eclipse 为例：

查看效果：

该例中的注解处理器作用是检测方法名是否符合命名规范。

如果需要编译过程修改 class 内容，比如编译时根据属性自动生成 getter ,setter 方法等，这涉及到修改 AST(抽象语法树)。著名的 Lombok（一个 java 库，只需类上添加注解，编译后就可以自动生成 getter，setter，equals，构造方法以及自动化日志变量等）就是基于注解处理器修改 AST 来实现的。

小结

注解相当于贴在类上的标签，用来为类、接口、方法和字段等提供元数据信息，使编译器、其他工具，程序等读取元数据来执行某些操作。

注解本质是一种特殊的接口类型，注解中的方法声明返回类型是有限制的，必须规定的几种类型之一。

JDK提供了 @Retention，@Target，@Inherited，@Repeatable，@Documented 等元注解。

在运行时通过反射技术解析生命周期为 RUNTIME 的注解，生命周期为 SOURCE 和 CLASS的注解在运行时读取不到的，在编译期间通过定义注解处理器来对注解进行处理和解析。

注解处理器功能非常强大，可以在编译期间修改语法树，改变生成的字节码文件。

---

参考：
https://jcp.org/en/jsr/detail?id=175
https://jcp.org/en/jsr/detail?id=269
https://jcp.org/en/jsr/detail?id=270
https://docs.oracle.com/javase/specs/jls/se12/html/jls-9.html#jls-9.6
https://docs.oracle.com/javase/specs/jvms/se12/html/jvms-4.html#jvms-4.1
https://docs.oracle.com/javase/1.5.0/docs/guide/language/annotations.html
https://docs.oracle.com/javase/1.5.0/docs/guide/apt/index.html
https://www.oracle.com/technetwork/java/javase/compatibility-417013.html
https://www.oracle.com/technetwork/java/javase/8-compatibility-guide-2156366.html
https://stackoverflow.com/questions/17237813/elementtype-local-variable-annotation-type
https://yq.aliyun.com/articles/704117