apt(Annotation Processor Tool) 注解处理知识汇总

【Annotation】Processing-Tool详解
一小时搞明白注解处理器（Annotation Processor Tool）

注解（Annotation）

是java 1.5的新特性，是一种能够添加到 Java 源代码的语法元数据。类、方法、变量、参数、包都可以被注解，可用来将信息元数据与程序元素进行关联。

元注解

元注解就是用来描述注解的注解，在java中有以下几个元注解：

@Documented

作用是告诉JavaDoc工具，当前注解本身也要显示在Java Doc中。

@Retention

用来定义当前注解的作用范围，有以下三个范围可选：

RetentionPolicy.SOURCE : 注解只存在于源码中，不会存在于.class文件中，在编译时会被忽略掉。
RetentionPolicy.CLASS：注解只存在于.class文件中，在编译期有效，但是在运行期会被忽略掉，这也是默认范围。
RetentionPolicy.RUNTIME：在运行期有效，JVM在运行期通过反射获得注解信息。

@Target

用于指定注解作用于java的哪些元素，未标注则表示可修饰所有.有以下这些元素类型可供选择：

ElementType.ANNOTATION_TYPE can be applied to an annotation type.
ElementType.CONSTRUCTOR can be applied to a constructor.
ElementType.FIELD can be applied to a field or property.
ElementType.LOCAL_VARIABLE can be applied to a local variable.
ElementType.METHOD can be applied to a method-level annotation.
ElementType.PACKAGE can be applied to a package declaration.
ElementType.PARAMETER can be applied to the parameters of a method.
ElementType.TYPE can be applied to any element of a class.

通过名字就可以看出来他们的元素类型，不过有两个需要特别说明下：

ElementType.ANNOTATION_TYPE:元注解类型，只能用来注解其它的注解，例如@Target和@Retention。
ElementType.TYPE：可以用来注解任何类型的java类，如类、接口、枚举、或者注解类。

@Inherited

注解所作用的类，在继承时默认无法继承父类的注解。除非注解声明了 @Inherited。同时Inherited声明出来的注解，只对类有效，对方法／属性无效。

注解处理器（Annotation Processor）

注解处理器是（Annotation Processor）是javac的一个工具，用来在编译时扫描和编译和处理注解（Annotation）。你可以自己定义注解和注解处理器去搞一些事情。一个注解处理器它以Java代码或者（编译过的字节码）作为输入，生成文件（通常是java文件）。这些生成的java文件不能修改，并且会同其手动编写的java代码一样会被javac编译。

自定义注解处理器一般继承AbstractProcessor，需要实现4个方法：

//自动注册
@AutoService(Processor.class)
public class ViewProcessor extends AbstractProcessor {
    /**
     * 文件相关的辅助类，生成JavaSourceCode
     */
    private Filer fileUtils;
    /**
     * 元素相关的辅助类，帮助我们去获取一些元素相关的信息
     */
    private Elements elementUtils;
    /**
     * 日志相关的辅助类
     */
    private Messager messager;

    /**
     * 初始化操作的方法，RoundEnvironment会提供很多有用的工具类Elements、Types和Filer等。
     *
     * @param processingEnv
     */
    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
        fileUtils = processingEnv.getFiler();
        elementUtils = processingEnv.getElementUtils();
        messager = processingEnv.getMessager();
    }

    /**
     * @return 返回支持的注解类型
     */
    @Override
    public Set getSupportedAnnotationTypes() {
        Set annotationTypes = new LinkedHashSet();
        annotationTypes.add(BindView.class.getCanonicalName());
        return annotationTypes;
    }

    /**
     * @return 返回支持的源码版本
     */
    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }

    private Map mProxyMap = new HashMap();

    /**
     * 这相当于每个处理器的主函数main()。在该方法中去扫描、评估、处理以及生成Java文件。
     *
     */
    @Override
    public boolean process(Set annotations, RoundEnvironment roundEnv) {
        ....
    }
}

注册自定义的处理器

你可能会问 “怎样注册我的注解处理器到 javac ？”。你必须提供一个.jar文件。就像其他 .jar 文件一样，你将你已经编译好的注解处理器打包到此文件中。并且，在你的 .jar 文件中，你必须打包一个特殊的文件javax.annotation.processing.Processor到META-INF/services目录下。因此你的 .jar 文件目录结构看起来就你这样：

