使用Android註解處理器，解放勞動生產力

鹹魚不思議發表於2018-02-11
Android

“我已放棄成為珠三角頭髮最濃密的程式設計師夢想...”

簡介

在android開發中，比較常用到的第三方庫中，有不少用到了 註解處理器(Annotation Processor)。 比較常見的就有 Butterknife，Dagger2，DBFlow 等。

註解

Java中存在不少關於註解的Api, 比如@Override用於覆蓋父類方法，@Deprecated表示已捨棄的類或方法屬性等，android中又多了一些註解的擴充套件，如@NonNull, @StringRes, @IntRes等。

程式碼自動生成

使用程式碼自動生成，一是為了提高編碼的效率，二是避免在執行期大量使用反射，通過在編譯期利用反射生成輔助類和方法以供執行時使用。

註解處理器的處理步驟主要有以下：

  1. 在java編譯器中構建
  2. 編譯器開始執行未執行過的註解處理器
  3. 迴圈處理註解元素(Element)，找到被該註解所修飾的類，方法，或者屬性
  4. 生成對應的類，並寫入檔案
  5. 判斷是否所有的註解處理器都已執行完畢，如果沒有，繼續下一個註解處理器的執行(回到步驟1)

註解處理器流程

Butterknife註解處理器的例子

Butterknife的註解處理器的工作方式如下：

  1. 定義一個非私有的屬性變數
  2. 新增該屬性變數的註解和傳入id
  3. 呼叫Butterknife.bind(..)方法。

當你點選Android Studio的Build按鈕時，Butterknife先是按照上述步驟生成了對應的輔助類和方法。在程式碼執行到bind(..)方法時，Butterknife就去呼叫之前生成的輔助類方法，完成對被註解元素的賦值操作。

自定義註解處理器

瞭解了基本的知識點後，我們應該嘗試去使用這些技巧。 接下來是實踐時間，我們來開發一個簡單的例子，利用註解處理器來自動產生隨機數字和隨機字串。

  1. 首先建立一個project。
  2. 建立lib_annotations， 這是一個純java的module，不包含任何android程式碼，只用於存放註解。
  3. 建立lib_compiler， 這同樣是一個純java的module。該module依賴於步驟2建立的module_annotation,處理註解的程式碼都在這裡，該moduule最終不會被打包進apk，所以你可以在這裡匯入任何你想要的任意大小依賴庫。
  4. 建立lib_api, 對該module不做要求，可以是android library或者java library或者其他的。該module用於呼叫步驟3生成的輔助類方法。

lib_annotations & lib_compiler

專案結構

1. 新增註解

在lib_annotations中新增兩個註解：RandomString, RandomInt，分別用於生成隨機數字和隨機字串:

@Retention(CLASS)
@Target(value = FIELD)
public @interface RandomString {
}
複製程式碼
@Retention(CLASS)
@Target(value = FIELD)
public @interface RandomInt {
    int minValue() default 0;
    int maxValue() default 65535;
}
複製程式碼
  • @interface 自定義註解，使用 @interface 作為類名修飾符
  • @Target 該註解所能修飾的元素型別，可選型別如下：
public enum ElementType {
    TYPE, //類
    FIELD, //屬性
    METHOD, //方法
    PARAMETER, //引數
    CONSTRUCTOR, //建構函式
    LOCAL_VARIABLE, 
    ANNOTATION_TYPE,
    PACKAGE,
    TYPE_PARAMETER,
    TYPE_USE;

    private ElementType() {
    }
}
複製程式碼
  • @Retention 該註解的保留策略，有三種選項：
public enum RetentionPolicy {
    SOURCE, //被編譯器所忽略

    CLASS, //被編譯器保留至類檔案，但不會保留至執行時

    RUNTIME //保留至類檔案，且保留至執行時，能在執行時反射該註解修飾的物件
}
複製程式碼

2. 註解處理器

真正處理註解並生成程式碼的操作都在這裡。 在寫程式碼之前我們需要先匯入兩個重要的庫，以及我們的註解模組：

