Java注解和注解解析器深耕，架构师必会

什么是元数据(metadata)

元数据由metadata译来，所谓的元数据就是“关于数据的数据”,更通俗的说就是描述数据的数据，对数据及信息资源的描述性信息.比如说一个文本文件,有创建时间,创建人,文件大小等数据,这都可以理解为是元数据.

在java中,元数据以标签的形式存在java代码中,它的存在并不影响程序代码的编译和执行，通常它被用来生成其它的文件或运行时知道被运行代码的描述信息。java当中的javadoc和注解都属于元数据.

什么是注解(Annotation)?

注解是从java 5.0开始加入,可以用于标注包,类,方法,变量等.比如我们常见的@Override,再或者Android源码中的@hide,@systemApi,@privateApi等

对于@Override,多数人往往都是知其然而不知其所以然,今天我就来聊聊Annotation背后的秘密,开始正文.

元注解就是定义注解的注解,是java提供给我们用于定义注解的基本注解.在java.lang.annotation包中我们可以看到目前元注解共有以下几个:

1. @Retention

2. @Target

3. @Inherited

4. @Documented

5. @interface

下面我们将集合@Override注解来解释着5个基本注解的用法.

@interface

@interface是java中用于声明注解类的关键字.使用该注解表示将自动继承java.lang.annotation.Annotation类,该过程交给编译器完成.

因此我们想要定义一个注解只需要如下做即可,以@Override注解为例

public @interface Override { 
} 

需要注意:在定义注解时,不能继承其他注解或接口

@Retention

@Retention:该注解用于定义注解保留策略,即定义的注解类在什么时候存在(源码阶段 or 编译后 or 运行阶段).该注解接受以下几个参数: RetentionPolicy.SOURCE,RetentionPolicy.CLASS,RetentionPolicy.RUNTIME ,其具体使用及含义如下:

来看一下@Override注解的保留策略:

@Retention(RetentionPolicy.SOURCE) 
public @interface Override { 
} 

这表明@Override注解只在源码阶段存在,javac在编译过程中去去掉该注解.

@Target

该注解用于定义注解的作用目标,即注解可以用在什么地方,比如是用于方法上还是用于字段上,该注解接受以下参数:

以@Override为例,不难看出其作用目标为方法:

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

到现在,通过@interface,@Retention,@Target已经可以完整的定义一个注解,来看@Override完整定义:

@Target(ElementType.METHOD) 
@Retention(RetentionPolicy.SOURCE) 
public @interface Override { 
} 

@Inherited

默认情况下,我们自定义的注解用在父类上不会被子类所继承.如果想让子类也继承父类的注解,即注解在子类也生效,需要在自定义注解时设置@Inherited.一般情况下该注解用的比较少.

@Documented

该注解用于描述其它类型的annotation应该被javadoc文档化,出现在api doc中.

比如使用该注解的@Target会出出现在api说明中.

@Documented 
@Retention(RetentionPolicy.RUNTIME) 
@Target(ElementType.ANNOTATION_TYPE) 
public @interface Target { 
 
 
 
 
    ElementType[] value(); 
} 

借助@Interface,@Target,@Retention,@Inherited,@Documented这五个元注解,
我们就可以自定义注解了,其中前三个注解是任何一个注解都必备具备的.

自定义注解

格式:

public @interface 注解名 {定义体} 

定义体就是方法的集合,每个方法实则是声明了一个配置参数.方法的名称作为配置参数的名称,方法的返回值类型就是配置参数的类型.和普通的方法不一样,可以通过default关键字来声明配置参数的默认值.

需要注意:

此处只能使用public或者默认的defalt两个权限修饰符

配置参数的类型只能使用基本类型(byte,boolean,char,short,int,long,float,double)和String,Enum,Class,annotation

对于只含有一个配置参数的注解,参数名建议设置中value,即方法名为value

配置参数一旦设置,其参数值必须有确定的值,要不在使用注解的时候指定,要不在定义注解的时候使用default为其设置默认值,对于非基本类型的参数值来说,其不能为null.

