注解（二）- 自定义注解处理器

标签： java annotation

上一篇博客讨论了关于注解的基础知识，以及运行时（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的文档.

总结和反思

我在学习自定义注解处理器的过程中，参考了网上的很多博客，敲代码进行实测，但是实际上依旧碰到了很多的问题，也折腾了好久，在这里我将自己所碰到的问题，都罗列出来。（虽然有些是可笑的低级错误），希望对大家有所帮助。

  1. resource/META-INF/services com.yaoxiaowen.annotation.createjson.BeanProcessor 文件中，写的是 处理器的类DbProcessor，而不是你的注解类:SQLString。
  2. resource 这个文件夹 是 New Source Folder，后面两个文件，才是 New Folder， 关于两者之间的区别: 后者就是一个普通的文件夹而已，但是前者，是属于项目的一部分，eclipse会编译这个文件夹。所以有些文章说建立的 是res(而不是resource)文件夹,这个其实无所谓，只要它是 Souce Folder.
  3. 在导入包的时候，注意不要导入错误的包(比如import java.awt.Window.Type)。因为往往同一个类名，它在不同的包里都有实现。像常用的List，经常导错包。java.awt.List和java.util.List。 List比较常用，我们很容易找到错误，但是 Type之类的不常用，所以不是那么容易发现。
  4. 在处理器的生成文件的代码中，有这样一句：
    File file = new File( "/Users/yw/code/dbCustomProcFile");
    那如果我将代码改成这样:
    File file = new File("./dbCustomProcFile");
    那么请问此时，这个dbCustomProcFile文件到底在那里呢？
    在我的电脑上，该文件路径分别如下
    D:\software\eclipse\dbCustomProcFile(window)或/Users/yw//Downloads/Eclipse.app/Contents/MacOS/dbCustomProcFile（mac）。
    一般我们在工程中使用./我们都认为是工程当前的目录，但是在注解处理器中，这个路径实际上是eclipse 安装路径下 javac的路径。的确应该如此，因为注解处理器毕竟是javac的一个工具。
  5. 某一次测试时，当我向新工程导入生成的jar包时，刚刚导入eclipse就报错。

    后来终于发现了问题所在。

    在编码过程中，函数的行参原来是processingEnv,后来我嫌长，就修改为了env,但是下面一句super.init()却忘记修改了。所以导致找不到这个参数，而问题是在window和mac下，这句代码IDE都没有任何提示，我又在下面故意写了一句错代码String = 2,此时IDE提示错误。 那为什么第一句话IDE就是没报错呢。测试了普通java文件的同种类型的错误，IDE就会报错，所以这真的让我不解。

以上就是本篇文章的全部内容，关于注解处理器深处的很多东西其实也没搞懂。也欢迎大家留言指点交流。

作者： www.yaoxiaowen.com

github： https://github.com/yaowen369

欢迎对于本人的博客内容批评指点，如果问题，可评论或邮件(yaowen369@gmail.com)联系 

<p >
		 欢迎转载，转载请注明出处.谢谢
</p>


<script type="text/javascript">
 function    Curgo()   
 {   
     window.open(window.location.href);
 }   
</script>
posted @ 2017-04-23 20:56  eleven_yw  阅读(5234)  评论(6)  编辑  收藏  举报