Android 利用 APT 技术在编译期生成代码

apt(annotation processing tool 的简称)，可以在代码编译期解析注解，并且生成新的 java 文件，减少手动的代码输入。现在有很多主流库都用上了 apt，比如 dagger2, butterknife, eventbus3 等，我们要紧跟潮流，与时俱进呐！ (ง •̀_•́)ง

下面通过一个简单的 view 注入项目 viewfinder 来介绍 apt 相关内容，简单实现了类似于butterknife 中的两种注解 @bindview 和 @onclick 。

项目地址：https://github.com/brucezz/viewfinder

大概项目结构如下：

1. viewfinder-annotation - 注解相关模块
2. viewfinder-compiler - 注解处理器模块
3. viewfinder - api 相关模块
4. sample - 示例 demo 模块
   

实现目标

在通常的 android 项目中，会写大量的界面，那么就会经常重复地写一些代码，比如：

textview text = (textview) findviewbyid(r.id.tv);
text.setonclicklistener(new view.onclicklistener() {
 @override
 public void onclick(view view) {
  // on click
 }
});

天天写这么冗长又无脑的代码，还能不能愉快地玩耍啦。所以，我打算通过 viewfinder 这个项目替代这重复的工作，只需要简单地标注上注解即可。通过控件 id 进行注解，并且@onclick 可以对多个控件注解同一个方法。就像下面这样子咯：

@bindview(r.id.tv) textview mtextview;
@onclick({r.id.tv, r.id.btn})
public void onsomethingclick() {
 // on click
}

定义注解

创建 module viewfinder-annotation ，类型为 java library，定义项目所需要的注解。

在 viewfinder 中需要两个注解 @bindview 和 @onclick 。实现如下：

@retention(retentionpolicy.class)
@target(elementtype.field)
public @interface bindview {
 int value();
}

@retention(retentionpolicy.class)
@target(elementtype.method)
public @interface onclick {
 int[] value();
}

@bindview 需要对成员变量进行注解，并且接收一个 int 类型的参数； @onclick 需要对方法进行注解，接收一组 int 类型参数，相当于给一组 view 指定点击响应事件。

编写 api

创建 module viewfinder，类型为 android library。在这个 module 中去定义 api，也就是去确定让别人如何来使用我们这个项目。

首先需要一个 api 主入口，提供静态方法直接调用，就比如这样：

viewfinder.inject(this);

同时，需要为不同的目标（比如 activity、fragment 和 view 等）提供重载的注入方法，最终都调用 inject() 方法。其中有三个参数：

1. host 表示注解 view 变量所在的类，也就是注解类
2. source 表示查找 view 的地方，activity & view 自身就可以查找，fragment 需要在自己的 itemview 中查找
3. provider 是一个接口，定义了不同对象（比如 activity、view 等）如何去查找目标 view，项目中分别为 activity、view 实现了 provider 接口。

public class viewfinder {

 private static final activityprovider provider_activity = new activityprovider();
 private static final viewprovider provider_view = new viewprovider();

 public static void inject(activity activity) {
  inject(activity, activity, provider_activity);
 }
 public static void inject(view view) {
  // for view
  inject(view, view);
 }
 public static void inject(object host, view view) {
  // for fragment
  inject(host, view, provider_view);
 }
 public static void inject(object host, object source, provider provider) {
  // how to implement ?
 }
}

那么 inject() 方法中都写一些什么呢？

首先我们需要一个接口 finder，然后为每一个注解类都生成一个对应的内部类并且实现这个接口，然后实现具体的注入逻辑。在 inject() 方法中首先找到调用者对应的 finder 实现类，然后调用其内部的具体逻辑来达到注入的目的。

接口 finder 设计如下 ：

public interface finder<t> {
 void inject(t host, object source, provider provider);
}

举个例子，为 mainactivity 生成 mainactivity$$finder，对其注解的 view 进行初始化和设置点击事件，这就跟我们平常所写的重复代码基本相同。

