近来，开发项目中需求用到编译期自定义注解的使用，本篇文章主要记录一下使用的过程。
主要包含以下内容：
1. 什么是注解
2. 注解的分类
3. Android 编译期注解的使用
什么是注解
Java 中注解使用@interface 作为关键字，注解本身对代码无影响，但具体能发挥什么作用完全取决于如何解析和处理它。
要想使用自定义注解，还需要了解元注解 ，也就是用来定义注解的注解 .
让我们先来看下 Android 系统为我们提供的一些注解
// java.lang.Override
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}
// Toast.makeText
@IntDef({LENGTH_SHORT, LENGTH_LONG})
@Retention(RetentionPolicy.SOURCE)
public @interface Duration {}
这些相信大家都用过，元注解共有四种 @Retention, @Target, @Inherited, @Documented
@Retention 保留的范围，默认值为CLASS. 可选值有三种
1.SOURCE, 在源文件中有效（即源文件保留）
2.CLASS, 在class文件中有效（即class保留）
3.RUNTIME, 在运行时有效（即运行时保留）
@Target 说明了 Annotation 所修饰的对象范围： Annotation 可被用于 packages、types（类、接口、枚举、Annotation 类型）、类型成员（方法、构造方法、成员变量、枚举值）、方法参数和本地变量（如循环变量、catch 参数）。在 Annotation 类型的声明中使用了 target 可更加明晰其修饰的目标。
作用：用于描述注解的使用范围（即：被描述的注解可以用在什么地方）
取值(ElementType)有:
1.CONSTRUCTOR:用于描述构造器
2.FIELD:用于描述域
3.LOCAL_VARIABLE:用于描述局部变量
4.METHOD:用于描述方法
5.PACKAGE:用于描述包
6.PARAMETER:用于描述参数
7.TYPE:用于描述类、接口(包括注解类型) 或enum声明
@Documented 用于描述其它类型的 Annotation 应该被作为被标注的程序成员的公共API，因此可以被例如 Javadoc 此类的工具文档化。Documented 是一个标记注解，没有成员。
@Inherited 元注解是一个标记注解，@Inherited 阐述了某个被标注的类型是被继承的。如果一个使用了@Inherited修饰的 Annotation 类型被用于一个 Class，则这个 Annotation 将被用于该 Class 的子类。
注意：@Inherited Annotation类型是被标注过的 Class 的子类所继承
类并不从它所实现的接口继承 Annotation，方法并不从它所重载的方法继承Annotation。
当@Inherited Annotation 类型标注的 Annotation 的 @Retention是RetentionPolicy.RUNTIME，则反射API增强了这种继承性。如果我们使用java.lang.reflect去查询一个@Inherited Annotation 类型的 Annotation时，反射代码检查将展开工作：检查 Class 和其父类，直到发现指定的 Annotation 类型被发现，或者到达类继承结构的顶层。
注解的分类
注解根据保留策略，分为三类，即@Retention对应的三种可选值
使用 RetentionPolicy.SOURCE 标注的 Annotation 仅用于源码中标记作用，例如上面系统中使用的 @Override 和 @Duration ，还有例如 @NotNull 和 @Deprecated ，这类注解仅存在于源码中，当源码编译成 .class 文件后就不见了。
使用 RetentionPolicy.CLASS 标注的 Annotation 可以保留在class文件中 ，利用这个性质我们可以在编译期来处理解析这类的注解，本文后面主要实现的就是这类的注解。
使用 RetentionPolicy.RUNTIME 标注的 Annotation 可用于 Java 运行时，即我们可以在运行时动态处理解析这类的注解。这类注解通常都使用反射机制来扫描和解析，所以对性能会有一定的影响，现在一般都尽量避免大量的使用反射机制。
Android 编译期注解的使用
首先，先说一下我们要实现的一个功能，即把每一个页面（Activity）都映射到一个别名，然后通过类名就可以查找出该类的别名。
要实现编译期注解的解析，我们要使用 AbstractProcessor 这个基类，但这个类是 Java 中的，在 Android Module 中不支持该类的使用。所以我们首先 Android Studio 中新建一个“Java Library”。
好了，我们先新建一个自定义注解类,因为我们需要一个编译期中使用的注解，所以我们使用 RetentionPolicy.CLASS 来标识，其次这个注解只是用来标注类的，所以 @Target 使用 ElementType.TYPE
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface TrackName {
String name() default "";
}
然后我们新建一个继承于 AbstractProcessor 的类用来解析该注解
// JDK version,use java7
@SupportedSourceVersion(SourceVersion.RELEASE_7)
// annotation package name
@SupportedAnnotationTypes({"com.test.compiler.annotation.TrackName"})
public class TrackNameProcessor extends AbstractProcessor {
@Override
public boolean process(Set<? extends TypeElement> set, RoundEnvironment roundEnvironment) {
if (set != null && !set.isEmpty()) {
generateJavaClassFile(set, roundEnvironment);
return true;
}
return false;
}
// 生成Java源文件
private void generateJavaClassFile(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
// set of track
Map<String, String> trackMap = new HashMap<>();
// print on gradle console
Messager messager = processingEnv.getMessager();
for (TypeElement te : annotations) {
for (Element e : roundEnv.getElementsAnnotatedWith(te)) {
// 打印
messager.printMessage(Diagnostic.Kind.NOTE, "Printing: " + e.toString());
messager.printMessage(Diagnostic.Kind.NOTE, "Printing: " + e.getSimpleName());
messager.printMessage(Diagnostic.Kind.NOTE, "Printing: " + e.getEnclosingElement().toString());
// 获取注解
TrackName annotation = e.getAnnotation(TrackName.class);
// 获取名称
String name = "".equals(annotation.name()) ? e.getSimpleName().toString() : annotation.name();
// 保存映射信息
trackMap.put(e.getSimpleName().toString(), name);
}
}
try {
// 生成的包名
String genaratePackageName = "com.test.trackinfo";
// 生成的类名
String genarateClassName = "TrackInfo";
// 创建Java文件
JavaFileObject f = processingEnv.getFiler().createSourceFile(genarateClassName);
// 在控制台输出文件路径
messager.printMessage(Diagnostic.Kind.NOTE, "Printing: " + f.toUri());
Writer w = f.openWriter();
try {
PrintWriter pw = new PrintWriter(w);
pw.println("package " + genaratePackageName + ";\n");
pw.println("import java.util.HashMap;");
pw.println("import java.util.Map;");
pw.println("import com.test.compiler.TrackInfoProvide;\n");
pw.println("/**");
pw.println("* @author pengj <a href=\"#\">3344716091@qq.com</a>");
pw.println("* this file is auto-create by compiler,please don`t edit it");
pw.println("* 页面别名映射关系表");
pw.println("*/");
pw.println("public class " + genarateClassName + " implements TrackInfoProvide {");
// 缓存别名信息的列表
pw.println("\n private Map<String, String> trackNameMap;\n");
// 构造方法,将别名信息注入
pw.println(" public " + genarateClassName + "() {");
pw.println(" trackNameMap = new HashMap<String,String>(); ");
Iterator<String> keys = trackMap.keySet().iterator();
while (keys.hasNext()) {
String key = keys.next();
String value = trackMap.get(key);
pw.println(" trackNameMap.put(\"" + key + "\",\"" + value + "\");");
}
pw.println(" }");
// 实现查找信息接口
pw.println("\n @Override");
pw.println(" public String getTrackNameByClass(String className) {");
pw.println(" String output = className;");
pw.println(" if(trackNameMap != null && !trackNameMap.isEmpty()) {");
pw.println(" String value = trackNameMap.get(className);");
pw.println(" output = (value == null?output:value);");
pw.println(" }");
pw.println(" return output;");
pw.println(" }");
pw.println("}");
pw.flush();
} finally {
w.close();
}
} catch (IOException x) {
processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, x.toString());
}
}
}
通过注解解析，可以直接生成一个 TrackInfo.java 源代码文件，参与到后面的代码编译过程中，并且可以在我们的源代码使用这个生成的 TrackInfo 类。这里注意到生成的 TrackInfo 类还实现了一个 TrackInfoProvide 的接口，这个后文会讲到。
现在，一个完整的编译期的注解的实现就算完成了。但是我们的注解解析器 Jvm 并不知道，我还需要把它告诉给 Jvm，让其编译的时候去处理它。
如图所示，再 java 同一级目录下创建一个 resources 文件夹，在其中创建一个 META-INF/services/javax.annotation.processing.Processor 文件，文件中填写你注解解析器的全类名。
文件信息如下
com.test.compiler.TrackNameProcessor
现在你的注解就能正常使用了，你可以在 Android 主项目中直接添加依赖该 “Java Library”，或者直接生成一个 Jar 包导入到工程中。
在 Android 项目的根目录的 build.gradle 中 apt 插件：
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:2.3.0'
classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
引用的 module 目录的 gradle 中, 添加
apply plugin: 'android-apt'
现在就可以在你的代码中使用该注解了
@TrackName(name = "测试页面")
public class MainActivity extends AppCompatActivity {
....
编译一遍项目后，就会自动生成一个源文件，位于 \build\generated\source\apt\debug\TrackInfo.java
public class TrackInfo implements TrackInfoProvide {
private Map<String, String> trackNameMap;
public TrackInfo() {
trackNameMap = new HashMap<String,String>();
trackNameMap.put("MainActivity","测试页面");
}
@Override
public String getTrackNameByClass(String className) {
String output = className;
if(trackNameMap != null && !trackNameMap.isEmpty()) {
String value = trackNameMap.get(className);
output = (value == null?output:value);
}
return output;
}
}
我们现在就可以在代码中测试使用这个自动生成的代码了
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
TextView textView = (TextView) findViewById(R.id.text);
textView.setText(com.szy.seebaby.service.trackinfo.TrackInfo.class.getName());
}
你会发现 Android Studio 的编辑器面板会有红色的文件提示找不到的错误提示，但是却可以正常编译运行。
本来这样就算完成了，但是，相信绝大多数的人对这种错误提示非常不爽。
好吧，既然它提示找不到这个自动生成的代码，那我们就给它一个真正存在的。
所以我们定义了一个接口：
public interface TrackInfoProvide {
/**
* 通过类名查找足迹定义信息
*
* @param className
* @return
*/
public String getTrackNameByClass(String className);
}
让生成的代码实现该接口，然后我们就可以使用这个接口来愉快的使用自动生成的代码了。
String classFullName = "com.test.trackinfo.TrackInfo";
try {
Class<?> clazz = Class.forName(classFullName);
TrackInfoProvide provide = (TrackInfoProvide) clazz.newInstance();
textView.setText(provide.getTrackNameByClass("MainActivity"));
} catch (Exception e) {
e.printStackTrace();
textView.setText("找不到该类");
}
但是！！！很快你就会发现，这样的使用方法并不友好，需要把包名暴露给使用者，而且如果需要实现的方法接口比较多的话，编写“生成代码”的 Processor 过程非常的繁琐且容易出错。
笔者在参考 ARouter 的实现后，有了更优雅的处理建议：
我们自己实现 TrackInfo 这个帮助类
public class TrackInfo implements TrackInfoProvide {
private Map<String, String> trackNameMap;
public TrackInfo() {
trackNameMap = new HashMap<String,String>();
String classFullName = "com.test.trackinfo.TrackInfo$Helper";
try {
Class<?> clazz = Class.forName(classFullName);
IData data = (IData)clazz.newInstance();
data.loadInto(trackNameMap);
} catch (Exception e) {
e.printStackTrace();
}
}
@Override
public String getTrackNameByClass(String className) {
String output = className;
if(trackNameMap != null && !trackNameMap.isEmpty()) {
String value = trackNameMap.get(className);
output = (value == null?output:value);
}
return output;
}
}
这样外部调用的时候仅需要
new TrackInfo().getTrackNameByClass("MainActivity");
就能完成，是不是比之前更简单了，不用再关心具体的实现细节。
再回到 TrackInfo 的实现，这次我们使用了另一个编译期帮我们生成的类 com.test.trackinfo.TrackInfo$Helper , 它仅实现了一个 IData 的接口
public interface IData {
/**
* 载入数据
*/
void loadInto(Map<String, String> map);
}
而 com.test.trackinfo.TrackInfo$Helper 也变得更简单，只需要实现这个接口完成数据载入即可，无需再关心数据如何被使用，我们来看一下生成的代码就知道了。
public class TrackInfo$Helper implements IData {
@Override
public void loadInto(Map<String, String> map) {
map.put("MainActivity","测试页面");
}
}
怎么样，是不是优雅了许多，连强迫症都消停了！