MyProcess.jar
    -com
        -example
            -MyProcess.class
    -META-INF
        -services
            -javax.annotation.processing.Processor

javax.annotation.processing.Processor 文件的内容是一个列表，每一行是一个注解处理器的全称。例如：

com.example.MyProcess
com.example.AnotherProcess

好像很复杂？没事~ 我们有简单的方法！

可以通过@AutoService(Processor.class)，谷歌提供的自动注册注解，为你生成注册Processor所需要的格式文件（com.google.auto相关包）
记得添加依赖：

compile 'com.google.auto.service:auto-service:1.0-rc2'

Elements and TypeMirrors

在注解处理器中，我们扫描 java 源文件，源代码中的每一部分都是Element的一个特定类型。换句话说：Element代表程序中的元素，比如说包，类，方法。每一个元素代表一个静态的，语言级别的结构。在下面的例子中，我将添加注释来说明这个问题：

package com.example;

public class Foo { // TypeElement

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

    public Foo() {} // ExecuteableElement

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

你得换个角度来看源代码。它只是结构化的文本而已。它不是可以执行的。你可以把它当作你试图去解析的XML 文件。或者一棵编译中创建的抽象语法树。就像在 XML 解析器中，有许多DOM元素。你可以通过一个元素找到它的父元素或者子元素。

通过getEnclosedElements()获取所有子元素，getEnclosingElement()获取父元素。

如你所见，Elements代表源代码，TypeElement代表源代码中的元素类型，例如类。然后，TypeElement并不包含类的相关信息。你可以从TypeElement获取类的名称，但你不能获取类的信息，比如说父类。这些信息可以通过TypeMirror获取。你可以通过调用element.asType()来获取一个Element的TypeMirror。

process

在precess方法中处理具体的细节，通过roundEnv.getElementsAnnotatedWith(YourAnnotation.class)获取所有被@YourAnnotation注解的Element列表.
通过if(annotatedElement.getKind() != ElementKind.CLASS)判断元素是否是类。类是一种TypeElement元素。那我们为什么不使用if (! (annotatedElement instanceof TypeElement))来检查呢？这是错误的判断，因为接口也是一种TypeElement类型。所以在注解处理器中，你应该避免使用instanceof，应该用ElementKind或者配合TypeMirror使用TypeKind。

错误处理

在init()方法中，我们也获取了一个Messager的引用。Messager为注解处理器提供了一种报告错误消息，警告信息和其他消息的方式。它不是注解处理器开发者的日志工具。Messager是用来给那些使用了你的注解处理器的第三方开发者显示信息的。在官方文档中描述了不同级别的信息。非常重要的是Kind.ERROR，因为这种消息类型是用来表明我们的注解处理器在处理过程中出错了。有可能是第三方开发者误使用了我们的注解（比如，使用@Factory注解了一个接口）。这个概念与传统的 java 应用程序有一点区别。传统的 java 应用程序出现了错误，你可以抛出一个异常。如果你在process()中抛出了一个异常，那 jvm 就会崩溃。注解处理器的使用者将会得到一个从 javac 给出的非常难懂的异常错误信息。因为它包含了注解处理器的堆栈信息。因此注解处理器提供了Messager类。它能打印漂亮的错误信息，而且你可以链接到引起这个错误的元素上。在现代的IDE中，第三方开发者可以点击错误信息，IDE会跳转到产生错误的代码行中，以便快速定位错误。

代码生成

生成 java 文件跟写其他文件完全一样。我们可以使用Filer提供的一个Writer对象来操作。我们可以用字符串拼接的方法写入我们生成的代码。幸运的是，Square公司（因为提供了许多非常优秀的开源项目二非常有名）给我们提供了JavaWriter，这是一个高级的生成Java代码的库，使用起来更加简便。

Example

writer.emitPackage("com.example")
    .beginType("com.example.Person", "class", EnumSet.of(PUBLIC, FINAL))
    .emitField("String", "firstName", EnumSet.of(PRIVATE))
    .emitField("String", "lastName", EnumSet.of(PRIVATE))
    .emitJavadoc("Returns the person's full name.")
    .beginMethod("String", "getName", EnumSet.of(PUBLIC))
    .emitStatement("return firstName + \" \" + lastName")
    .endMethod()
    .endType();

Would produce the following source output:

package com.example;

public final class Person {
  private String firstName;
  private String lastName;
  /**
   * Returns the person's full name.
   */
  public String getName() {
    return firstName + " " + lastName;
  }
}