compile 'com.google.auto.service:auto-service:1.0-rc4'
compile 'com.squareup:javapoet:1.9.0'
implementation project(':lib_annotations')
複製程式碼

新建類RandomProcessor.java:

@AutoService(Processor.class)
public class RandomProcessor extends AbstractProcessor{

    @Override
    public synchronized void init(ProcessingEnvironment processingEnvironment) {
        super.init(processingEnvironment);
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        return super.getSupportedSourceVersion();
    }

    @Override
    public Set<String> getSupportedAnnotationTypes() {
        return super.getSupportedAnnotationTypes();
    }

    @Override
    public boolean process(Set<? extends TypeElement> set, RoundEnvironment roundEnvironment) {
        return false;
    }
}
複製程式碼
  • @AutoService @AutoService(Processor.class)會告訴編譯器該註解處理器的存在，並在編譯時自動在META-INF/services下生成javax.annotation.processing.Processor檔案，檔案的內容為
com.rhythm7.lib_compiler.RandomProcessor
複製程式碼

也就是說，你所宣告的註解處理器都會在被寫入這個配置檔案中。 這樣子，當外部程式裝載這個模組的時候，就能通過該模組的jar包下的META-INF/services下找到具體的註解處理器的實現類名，並載入例項化，完成模組的注入。 註解處理器需要實現AbstractProcessor介面，並實現對應的方法

  • init() 可選 在該方法中可以獲取到processingEnvironment物件，藉由該物件可以獲取到生成程式碼的檔案物件, debug輸出物件，以及一些相關工具類

  • getSupportedSourceVersion() 返回所支援的java版本，一般返回當前所支援的最新java版本即可

  • getSupportedAnnotationTypes() 你所需要處理的所有註解，該方法的返回值會被process()方法所接收

  • process() 必須實現 掃描所有被註解的元素，並作處理，最後生成檔案。該方法的返回值為boolean型別，若返回true,則代表本次處理的註解已經都被處理，不希望下一個註解處理器繼續處理，否則下一個註解處理器會繼續處理。

初始化

較詳細程式碼如下:

private static final List<Class<? extends Annotation>> RANDOM_TYPES
        = Arrays.asList(RandomInt.class, RandomString.class);

private Messager messager;
private Types typesUtil;
private Elements elementsUtil;
private Filer filer;

private TypeonProcess()per.init(processingEnv);
    messager = processingEnv.getMessager(); 
    typesUtil = processingEnv.getTypeUtils();
    elementsUtil = processingEnv.getElementUtils();
    filer = processingEnv.getFiler();
}

@Override
public SourceVersion getSupportedSourceVersion() {
    return SourceVersion.latestSupported();
}

@Override
public Set<String> getSupportedAnnotationTypes() {
    Set<String> annotations = new LinkedHashSet<>();

    for (Class<? extends Annotation> annotation : RANDOM_TYPES) {
        annotations.add(annotation.getCanonicalName());
    }
    return annotations;
}
複製程式碼

處理註解

在process()方法中執行以下操作：

  1. 掃描所有註解元素，並對註解元素的型別做判斷
for (Element element : roundEnv.getElementsAnnotatedWith(RandomInt.class)) {
    //AnnotatedRandomInt是對被RandomInt註解的Elment的簡單封裝
    AnnotatedRandomInt randomElement = new AnnotatedRandomInt(element);
    messager.printMessage(Diagnostic.Kind.NOTE, randomElement.toString());
    //判斷被註解的型別是否符合要求
    if (!element.asType().getKind().equals(TypeKind.INT)) { 
        messager.printMessage(Diagnostic.Kind.ERROR, randomElement.getSimpleClassName().toString() + "#"
          + randomElement.getElementName().toString() + " is not in valid type int");
    }
  
    //按被註解元素所在類的完整類名為key將被註解元素儲存進Map中，後面會根據key生成類檔案
    String qualifier = randomElement.getQualifiedClassName().toString();
    if (annotatedElementMap.get(qualifier) == null) {
        annotatedElementMap.put(qualifier, new ArrayList<AnnotatedRandomElement>());
    }
    annotatedElementMap.get(qualifier).add(randomElement);
}
複製程式碼

