andoridAPT使用

前言

APT的概念大家应该不会陌生, 而且在很多第三方库中都有使用到, 最有名的应该就是ButterKnife了. 这里基础概念就略过了, 本篇主要是着重在怎么编写自己的注解处理器, 以及一些踩到的坑.

开始

一般要实现编译器注解处理生成, 需要新建两个module, 分别存放自定义的Annotation和对应Annotation的处理器.

自定义注解

我们先新建存在自定义注解的module, 注意, 这里建议新建java-library, 便于本地调试时给存放处理器的module依赖使用, 对应gradle配置如下

apply plugin: 'java-library'

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

sourceCompatibility = "1.8"
targetCompatibility = "1.8"

自定义一个新的注解

@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface TestAnnotation {
    String value();
}

这里Retention注解表示设置注解保留时机, 需要传递的是RetentionPolicy枚举类型, 值分别有:

SOURCE: 编译器时就会抛弃注解
CLASS: 注解保留到编译器, 运行期会去除
RUNTIME: 注解保留到运行期, 编译器时也会存在

Target表示注解适用的上下文, 即他的目标修饰类型, 可以传数组,值应该为ElementType,枚举各个值的含义可以看官方文档, 我们主要用到比较多的应该是

TYPE: 类, 接口(包括注解类型)或者枚举的声明
METHOD: 方法声明
FIELD: 字段声明, 包括枚举常量
LOCAL_VARIABLE: 局部变量声明
CONSTRUCTOR: 构造函数的声明

注解处理器

同样需要新建一个java-library, 对应gradle的配置如下

apply plugin: 'java-library'
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    // 协助我们生成类文件
    implementation 'com.squareup:javapoet:1.11.0'
    // 自定义注解的库
    implementation project(':anno')
    // 协助自动注册META-INF
    implementation 'com.google.auto.service:auto-service:1.0-rc4'
}

然后开始编写处理器, 关于如何使用JavaPoet, 建议看下官方文档, 在这里不再细说.最后通过Filer来进行文件的写入.

// AutoService注解协助自动生成META-INF服务, 提供项目识别自定义的注解处理器
@AutoService(Processor.class)
public class TestProcessor extends AbstractProcessor {
    private Filer mFiler;
    private Messager messager;
    /**
     * init()方法可以初始化拿到一些使用的工具，比如文件相关的辅助类 Filer;元素相关的辅助类Elements;日志相关的辅助类Messager;
     * @param processingEnv
     */
    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
        mFiler = processingEnv.getFiler();
        messager = processingEnv.getMessager();
    }

    /**
     * @return 返回Java版本
     * 也可以通过@SupportedSourceVersion来指定, 如果没有设置默认返回的是JDK1.6版本
     */
    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latest();
    }

    /**
     *
     * @return 支持的注解类型
     * 即是这个处理器是需要注册在哪几个注解上的, 也可以通过@SupportedAnnotationTypes来指定
     */
    @Override
    public Set<String> getSupportedAnnotationTypes() {
        LinkedHashSet<String> types = new LinkedHashSet<>();
        types.add(TestAnnotation.class.getCanonicalName());
        return types;
    }

    /**
     * 一个Processor的main函数
     * @param annotations 请求被处理的注解
     * @param roundEnv 可以用来查询特定注解的被注解元素
     * @return true 被当前处理器处理; false 可能被其他同样声明支持对应注解的处理器用来处理
     */
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        HashMap<String, String> nameMap = new HashMap<>();
        Set<? extends Element> annotationElements = roundEnv.getElementsAnnotatedWith(TestAnnotation.class);
        for (Element element: annotationElements
             ) {
            TestAnnotation annotation = element.getAnnotation(TestAnnotation.class);
            String name = annotation.value();
            nameMap.put(name, element.getSimpleName().toString());
        }
        generateJavaFile(nameMap);
        return true;
    }

    private void generateJavaFile(Map<String, String> nameMap){
        // 通过javaPoet生成java文件
    }
}

错误信息

由于注解处理器是JVM在编译期进行运行, 所以普通的Log无法用来提示我们来打印一些日志或者用来提示错误信息.在Processor中, 当执行初始化的时候, 会传进来一个ProcessingEnvironment参数, 在上方代码注释内我也写了, 他会提供一些我们需要的参数, 比如Messager一个用来报告错误, 警报或者其他通知的工具, 它可以用来提醒第三方使用注解的开发者们来处理相关的错误.它有多个重载函数, 用于设置提醒到哪个地步, 具体可以自己尝试下.

public interface Messager {
    void printMessage(Diagnostic.Kind kind, CharSequence msg);

    void printMessage(Diagnostic.Kind kind, CharSequence msg, Element e);

    void printMessage(Diagnostic.Kind kind, CharSequence msg, Element e, AnnotationMirror a);

    /**
     * @param kind 通知类型
     * @param msg  内容
     * @param e    注解元素
     * @param a    包含注解的值得注解
     * @param v    提示到注解的值使用位置
     */
    void printMessage(Diagnostic.Kind kind,
                      CharSequence msg,
                      Element e,
                      AnnotationMirror a,
                      AnnotationValue v);
}

使用自定义注解

当我们需要使用的时候, 那么就跟常见的几个第三方库的使用(比如Dagger之类)是一样的.

// 依赖管理自定义注解的库
implementation project(':anno')
// apt配置注解处理库
annotationProcessor project(':aptlib')

值得注意的是如果你使用的是kotlin开发使用到对应的注解, 那么首先需要依赖kapt插件, 然后以kapt替换annotationProcessor添加注解处理库, 当项目里有Java文件使用到注解的时候, kapt也会兼顾到.

apply plugin: 'kotlin-kapt'
dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')

    implementation project(':anno')
    kapt project(':aptlib')

}

Tips

我们在开始的时候, 谈到注解的声明和处理器需要分别放在不同的module里, 原因是因为, 如果放在一个module里, 那么应用项目在依赖的时候, 就会变成

implementation project(':aptlib')
annotationProcessor project(':aptlib')

而不论是我们使用的AbstractProcessor还是JavaPoet库, 都是依赖于JDK进行编译的, 当应用项目依赖于(implementation)这个库的时候, AS就会默认用SDK来进行编译, 导致编译器提示部分类无法加载, 所以我们才需要分成两个module, 保证到进行逻辑处理的处理器可以不会通过implementation被依赖进项目中.相关可以看看相关的issue的说明