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

Posted 黄小斜

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Java注解和注解解析器深耕,架构师必会相关的知识,希望对你有一定的参考价值。

本文将介绍学习元数据->元注解->运行时注解->编译时注解处理器->自定义框架Demo

什么是元数据(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;             //PackageElementpublic 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)

以上是关于Java注解和注解解析器深耕,架构师必会的主要内容,如果未能解决你的问题,请参考以下文章

29个阿里架构师必会的核心实战知识点整理清单

29个阿里架构师必会的核心实战知识点整理清单

架构实践架构师必知必会的 5 种业界主流的架构风格

架构实践架构师必知必会的 5 种业界主流的架构风格

Spring源码-循环依赖,Java架构师必学

9大架构设计场景,架构师必知必会