AnnotationProcessor 处理器不工作怎么定位?

什么是 Annotation Processor 构建问题

写过自定义注解处理器的老司机们乍一看这个问题觉得挺简单,是的,因为网上基本通篇都在教你怎么打日志,但是你有没有想过如果连日志都打印不出来的时候你怎么定位呢?譬如如下代码:

// 确认 META-INF/services/javax.annotation.processing.Processor 没问题
// 确认构建脚本没问题,确认注解 Bridge 有被使用且有参与构建
@AutoService(Processor.class)
public class TestAnnotationProcessor extends AbstractProcessor {
    public TestAnnotationProcessor() {
        System.out.println("TestAnnotationProcessor constrator");
    }

    @Override
    public synchronized void init(ProcessingEnvironment processingEnvironment) {
        super.init(processingEnvironment);
        System.out.println("TestAnnotationProcessor init");
    }

    @Override
    public Set<String> getSupportedAnnotationTypes() {
        System.out.println("TestAnnotationProcessor getSupportedAnnotationTypes");
        Set<String> supported = new HashSet<String>();
        supported.add(Bridge.class.getCanonicalName());
        return supported;
    }

    @Override
    public boolean process(Set<? extends TypeElement> set, RoundEnvironment roundEnvironment) {
        System.out.println("TestAnnotationProcessor process");
        return true;
    }
}

运行构建后compileReleaseJavaWithJavac过程中没有先吐我 Annotation Processor 的任意一行日志,直接报错找不到我注解处理器产物类引用(即直接进行了 compile class 环节)。

你懵逼吗?反正我懵逼了!打印日志不好使了,哈哈,环境确认没问题,什么鬼,直接越过 Annotation Processor 进行 compile 了。

这时候就需要你稍微深入定位分析(撸javac源码的巨佬请自行飘过),前提就是你需要熟悉下 Annotation Processor 基本原理,然后我们通过一些额外的javac详细日志进行举例分析。

Annotation Processor 机制

注解和注解处理器是 JDK5 引入的机制,主要用来为类、方法、字段和参数等 Java 结构提供额外的信息。譬如常见的@Override就是仅仅对 Java 编译器生效的一个注解。Java 允许我们自定义注解,自定义的注解处理器就是用来处理这些自定义注解的(废话),注解处理器触发时机是由javac来处理的,所以整个javac过程的简要步骤如下图:

在这里插入图片描述

可以看到,javac编译概要图主要分为如下几步:

  1. 把源文件解析为抽象语法树。
  2. 调用已注册的注解处理器。
  3. 如果注解处理器处理过程中生成了新的源文件,编译器重复第 1、2 步,当注解处理器不再生成新的源文件则进入最后一轮。
  4. 进入真正的 compile 字节码环节生成字节码。

如上就是注解处理器的核心机制,有了这个核心机制的认识我们就继续往下探索。

构建工具下 Annotation Processor 的本质

我们日常开发中(无论是 Java 后端还是 Android 移动端)总是多多少少会用到 JDK 提供的annotation processor能力,无论是什么构建工具(Gradle 或者 Maven 等)本质都是通过javac -processorpath命令参数显式指定哪些 Processer,或者显式声明META-INF/services/javax.annotation.processing.Processor来被javac发现并调用的(参见 google 的 AutoService 框架)。

正常情况下我们开发中使用及构建 Annotation Processor 技术都是上面几步走的方案,而且大多数照着网络上抄的都能正常工作,每次只用自己处理 process 就挺香的,因为只要按照规则声明放置,其他的 javac都能自己完美调用。

增强 javac 过程打印暴露问题

要解决一开始说的 Annotation Processor 中自己加的日志都不打印场景问题,我们需要获取一些额外的信息辅助定位。由于直接使用命令行javac的方式是最原始的操作,我们构建一般采用 Gradle,而 Gradle 的本质还是调用javac,所以下面我们以 Gradle 为例来分析如何定位 Annotation Processor 问题。

下面简单粗暴点就是直接在根目录的build.gradle中给所有模块添加参数:

//【工匠若水 加微信 yanbo373131686 联系我,关注微信公众号:码农每日一题  未经允许严禁转载 https://blog.csdn.net/yanbober】

// 参数可选,重点是 -verbose -XprintRounds -XprintProcessorInfo
allprojects {
    gradle.projectsEvaluated {
        tasks.withType(JavaCompile) {
            options.compilerArgs << "-Xlint" << "-verbose" << "-XprintRounds" << "-XprintProcessorInfo" << "-Xmaxerrs" << "100000"
        }
    }
}

你也可以仅仅在自己有注解处理器的模块中添加,与上面一样,只要加给JavaCompile的参数就行。这里的参数其实就是我们平时命令行javac是否的参数,不懂的可以去命令行执行下javac -help观摩下含义吧,如下(JDK8,不同版本 JDK 略有差异):

yan@yanDeMackbookPro:~$ javac -help
用法: javac <options> <source files>
其中, 可能的选项包括:
-g                         生成所有调试信息
......
-verbose                   输出有关编译器正在执行的操作的消息
......
-processor <class1>[,<class2>,<class3>...] 要运行的注释处理程序的名称; 绕过默认的搜索进程
-processorpath <路径>        指定查找注释处理程序的位置
......

至于脚本中其他几个在javac -help中没有的参数可以看下官方文档https://docs.oracle.com/en/java/javase/11/tools/javac.html ,里面详细解释了参数含义。