public class mainactivity$$finder implements finder<mainactivity> {
 @override
 public void inject(final mainactivity host, object source, provider provider) {
  host.mtextview = (textview) (provider.findview(source, 2131427414));
  host.mbutton = (button) (provider.findview(source, 2131427413));
  host.medittext = (edittext) (provider.findview(source, 2131427412));
  view.onclicklistener listener;
  listener = new view.onclicklistener() {
   @override
   public void onclick(view view) {
    host.onbuttonclick();
   }
  };
  provider.findview(source, 2131427413).setonclicklistener(listener);
  listener = new view.onclicklistener() {
   @override
   public void onclick(view view) {
    host.ontextclick();
   }
  };
  provider.findview(source, 2131427414).setonclicklistener(listener);
 }
}

好了，所有注解类都有了一个名为 xx$$finder 的内部类。我们首先通过注解类的类名，得到其对应内部类的 class 对象，然后实例化拿到具体对象，调用注入方法。

public class viewfinder {

 // same as above

 private static final map<string, finder> finder_map = new hashmap<>();

 public static void inject(object host, object source, provider provider) {
  string classname = host.getclass().getname();
  try {
   finder finder = finder_map.get(classname);
   if (finder == null) {
    class<?> finderclass = class.forname(classname + "$$finder");
    finder = (finder) finderclass.newinstance();
    finder_map.put(classname, finder);
   }
   finder.inject(host, source, provider);
  } catch (exception e) {
   throw new runtimeexception("unable to inject for " + classname, e);
  }
 }
}

另外代码中使用到了一点反射，所以为了提高效率，避免每次注入的时候都去找 finder 对象，这里用一个 map 将第一次找到的对象缓存起来，后面用的时候直接从 map 里面取。

到此，api 模块的设计基本搞定了，接下来就是去通过注解处理器为每一个注解类生成 finder内部类。

创建注解处理器

创建 module viewfinder-compiler，类型为 java library，实现一个注解处理器。

这个模块需要添加一些依赖：

compile project(':viewfinder-annotation')
compile 'com.squareup:javapoet:1.7.0'
compile 'com.google.auto.service:auto-service:1.0-rc2'

1. 因为要用到前面定义的注解，当然要依赖 viewfinder-annotation。
2. javapoet 是方块公司出的又一个好用到爆炸的裤子，提供了各种 api 让你用各种姿势去生成 java 代码文件，避免了徒手拼接字符串的尴尬。
3. auto-service 是 google 家的裤子，主要用于注解 processor，对其生成 meta-inf 配置信息。
   

下面就来创建我们的处理器 viewfinderprocessor。

@autoservice(processor.class)
public class viewfinderprocesser extends abstractprocessor {

 /**
  * 使用 google 的 auto-service 库可以自动生成 meta-inf/services/javax.annotation.processing.processor 文件
  */

 private filer mfiler; //文件相关的辅助类
 private elements melementutils; //元素相关的辅助类
 private messager mmessager; //日志相关的辅助类

 @override
 public synchronized void init(processingenvironment processingenv) {
  super.init(processingenv);
  mfiler = processingenv.getfiler();
  melementutils = processingenv.getelementutils();
  mmessager = processingenv.getmessager();
 }

 /**
  * @return 指定哪些注解应该被注解处理器注册
  */
 @override
 public set<string> getsupportedannotationtypes() {
  set<string> types = new linkedhashset<>();
  types.add(bindview.class.getcanonicalname());
  types.add(onclick.class.getcanonicalname());
  return types;
 }

 /**
  * @return 指定使用的 java 版本。通常返回 sourceversion.latestsupported()。
  */
 @override
 public sourceversion getsupportedsourceversion() {
  return sourceversion.latestsupported();
 }

 @override
 public boolean process(set<? extends typeelement> annotations, roundenvironment roundenv) {
  // to process annotations 
  return false;
 }
}

用 @autoservice 来注解这个处理器，可以自动生成配置信息。

在 init() 可以初始化拿到一些实用的工具类。

在 getsupportedannotationtypes() 方法中返回所要处理的注解的集合。

在 getsupportedsourceversion() 方法中返回 java 版本。

这几个方法写法基本上都是固定的，重头戏在 process() 方法。

这里插播一下 element 元素相关概念，后面会用到不少。