像@Override这样,没有成员定义的注解称之为标记注解.

注解处理器

上面我们已经学会了如何定义注解,要想注解发挥实际作用,需要我们为注解编写相应的注解处理器.根据注解的特性,注解处理器可以分为运行时注解处理和编译时注解处理器.运行时处理器需要借助反射机制实现,而编译时处理器则需要借助APT来实现.

无论是运行时注解处理器还是编译时注解处理器,主要工作都是读取注解及处理特定注解,从这个角度来看注解处理器还是非常容易理解的.

注解处理器是（Annotation Processor）是javac的一个工具，用来在编译时扫描和编译和处理注解（Annotation）。你可以自己定义注解和注解处理器去搞一些事情。一个注解处理器它以Java代码或者（编译过的字节码）作为输入，生成文件（通常是java文件）。这些生成的java文件不能修改，并且会同其手动编写的java代码一样会被javac编译。看到这里加上之前理解，应该明白大概的过程了，就是把标记了注解的类，变量等作为输入内容，经过注解处理器处理，生成想要生成的java代码。

运行时注解处理器（不建议使用）

熟悉java反射机制的同学一定对java.lang.reflect包非常熟悉,该包中的所有api都支持读取运行时Annotation的能力,即属性为@Retention(RetentionPolicy.RUNTIME)的注解.

在java.lang.reflect中的AnnotatedElement接口是所有程序元素的(Class,Method)父接口,我们可以通过反射获取到某个类的AnnotatedElement对象,进而可以通过该对象提供的方法访问Annotation信息,常用的方法如下:

运行时注解处理器的编写本质上就是通过反射获取注解信息，随后进行其他操作。编译一个运行时注解处理器就是这么简单。运行时注解通常多用于参数配置类模块。

编译时注解处理器

不同于运行时注解处理器，编写编译时注解处理器（Annotation Processor Tool）.

APT用于在编译时期扫描和处理注解信息.一个特定的注解处理器可以以java源码文件或编译后的class文件作为输入,然后输出另一些文件,可以是.java文件,也可以是.class文件,但通常我们输出的是.java文件.(注意:并不是对源文件修改).如果输出的是.java文件,这些.java文件回合其他源码文件一起被javac编译.

你可能很纳闷,注解处理器是到底是在什么阶段介入的呢?好吧,其实是在javac开始编译之前,这也就是通常我们为什么愿意输出.java文件的原因.

注解最早是在java 5引入，主要包含apt和com.sum.mirror包中相关mirror api，此时apt和javac是各自独立的。从java 6开始，注解处理器正式标准化，apt工具也被直接集成在javac当中。

我们还是回到如何编写编译时注解处理器这个话题上,编译一个编译时注解处理主要分两步：

1、继承AbstractProcessor，实现自己的注解处理器

2、注册处理器,并打成jar包

首先来看一下一个标准的注解处理器的格式：

public class MyAnnotationProcessor extends AbstractProcessor { 
 
 
    @Override 
    public Set<String> getSupportedAnnotationTypes() { 
        return super.getSupportedAnnotationTypes(); 
    } 
 
 
    @Override 
    public SourceVersion getSupportedSourceVersion() { 
        return super.getSupportedSourceVersion(); 
    } 
 
 
    @Override 
    public synchronized void init(ProcessingEnvironment processingEnv) { 
        super.init(processingEnv); 
    } 
 
 
    @Override 
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { 
        return false; 
    } 
} 

编写一个注解处理器首先要对ProcessingEnvironment和RoundEnvironment非常熟悉。接下来我们一览这两个类的风采.首先来看一下ProcessingEnvironment类：