添加上面参数后一定要将你的构建日志追加到一个磁盘文件中,因为日志会变得非常庞大,同时也变得很容易定位问题。

通过构建日志分析定位问题

执行你的构建任务,完毕后分析定位主要分为如下几个步骤,每一步都是一种场景的定位,循序渐进定位分析即可。

  1. 在你的日志中搜索你的 Processor 类名,譬如TestAnnotationProcessor.class,看到的日志会是如下。
// 如果你的注解处理器在项目中是源码形式的日志
[loading RegularFileObject[/home/user/yan/test/target/classes/cn/yan/test/TestAnnotationProcessor.class]]

// 如果你的注解处理器在项目中是依赖 jar 形式的日志
[loading ZipFileIndexFileObject[....../test.jar(cn/yan/test/TestAnnotationProcessor.class)]]

分析: 如果你的日志中搜不到上面信息,说明你的注解处理器没有被添加到javac的 classpath 中。一般问题就是你的META-INF/services/javax.annotation.processing.Processor声明有问题,javac无法找到你的注解处理器。有些同学可能是通过 google 的 AutoService 来生成META-INF/services/javax.annotation.processing.Processor的,这种情况下也要自己检查是否 OK(譬如之前安卓中 AGP 有一段时间的中间过渡版本就修改了 classpath,需要手动将 compile 改成 annotationProcessor 才行)。

  1. 在你的日志中搜索Round关键字,建议直接搜Round 1:这样的格式容易点,看到的日志会是如下。
Round 1:
        input files: {cn.yan.test.Application, ......, cn.yan.test.UseMarkedAnnotation}
                annotations: [java.lang.Override, cn.yan.annotation.Bridge]
                last round: false

上面日志中的input files:部分是扫到的你的源码,annotations:部分就是扫到你代码中使用了哪些注解,如果你注解处理器声明了要处理这种注解(譬如@cn.yan.annotation.Bridge),则日志如上才是正常的。

分析: 如果你日志中没搜到上面的Round,则说明javac没有触发调用任何注解处理器(无论是你写的还是依赖三方框架的),最大的可疑点就是检查下自己有没有禁用javac注解处理器,也就是确认javac执行时没有-proc:none参数。如果你的日志中有Round,但是input files:annotations:没有你的注解类和使用类,则说明你没有在代码中使用你注解处理器要处理的注解。

  1. 在你的日志中搜索Loaded cn.yan.test.TestAnnotationProcessor关键字,看到的日志会是如下。
[Loaded cn.yan.test.TestAnnotationProcessor from file:/home/user/yan/test/target/classes/cn/yan/test/TestAnnotationProcessor.class]

分析: 如果你看不到上面这行日志,说明你的注解处理器类自己没有被加载成功,为什么没有我也不知道怎么分析了,但是至少说明没加载成功,你可能需要仔细核对哪里不规范或者不合法导致的了。

  1. 上面都排查完了,如果还是找不到问题原因,不妨换个思路,去仔细检查下你参与构建的普通 java 文件,是否存在语法错误或者什么问题(譬如常量没声明等);如果有,解决完了再试试,别问我为什么,我也没有深入研究javac这块源码,只是我遇到过,且也没有异常堆栈信息,最终发现是合并解决冲突后代码少了一个变量声明,就是单纯的越过了 Annotation Processor 过程直接进行 compile to class 流程了)。
这个技能有什么鸟用?

不瞒你说,我也算是老司机了,好些年前 Annotation Processor 就玩的很 6 了,但是最近项目升级构建和 Java8 及 androidX 支持后 merge 了下代码,然后项目中的注解处理器、dataBinding 全部都不工作了,更可气的是,这个不工作是真的很吝啬,什么错误堆栈都没有,大致如下奇葩构建日志:

//【工匠若水 加微信 yanbo373131686 联系我,关注微信公众号:码农每日一题  未经允许严禁转载 https://blog.csdn.net/yanbober】

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':test:compileReleaseJavaWithJavac'.
// 本来这里该先吐我注解处理器内部的日志,然后才继续 javac 编译,实际什么都没吐
> Compilation failed; see the compiler error output for details.
* Exception is:
org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':moffice:compileReleaseJavaWithJavac'.
	at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter.lambda$executeIfValid$1(ExecuteActionsTaskExecuter.java:200)
	......
Caused by: org.gradle.api.internal.tasks.compile.CompilationFailedException: Compilation failed; see the compiler error output for details.
	at org.gradle.api.internal.tasks.compile.JdkJavaCompiler.execute(JdkJavaCompiler.java:57)

Gradle 构建命令已经添加了各种详细参数供查看堆栈和详细日志,但奇妙的事情就是他走到compileReleaseJavaWithJavac就直接出错了,前后没有任何错误提示(有的只是一坨 Gradle 自己的 task 调用链)。我特么大意了,我就同步了下代码,编不过就编不过啊,你倒是提示下问题啊!啥也不提示直接干到 compile class 环节了,跳过了 Annotation Processor 流程,这就很恼火了。好在按照上面方式定位修复了,哈哈。

左侧码走一波啊!

工匠若水 CSDN认证博客专家 开车小能手
代码手艺人,秋名山老司机,开车小能手。专注于移动互联网及嵌入式领域。
微信公众号:码农每日一题
个人微信号:yanbo373131686
写博客不赚钱,就图交个朋友,欢迎来撩,微信更精彩。
已标记关键词 清除标记
©️2020 CSDN 皮肤主题: 程序猿惹谁了 设计师:上身试试 返回首页