生成類檔案

將之前以註解所在類為key的map遍歷，並以key值為分組生成類檔案。

for (Map.Entry<String, List<AnnotatedRandomElement>> entry : annotatedElementMap.entrySet()) {
    MethodSpec constructor = createConstructor(entry.getValue());
    TypeSpec binder = createClass(getClassName(entry.getKey()), constructor);
    JavaFile javaFile = JavaFile.builder(getPackage(entry.getKey()), binder).build();
    javaFile.writeTo(filer);
}
複製程式碼

生成類、建構函式、程式碼段以及檔案都是利用到了javapoet依賴庫。當然你也可以選擇拼接字串和自己用檔案IO寫入，但是用javapoet要更方便得多。

private MethodSpec createConstructor(List<AnnotatedRandomElement> randomElements) {
    AnnotatedRandomElement firstElement = randomElements.get(0);
    MethodSpec.Builder builder = MethodSpec.constructorBuilder()
            .addModifiers(Modifier.PUBLIC)
            .addParameter(TypeName.get(firstElement.getElement().getEnclosingElement().asType()), "target");
    for (int i = 0; i < randomElements.size(); i++) {
        addStatement(builder, randomElements.get(i));
    }
    return builder.build();
}

private void addStatement(MethodSpec.Builder builder, AnnotatedRandomElement randomElement) {
    builder.addStatement(String.format(
            "target.%1$s = %2$s",
            randomElement.getElementName().toString(),
            randomElement.getRandomValue())
    );
}

private TypeSpec createClass(String className, MethodSpec constructor) {
    return TypeSpec.classBuilder(className + "_Random")
            .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
            .addMethod(constructor)
            .build();
}

private String getPackage(String qualifier) {
    return qualifier.substring(0, qualifier.lastIndexOf("."));
}

private String getClassName(String qualifier) {
    return qualifier.substring(qualifier.lastIndexOf(".") + 1);
}
複製程式碼

通過以上幾行程式碼，建立了類檔案。在類的建構函式中新增引數(target), 併為每一個被註解元素新增語句"target.%1$s = %2$s"，最後通過javaFile.writeTo(filer)完成檔案寫入。

3. 呼叫生成類的方法

在lib_api中新建一個類：RandomUtil.java，新增註入方法：

public static void inject(Object object) {
    Class bindingClass = Class.forName(object.getClass().getCanonicalName() + "_Random"); 
    Constructor constructor = bindingClass.getConstructor(object.getClass());
    constructor.newInstance(object);
}
複製程式碼

這裡利用反射找到了以“Object類名_Random”命名的生成類，並呼叫它的構造方法。而在我們之前的註解處理器中，我們已在生成類的構造方法中實現了屬性的賦值操作。

4. 使用生成類

在app module中依賴剛才建立的庫：

implementation project(':lib_annotations')
implementation project(':lib_api')
annotationProcessor project(':lib_compiler')
複製程式碼

在Activity中的使用

public class MainActivity extends AppCompatActivity {
    @RandomInt(minValue = 10, maxValue = 1000)
    int mRandomInt;

    @RandomString
    String mRandomString;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        RandomUtil.inject(this);

        Log.i("RandomInt ==> ", mRandomInt + "");
        Log.i("RandomString ==> ", mRandomString);
    }
}
複製程式碼

編譯，執行，檢視結果：

RandomInt ==>: 700
RandomString ==>: HhRayFyTtt
複製程式碼

被註解的元素成功被自動賦值，說明注入成功。

完整的demo地址

原文地址

除錯

註解處理器的debug跟普通的程式碼debug有點不同：

在當前工程路徑下輸入命令

gradlew --no-daemon -Dorg.gradle.debug=true :app:clean :app:compileDebugJavaWithJavac
複製程式碼

並在Edit Configurations中新新增一個遠端配置(remote)，名字隨意，埠為5005。 然後點選debug按鈕，就可以連線上遠端偵錯程式進行Annotation的除錯了。

遠端除錯annotation processor

相關文章