public interface ProcessingEnvironment { 
 
 
    Map<String,String> getOptions(); 
 
 
    //Messager用来报告错误，警告和其他提示信息 
    Messager getMessager(); 
 
 
    //Filter用来创建新的源文件，class文件以及辅助文件 
    Filer getFiler(); 
 
 
    //Elements中包含用于操作Element的工具方法 
    Elements getElementUtils(); 
 
 
     //Types中包含用于操作TypeMirror的工具方法 
    Types getTypeUtils(); 
 
 
    SourceVersion getSourceVersion(); 
 
 
    Locale getLocale(); 
} 

Element

element表示一个静态的，语言级别的构件。而任何一个结构化文档都可以看作是由不同的element组成的结构体，比如XML，JSON等。

对于java源文件来说， Element代表程序元素：包，类，方法都是一种程序元素 ，他同样是一种结构化文档：

package com.closedevice;             //PackageElement 
public class Main{                  //TypeElement 
    private int x;                  //VariableElement 
    private Main(){                 //ExecuteableElement 
    } 
    private void print(String msg){ //其中的参数部分String msg为TypeElement 
    } 
} 

TypeMirror

这三个类也需要我们重点掌握：

DeclaredType代表声明类型：类类型还是接口类型，当然也包括参数化类型，比如Set<String>，也包括原始类型

TypeElement代表类或接口元素，而DeclaredType代表类类型或接口类型。

TypeMirror代表java语言中的类型.Types包括基本类型，声明类型（类类型和接口类型），数组，类型变量和空类型。也代表通配类型参数，可执行文件的签名和返回类型等。TypeMirror类中最重要的是getKind()方法，该方法返回TypeKind类型，为了方便大家理解，这里附上其源码：

public enum TypeKind { 
    BOOLEAN,BYTE,SHORT,INT,LONG,CHAR,FLOAT,DOUBLE,VOID,NONE,NULL,ARRAY,DECLARED,ERROR,  TYPEVAR,WILDCARD,PACKAGE,EXECUTABLE,OTHER,UNION,INTERSECTION; 
    public boolean isPrimitive() { 
        switch(this) { 
        case BOOLEAN: 
        case BYTE: 
        case SHORT: 
        case INT: 
        case LONG: 
        case CHAR: 
        case FLOAT: 
        case DOUBLE: 
            return true; 
        default: 
            return false; 
        } 
    } 
} 

简单来说，Element代表源代码，TypeElement代表的是源码中的类型元素，比如类。虽然我们可以从TypeElement中获取类名，TypeElement中不包含类本身的信息，比如它的父类，要想获取这信息需要借助TypeMirror，可以通过Element中的asType()获取元素对应的TypeMirror。

然后来看一下RoundEnvironment,这个类比较简单,一笔带过:

public interface RoundEnvironment { 
    boolean processingOver(); 
     //上一轮注解处理器是否产生错误 
    boolean errorRaised(); 
     //返回上一轮注解处理器生成的根元素 
    Set<? extends Element> getRootElements(); 
   //返回包含指定注解类型的元素的集合 
    Set<? extends Element> getElementsAnnotatedWith(TypeElement a); 
    //返回包含指定注解类型的元素的集合 
    Set<? extends Element> getElementsAnnotatedWith(Class<? extends Annotation> a); 
} 

Filer

Filer用于注解处理器中创建新文件，由于Filer用起来实在比较麻烦,后面我们会使用javapoet简化我们的操作.

打包注解处理器的时候需要一个特殊的文件 javax.annotation.processing.Processor 在 META-INF/services 路径下

新建项目必要配置：

//javapoet代码生成框架 
implementation  'com.squareup:javapoet:1.8.0'  
//注解处理器 
implementation 'com.google.auto.service:auto-service:1.0-rc6' 
annotationProcessor  'com.google.auto.service:auto-service:1.0-rc6' 

编译时注解demo示例地址：https://gitee.com/yutg/apt.git

项目结构

－－apt-demo 
－－－－bindview-annotation(Java Library)//注解定义 
－－－－bindview-api(Android Library)//定义SDK接口方法 
－－－－bindview-compiler(Java Library)//注解处理器相关操作及生成java文件 
－－－－app(Android App)