element 元素，源代码中的每一部分都是一个特定的元素类型，分别代表了包、类、方法等等，具体看 demo。

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
 ) {
 }
}

这些 element 元素，相当于 xml 中的 dom 树，可以通过一个元素去访问它的父元素或者子元素。

element.getenclosingelement();// 获取父元素
 element.getenclosedelements();// 获取子元素

注解处理器的整个处理过程跟普通的 java 程序没什么区别，我们可以使用面向对象的思想和设计模式，将相关逻辑封装到 model 中，使得流程更清晰简洁。分别将注解的成员变量、点击方法和整个注解类封装成不同的 model。

public class bindviewfield {
 private variableelement mfieldelement;
 private int mresid;

 public bindviewfield(element element) throws illegalargumentexception {
  if (element.getkind() != elementkind.field) {
   throw new illegalargumentexception(
    string.format("only fields can be annotated with @%s", bindview.class.getsimplename()));
  }

  mfieldelement = (variableelement) element;
  bindview bindview = mfieldelement.getannotation(bindview.class);
  mresid = bindview.value();
 }
 // some getter methods
}

主要就是在初始化时校验了一下元素类型，然后获取注解的值，在提供几个 get 方法。onclickmethod 封装类似。

public class annotatedclass {

 public typeelement mclasselement;
 public list<bindviewfield> mfields;
 public list<onclickmethod> mmethods;
 public elements melementutils;

 // omit some easy methods 

 public javafile generatefinder() {

  // method inject(final t host, object source, provider provider)
  methodspec.builder injectmethodbuilder = methodspec.methodbuilder("inject")
   .addmodifiers(modifier.public)
   .addannotation(override.class)
   .addparameter(typename.get(mclasselement.astype()), "host", modifier.final)
   .addparameter(typename.object, "source")
   .addparameter(typeutil.provider, "provider");

  for (bindviewfield field : mfields) {
   // find views
   injectmethodbuilder.addstatement("host.$n = ($t)(provider.findview(source, $l))", field.getfieldname(),
    classname.get(field.getfieldtype()), field.getresid());
  }

  if (mmethods.size() > 0) {
   injectmethodbuilder.addstatement("$t listener", typeutil.android_on_click_listener);
  }
  for (onclickmethod method : mmethods) {
   // declare onclicklistener anonymous class
   typespec listener = typespec.anonymousclassbuilder("")
    .addsuperinterface(typeutil.android_on_click_listener)
    .addmethod(methodspec.methodbuilder("onclick")
     .addannotation(override.class)
     .addmodifiers(modifier.public)
     .returns(typename.void)
     .addparameter(typeutil.android_view, "view")
     .addstatement("host.$n()", method.getmethodname())
     .build())
    .build();
   injectmethodbuilder.addstatement("listener = $l ", listener);
   for (int id : method.ids) {
    // set listeners
    injectmethodbuilder.addstatement("provider.findview(source, $l).setonclicklistener(listener)", id);
   }
  }
  // generate whole class 
  typespec finderclass = typespec.classbuilder(mclasselement.getsimplename() + "$$finder")
   .addmodifiers(modifier.public)
   .addsuperinterface(parameterizedtypename.get(typeutil.finder, typename.get(mclasselement.astype())))
   .addmethod(injectmethodbuilder.build())
   .build();

  string packagename = melementutils.getpackageof(mclasselement).getqualifiedname().tostring();
  // generate file
  return javafile.builder(packagename, finderclass).build();
 }
}

annotatedclass 表示一个注解类，里面放了两个列表，分别装着注解的成员变量和方法。在generatefinder() 方法中，按照上一节设计的模板，利用 javapoet 的 api 生成代码。这部分没啥特别的姿势，照着 javapoet 文档 来就好了，文档写得很细致。

有很多地方需要用到对象的类型，普通类型可以用

classname get(string packagename, string simplename, string... simplenames)

传入包名、类名、内部类名，就可以拿到想要的类型了（可以参考 项目中typeutil 类）。

用到泛型的话，可以用
parameterizedtypename get(classname rawtype, typename... typearguments)

传入具体类和泛型类型就好了。

