近來，開發(fā)項(xiàng)目中需求用到編譯期自定義注解的使用，本篇文章主要記錄一下使用的過程。

主要包含以下內(nèi)容：

1. 什么是注解

2. 注解的分類

3. Android 編譯期注解的使用

什么是注解

Java 中注解使用@interface 作為關(guān)鍵字，注解本身對(duì)代碼無影響，但具體能發(fā)揮什么作用完全取決于如何解析和處理它。

要想使用自定義注解，還需要了解元注解 ，也就是用來定義注解的注解 .

讓我們先來看下 Android 系統(tǒng)為我們提供的一些注解

// 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 保留的范圍，默認(rèn)值為CLASS. 可選值有三種
1.SOURCE, 在源文件中有效（即源文件保留）
2.CLASS, 在class文件中有效（即class保留）
3.RUNTIME, 在運(yùn)行時(shí)有效（即運(yùn)行時(shí)保留）

@Target 說明了 Annotation 所修飾的對(duì)象范圍： Annotation 可被用于 packages、types（類、接口、枚舉、Annotation 類型）、類型成員（方法、構(gòu)造方法、成員變量、枚舉值）、方法參數(shù)和本地變量（如循環(huán)變量、catch 參數(shù)）。在 Annotation 類型的聲明中使用了 target 可更加明晰其修飾的目標(biāo)。
作用：用于描述注解的使用范圍（即：被描述的注解可以用在什么地方）
取值(ElementType)有:
1.CONSTRUCTOR:用于描述構(gòu)造器
2.FIELD:用于描述域
3.LOCAL_VARIABLE:用于描述局部變量
4.METHOD:用于描述方法
5.PACKAGE:用于描述包
6.PARAMETER:用于描述參數(shù)
7.TYPE:用于描述類、接口(包括注解類型) 或enum聲明

@Documented 用于描述其它類型的 Annotation 應(yīng)該被作為被標(biāo)注的程序成員的公共API，因此可以被例如 Javadoc 此類的工具文檔化。Documented 是一個(gè)標(biāo)記注解，沒有成員。

@Inherited 元注解是一個(gè)標(biāo)記注解，@Inherited 闡述了某個(gè)被標(biāo)注的類型是被繼承的。如果一個(gè)使用了@Inherited修飾的 Annotation 類型被用于一個(gè) Class，則這個(gè) Annotation 將被用于該 Class 的子類。 　　
注意：@Inherited Annotation類型是被標(biāo)注過的 Class 的子類所繼承
類并不從它所實(shí)現(xiàn)的接口繼承 Annotation，方法并不從它所重載的方法繼承Annotation。 　　
當(dāng)@Inherited Annotation 類型標(biāo)注的 Annotation 的 @Retention是RetentionPolicy.RUNTIME，則反射API增強(qiáng)了這種繼承性。如果我們使用java.lang.reflect去查詢一個(gè)@Inherited Annotation 類型的 Annotation時(shí)，反射代碼檢查將展開工作：檢查 Class 和其父類，直到發(fā)現(xiàn)指定的 Annotation 類型被發(fā)現(xiàn)，或者到達(dá)類繼承結(jié)構(gòu)的頂層。

注解的分類

注解根據(jù)保留策略，分為三類，即@Retention對(duì)應(yīng)的三種可選值

使用 RetentionPolicy.SOURCE 標(biāo)注的 Annotation 僅用于源碼中標(biāo)記作用，例如上面系統(tǒng)中使用的 @Override 和 @Duration ，還有例如 @NotNull 和 @Deprecated ，這類注解僅存在于源碼中，當(dāng)源碼編譯成 .class 文件后就不見了。

使用 RetentionPolicy.CLASS 標(biāo)注的 Annotation 可以保留在class文件中 ，利用這個(gè)性質(zhì)我們可以在編譯期來處理解析這類的注解，本文后面主要實(shí)現(xiàn)的就是這類的注解。

使用 RetentionPolicy.RUNTIME 標(biāo)注的 Annotation 可用于 Java 運(yùn)行時(shí)，即我們可以在運(yùn)行時(shí)動(dòng)態(tài)處理解析這類的注解。這類注解通常都使用反射機(jī)制來掃描和解析，所以對(duì)性能會(huì)有一定的影響，現(xiàn)在一般都盡量避免大量的使用反射機(jī)制。

Android 編譯期注解的使用

首先，先說一下我們要實(shí)現(xiàn)的一個(gè)功能，即把每一個(gè)頁面（Activity）都映射到一個(gè)別名，然后通過類名就可以查找出該類的別名。
要實(shí)現(xiàn)編譯期注解的解析，我們要使用 AbstractProcessor 這個(gè)基類，但這個(gè)類是 Java 中的，在 Android Module 中不支持該類的使用。所以我們首先 Android Studio 中新建一個(gè)“Java Library”。
好了，我們先新建一個(gè)自定義注解類,因?yàn)槲覀冃枰粋€(gè)編譯期中使用的注解，所以我們使用 RetentionPolicy.CLASS 來標(biāo)識(shí)，其次這個(gè)注解只是用來標(biāo)注類的，所以 @Target 使用 ElementType.TYPE

