java--自定义注解（注解在编译时生效）

Posted 2021-03-22 11014p

转：https://www.cnblogs.com/yaoxiaowen/p/6753964.html

若注解在运行时（Runtime）通过反射机制来处理注解，既然是Runtime，那么总会有效率上的损耗，如果我们能够在编译期（Compile time）就能处理注解，那自然更好，而很多框架其实都是在编译期处理注解，比如大名鼎鼎的bufferknife，这个过程并不复杂，只需要我们自定义注解处理器（Annotation Processor）就可以了。（Annotation Processor下文有些地方直接简称处理器，不要理解成cpu那个处理器）。

在Compile time注解就能起作用，这才是真正体现注解价值的地方，不过自定义Compile time的注解处理器也没什么神秘的。注解处理器是编译器（javac）的一个工具，它用来在编译时扫描和处理注解。我们可以自定义一个注解，并编写和注册对应的处理器。在写法上它其实就是我们自定义一个类，该类 extends javax.annotation.processing.AbstractProcessor， AbstractProcessor是一个abstract的基类。它以我们写好的java源码或者编译好的代码做为输入，然后就可以通过处理器代码来实现我们所希望的输出了，比如输出一份新的java代码，此时注解管理器就以递归的形式进行多趟处理，直到把代码（包括你手写的代码，以及注解处理器生成的代码）中所有的注解都被处理完毕。

我们已经写好的代码固然是不能修改了，但是这并不影响通过注解处理器来生成新的代码。还以bufferknife为例，写findViewById实在太无聊了，所以我们就使用了bufferknife的注解方式省略这个过程。

public class TestMainActivity extends BaseActivity {
    @BindView(R.id.mainSwitchGoneBtn)
    Button goneBtn;
    .......
}

但是实际上呢，是bufferknife通过其注解处理器器来生成了相应的代码，它生成的文件是这样的:

public class TestMainActivity_ViewBinding<T extends TestMainActivity> implements Unbinder {
  protected T target;

  @UiThread
  public TestMainActivity_ViewBinding(T target, View source) {
    this.target = target;

    target.goneBtn = Utils.findRequiredViewAsType(source, R.id.mainSwitchGoneBtn, "field \'goneBtn\'", Button.class);
  }
}

所以bufferknife就是通过这种方式来麻烦了自己，方便了我们。

注解处理器是运行在它自己的虚拟机jvm当中的，也就是说，javac启动了一个完整的java虚拟机来运行注解处理器，这点非常重要，因为这说明你编写的注解处理器代码，和你写的其他java代码是没什么区别的。不管是你使用的API，还是设计时的思想，编码习惯，甚至你想使用的其他第三方类库,框架等，都是一样的。

认识处理器

前面就说过，我们自定义的过程，就是extends AbstractProcessor,先来看看这个抽象处理器类。

package com.yaoxiaowen.testprocessor;

import java.util.Set;

import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.ProcessingEnvironment;
import javax.annotation.processing.RoundEnvironment;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.TypeElement;

public class TestProcessor extends AbstractProcessor{
    
    /**
     * 每个注解处理器都必须有一个空的构造方法（父类已经实现了），这个init方法会被构造器调用，
     * 并传入一个 ProcessingEnvironment 参数，该参数提供了很多工具类，
     * 比如 Elements， Filer， Messager， Types
     * @author www.yaoxiaowen.com
     */
    @Override
    public synchronized void init(ProcessingEnvironment env) {
        // TODO Auto-generated method stub
        super.init(env);
    }

    /**
     * 这个方法在父类中是abstract的，所以子类必须实现。
     * 这个方法就是相当于 注解处理器的 入口 main()方法,我们说在编译时，对注解进行的处理，
     * 比如对注解的扫描，评估和处理，以及后续的我们要做的其他操作。（比如生成其他java代码文件），
     * 都是在这里发生的。
     * 
     * 参数RoundEnvironment可以让我们查出包含特定注解的被注解元素。
     * @author www.yaoxiaowen.com
     */
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        // TODO Auto-generated method stub
        return false;
    }

    /**
     * 这个方法虽然在父类当中不是 abstract的，但是我们也必须实现。
     * 因为该方法的作用是指定我们要处理哪些注解的，
     * 比如你想处理注解MyAnnotation,可是该处理器怎么知道你想处理MyAnnotation，而不是OtherAnnotation呢。
     * 所以你要在这里指明，你需要处理的注解的全称。
     * 
     * 返回值是一个字符串的集合，包含着本处理器想要处理的注解类型的合法全称。
     * @author www.yaoxiaowen.com
     */
    @Override
    public Set<String> getSupportedAnnotationTypes() {
        // TODO Auto-generated method stub
        return super.getSupportedAnnotationTypes();
    }

    /**
     * 本方法用来指明你支持的java版本，
     * 不过一般使用 SourceVersion.latestSupported() 就可以了。 
     */
    @Override
    public SourceVersion getSupportedSourceVersion() {
        // TODO Auto-generated method stub
        return super.getSupportedSourceVersion();
    }
}