这些 model 都确定好了之后，process() 方法就很清爽啦。使用 roundenvironment 参数来查询被特定注解标注的元素，然后解析成具体的 model，最后生成代码输出到文件中。

@autoservice(processor.class)
public class viewfinderprocesser extends abstractprocessor {

 private map<string, annotatedclass> mannotatedclassmap = new hashmap<>();

 @override
 public boolean process(set<? extends typeelement> annotations, roundenvironment roundenv) {
  // process() will be called several times
  mannotatedclassmap.clear();

  try {
   processbindview(roundenv);
   processonclick(roundenv);
  } catch (illegalargumentexception e) {
   error(e.getmessage());
   return true; // stop process
  }

  for (annotatedclass annotatedclass : mannotatedclassmap.values()) {
   try {
    info("generating file for %s", annotatedclass.getfullclassname());
    annotatedclass.generatefinder().writeto(mfiler);
   } catch (ioexception e) {
    error("generate file failed, reason: %s", e.getmessage());
    return true;
   }
  }
  return true;
 }

 private void processbindview(roundenvironment roundenv) throws illegalargumentexception {
  for (element element : roundenv.getelementsannotatedwith(bindview.class)) {
   annotatedclass annotatedclass = getannotatedclass(element);
   bindviewfield field = new bindviewfield(element);
   annotatedclass.addfield(field);
  }
 }

 private void processonclick(roundenvironment roundenv) {
  // same as processbindview()
 }

 private annotatedclass getannotatedclass(element element) {
  typeelement classelement = (typeelement) element.getenclosingelement();
  string fullclassname = classelement.getqualifiedname().tostring();
  annotatedclass annotatedclass = mannotatedclassmap.get(fullclassname);
  if (annotatedclass == null) {
   annotatedclass = new annotatedclass(classelement, melementutils);
   mannotatedclassmap.put(fullclassname, annotatedclass);
  }
  return annotatedclass;
 }
}

首先解析注解元素，并放到对应的注解类对象中，最后调用方法生成文件。model 的代码中还会加入一些校验代码，来判断注解元素是否合理，数据是否正常，然后抛出异常，处理器接收到之后可以打印出错误提示，然后直接返回 true 来结束处理。

至此，注解处理器也基本完成了，具体细节参考项目代码。

实际项目使用

创建 module sample，普通的 android module，来演示 viewfinder 的使用。

在整个项目下的 build.gradle 中添加

classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'

然后在 sample module 下的 build.gradle 中添加

apply plugin: 'com.neenbedankt.android-apt'

同时添加依赖：

compile project(':viewfinder-annotation')
compile project(':viewfinder')
apt project(':viewfinder-compiler')

然后随便创建个布局，随便添加几个控件，就能体验注解啦。

public class mainactivity extends appcompatactivity {
 @bindview(r.id.tv) textview mtextview;
 @bindview(r.id.btn) button mbutton;
 @bindview(r.id.et) edittext medittext;

 @onclick(r.id.btn)
 public void onbuttonclick() {
  toast.maketext(this, "onbuttonclick", toast.length_short).show();
 }

 @onclick(r.id.tv)
 public void ontextclick() {
  toast.maketext(this, "ontextclick", toast.length_short).show();
 }

 @override
 protected void oncreate(bundle savedinstancestate) {
  super.oncreate(savedinstancestate);
  setcontentview(r.layout.activity_main);
  viewfinder.inject(this);
 }
}

这个时候 build 一下项目，就能看到生成的 mainactivity$$finder 类了，再运行项目就跑起来了。每次改变注解之后，build 一下项目就好啦。

all done ~

这个项目也就是个玩具级的 apt 项目，借此来学习如何编写 apt 项目。感觉 apt 项目更多地是考虑如何去设计架构，类之间如何调用，需要生成什么样的代码，提供怎样的 api 去调用。最后才是利用注解处理器去解析注解，然后用 javapoet 去生成具体的代码。

思路比实现更重要，设计比代码更巧妙。

参考

1. annotation-processing-tool详解 （大力推荐）
2. android 如何编写基于编译时注解的项目
3. javapoet 文档
4. butterknife （代码结构设计很棒）

 通过此文，希望能帮助大家开发android应用程序，谢谢大家对本站的支持！