@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface TrackName {
    String name() default "";
}

然后我們新建一個(gè)繼承于 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";

            // 創(chuàng)建Java文件
            JavaFileObject f = processingEnv.getFiler().createSourceFile(genarateClassName);
            // 在控制臺(tái)輸出文件路徑
            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("* 頁面別名映射關(guān)系表");
                pw.println("*/");
                pw.println("public class " + genarateClassName + " implements TrackInfoProvide {");
                
                // 緩存別名信息的列表
                pw.println("\n    private Map<String, String> trackNameMap;\n");
                // 構(gòu)造方法,將別名信息注入
                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("    }");
                // 實(shí)現(xiàn)查找信息接口
                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());
        }
    }
}

通過注解解析，可以直接生成一個(gè) TrackInfo.java 源代碼文件，參與到后面的代碼編譯過程中，并且可以在我們的源代碼使用這個(gè)生成的 TrackInfo 類。這里注意到生成的 TrackInfo 類還實(shí)現(xiàn)了一個(gè) TrackInfoProvide 的接口，這個(gè)后文會(huì)講到。

現(xiàn)在，一個(gè)完整的編譯期的注解的實(shí)現(xiàn)就算完成了。但是我們的注解解析器 Jvm 并不知道，我還需要把它告訴給 Jvm，讓其編譯的時(shí)候去處理它。

如圖所示，再 java 同一級(jí)目錄下創(chuàng)建一個(gè) resources 文件夾，在其中創(chuàng)建一個(gè) META-INF/services/javax.annotation.processing.Processor 文件，文件中填寫你注解解析器的全類名。

Paste_Image.png

com.test.compiler.TrackNameProcessor

現(xiàn)在你的注解就能正常使用了，你可以在 Android 主項(xiàng)目中直接添加依賴該 “Java Library”，或者直接生成一個(gè) Jar 包導(dǎo)入到工程中。
在 Android 項(xiàng)目的根目錄的 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'

現(xiàn)在就可以在你的代碼中使用該注解了

@TrackName(name = "測(cè)試頁面")
public class MainActivity extends AppCompatActivity {
....

編譯一遍項(xiàng)目后，就會(huì)自動(dòng)生成一個(gè)源文件，位于 \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","測(cè)試頁面");
    }

    @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;
    }
}

我們現(xiàn)在就可以在代碼中測(cè)試使用這個(gè)自動(dòng)生成的代碼了

@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());
}

你會(huì)發(fā)現(xiàn) Android Studio 的編輯器面板會(huì)有紅色的文件提示找不到的錯(cuò)誤提示，但是卻可以正常編譯運(yùn)行。
本來這樣就算完成了，但是，相信絕大多數(shù)的人對(duì)這種錯(cuò)誤提示非常不爽。
好吧，既然它提示找不到這個(gè)自動(dòng)生成的代碼，那我們就給它一個(gè)真正存在的。
所以我們定義了一個(gè)接口：

public interface TrackInfoProvide {

    /**
     * 通過類名查找足跡定義信息
     *
     * @param className
     * @return
     */
    public String getTrackNameByClass(String className);

}

讓生成的代碼實(shí)現(xiàn)該接口，然后我們就可以使用這個(gè)接口來愉快的使用自動(dòng)生成的代碼了。

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("找不到該類");
}

但是?。。『芸炷憔蜁?huì)發(fā)現(xiàn)，這樣的使用方法并不友好，需要把包名暴露給使用者，而且如果需要實(shí)現(xiàn)的方法接口比較多的話，編寫“生成代碼”的 Processor 過程非常的繁瑣且容易出錯(cuò)。
筆者在參考 ARouter 的實(shí)現(xiàn)后，有了更優(yōu)雅的處理建議：

我們自己實(shí)現(xiàn) TrackInfo 這個(gè)幫助類

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;
    }
}

這樣外部調(diào)用的時(shí)候僅需要
new TrackInfo().getTrackNameByClass("MainActivity");
就能完成，是不是比之前更簡(jiǎn)單了，不用再關(guān)心具體的實(shí)現(xiàn)細(xì)節(jié)。

再回到 TrackInfo 的實(shí)現(xiàn)，這次我們使用了另一個(gè)編譯期幫我們生成的類 com.test.trackinfo.TrackInfo$Helper , 它僅實(shí)現(xiàn)了一個(gè) IData 的接口

public interface IData {

    /**
     * 載入數(shù)據(jù)
     */
    void loadInto(Map<String, String> map);
}

而 com.test.trackinfo.TrackInfo$Helper 也變得更簡(jiǎn)單，只需要實(shí)現(xiàn)這個(gè)接口完成數(shù)據(jù)載入即可，無需再關(guān)心數(shù)據(jù)如何被使用，我們來看一下生成的代碼就知道了。

public class TrackInfo$Helper implements IData {

    @Override
    public void loadInto(Map<String, String> map) {
        map.put("MainActivity","測(cè)試頁面");
    }

}

怎么樣，是不是優(yōu)雅了許多，連強(qiáng)迫癥都消停了！