这几个主要方法，在代码片段的注释已经写的很清楚了。

我们使用TestProcessor.java这个处理器的目的就是分析处理java代码，而代码是遵循一定的结构规范的，代码文件被读取后，各个字符串会被分解成token进行处理，而javac的编译器首先将java代码分解为抽象语法树（AST）。而这个结构，在处理器内部，其实是被表示成这样的：

package com.example;    // PackageElement

public class Foo {        // TypeElement

    private int a;      // VariableElement
    private Foo other;  // VariableElement

    public Foo () {}    // ExecuteableElement

    public void setA (  // ExecuteableElement
        int newA   // TypeElement
    ){}
}

处理器在处理代码时，其实就是对抽象语法树进行遍历操作，分解出每一个的类，方法，属性等，然后再将这些元素的内容进行处理。

而实际上，这些PackageElement，VariableElement等元素模型都是在一个专门的类包中javax.lang.model。javax.lang.model用来为 Java 编程语言建立模型的包的类和层次结构。 此包及其子包的成员适用于语言建模、语言处理任务和 API（包括但并不仅限于注释处理框架）。

继承 AbstractProcessor实现自定义处理器

我们现在通过继承AbstractProcessor来实现一个小demo。
流程和功能如下：我们定义了一个注解SQLString,然后实现注解处理器 DbProcessor。该注解处理器功能很简单，就是生成一个文件，将实现了SQLString的属性元素的相关内容写入到这个文件（比如所在类的名字，属性名，所设置的注解的值）。

我们先自定义一个注解

package com.yaoxiaowen.comp.proce.db;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import javax.lang.model.element.Element;

/**
 * 该注解的 使用范围是 属性(域) 上
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.CLASS)
public @interface SQLString {
    int value() default 0;
    String name() default "";
}

然后再来定义注解处理器

package com.yaoxiaowen.comp.proce.db;

import java.io.File;
import java.io.FileWriter;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import java.util.TreeSet;

import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.Messager;
import javax.annotation.processing.ProcessingEnvironment;
import javax.annotation.processing.RoundEnvironment;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.tools.Diagnostic;

/**
  * @author www.yaoxiaowen.com
  */
public class DbProcessor extends AbstractProcessor{
    private Messager messager;
    
    private int count = 0;
    private int forCount = 0;
    private StringBuilder generateStr = new StringBuilder();
    
    @Override
    public synchronized void init(ProcessingEnvironment env) {
        // TODO Auto-generated method stub
        super.init(env);
        messager = env.getMessager();
        String logStr = "enter init(),  进入 init()";
        printMsg(logStr);
    }

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment env) {
        // TODO Auto-generated method stub
        String logStr = "enter process()， 进入process";
        
    
        //用来 存储 （className, 输出语句） 这种结构 
        Map<String, String> maps = new HashMap<>();
        
        //得到 使用了 SQLString注解的元素
        Set<? extends Element> eleStrSet = env.getElementsAnnotatedWith(SQLString.class);
        
        count++;
        
        for (Element eleStr : eleStrSet){
            
            //因为我们知道SQLString元素的使用范围是在域上，所以这里我们进行了强制类型转换
            VariableElement eleStrVari = (VariableElement)eleStr;
            forCount++;
            
            // 得到该元素的封装类型，也就是 包裹它的父类型
            TypeElement enclosingEle = (TypeElement)eleStrVari.getEnclosingElement();
            String className = enclosingEle.getQualifiedName().toString();
            
            generateStr.append("className = " + className);
            generateStr.append("\\t fieldName = " + eleStrVari.getSimpleName().toString());
            
            //得到在元素上，使用了注解的相关情况
            SQLString sqlString = eleStrVari.getAnnotation(SQLString.class);
            generateStr.append("\\t annotationName = " + sqlString.name());
            generateStr.append("\\t annotationValue = " + sqlString.value());
            generateStr.append("\\t forCount=" + forCount);
            generateStr.append("\\n");
        }
        
        generateStr.append("test File yaowen");
        generateStr.append("\\t count=" + count);
        generateFile(generateStr.toString());
        return true;
    }

    @Override
    public Set<String> getSupportedAnnotationTypes() {
        // TODO Auto-generated method stub
        Set<String> strings = new TreeSet<>();
        strings.add("com.yaoxiaowen.comp.proce.db.SQLString");
        return strings;
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        // TODO Auto-generated method stub
        return SourceVersion.latestSupported();
    }
    
    //将内容输出到文件
    private void generateFile(String str){
        try {
            //这是mac环境下的路径
            File file = new File( "/Users/yw/code/dbCustomProcFile");
            FileWriter fw = new FileWriter(file);
            fw.append(str);
            
            fw.flush();
            fw.close();
            
        } catch (Exception e) {
            // TODO: handle exception
            e.printStackTrace();
            printMsg(e.toString());
        }
    }
    
    private void printMsg(String msg){
        messager.printMessage(Diagnostic.Kind.ERROR, msg);
    }   
}

结合着注释，我们知道，这个处理器的功能就是将一些信息输出到 /Users/yw/code/dbCustomProcFile 这个文件中。

我在代码中使用了 javax.annotation.processing.Messager来输出一些log信息，因为这个过程是在编译时输出的，所以System.out.println()就没用了，这个输出信息是给使用了该处理器的第三方程序员看的，不是给该处理器的作者看的。
比如demo当中的log代码，在最后成功的打包成jar，在另一个项目中使用时(android Studio环境下,Eclipse我愣是没找到哪个窗口输出编译信息)，编译时期输出信息如下：

.......
:app:compileSc_360DebugJavaWithJavac
注: enter init, 进入init
注: enter process, 进入process
注: Creating DefaultRealmModule
注: enter process, 进入process
注: enter process, 进入process
注: 某些输入文件使用了未经检查或不安全的操作。
注: 有关详细信息, 请使用 -Xlint:unchecked 重新编译。

:app:generateJsonModelSc_360Debug UP-TO-DATE
:app:externalNativeBuildSc_360Debug
......

添加注册信息

处理器的代码虽然写完了，但是这还没完呢，剩下还有非常重要的步骤，那就是添加注册信息。因为注解处理器是属于javac的一个平台级的功能，所以我们的使用方式是将代码打包成jar的形式，这样就可以在其他第三方项目当中使用了。而在打包jar之前，则要在项目中添加注册信息。

先看一下这个目录的结构：

(eclipse)注册的步骤如下：
1，选中工程，鼠标右键，New -> Source Folder，创建 resources文件夹，然后依次通过New -> Folder 创建两个文件夹 : META-INF，services
2，在services文件夹下，New -> File, 创建一个文件，javax.annotation.processing.Processor。在文件中，输入自定义的处理器的全名:
com.yaoxiaowen.comp.proce.db.DbProcessor
输入之后记得键入回车一下。

其实这个手动注册的过程，也是可以不用我们麻烦的。google开发了一个注解工具AutoService,我们可以直接在处理器代码上使用。类似下面这样：

/**
  * @author www.yaoxiaowen.com
  */
@AutoService(Processor.class)
public class DbProcessor extends AbstractProcessor{
        .......

这个注解工具自动生成META-INF/services/javax.annotation.processing.Processor文件，文件里还包含了处理器的全名：
com.yaoxiaowen.comp.proce.db.DbProcessor

看到这里，你也许会比较震惊，我们在注解处理器的代码中也可以使用注解。
那么此时请再看看本文开头的那句话

注解处理器是运行在它自己的虚拟机jvm当中的，也就是说，javac启动了一个完整的java虚拟机来运行注解处理器.....

做完这些，我们的项目就已经完成了，下面要做的就是打包成jar了。

打包和使用jar(eclipse为例)

1： 打包jar
前面说过，编译期的注解处理器是平台级的功能，是要注册给javac的， 所以需要打包成jar， 我们的项目打包的名字是
AnnoCustomProce.jar

关于具体的打包过程，参见gif图(这是从鸿洋大神的博客上学习到的)。

2： 建立新项目
eclipse下的java项目，新建立一个lib文件夹，然后将AnnoCustomProce.jar手动拷贝到这个目录下。

3： 引用包，并启用annotation processor。
具体操作见gif图。

要注意一下两个gif图中的各种选项和配置。

使用注解

现在呢，已经大功告成了。下面就是使用了。
新建一个类，使用我们的注解。

public class AnnoCreateFile {

    @SQLString(name="yw")
    String filed;
    @SQLString(name="yaow", value=1)
    String name;
    
    /**
     * @author www.yaoxiaowen.com
     */
    public static void main(String[] args) {
        // TODO Auto-generated method stub
        System.out.println("hello world");
    }
}

当编译完这个项目时（eclipse默认就是Build Automatically），我们就能在 /Users/yw/code/目录下找到 dbCustomProcFile 文件了，打开这个文件，内容如下：

className = com.yaoxiaowen.testjar.AnnoCreateFile fieldName = filed annotationName = yw 
annotationValue = 0 forCount=1 className = com.yaoxiaowen.testjar.AnnoCreateFile fieldName = name 
annotationName = yaow annotationValue = 1 forCount=2 test File yaowen count=1test File yaowen count=2

大功告成，我们成功的实现了一个能够在编译时期起作用的自定义注解处理器。

当然，这个demo没有什么实际作用，它的功能也非常简单，但是了解了这个过程，我们在实际需求当中，就可以通过类似的方式来实现想要的功能了。

很多时候，我们都是希望注解处理器是来输出java代码的，既然是代码，那么总有格式的，这就不像简单的文件那样进行输出了，输出java代码，一般使用一个类库:javapoet。而我们如果在注解处理器中引入了第三方的类库，那么将其打包成jar的过程，就和我们演示的有所不同。这点需要自行google。另外，如果想对java源码进行游刃有余的处理，那么需要对于javax.lang.model 包下的各种Elements，工具之类的比较熟悉。具体的api，需要参考oracle的文档.