第4章 基于APT的编译期检测：AbstractProcessor实现、注解处理、生成检测代码

4.1 原理：为什么编译期检测更可靠

APT（Annotation Processing Tool）在 Java 编译阶段扫描源文件中的注解，并触发自定义的 AbstractProcessor 执行代码生成或校验逻辑。相比运行时通过反射遍历注册表，APT 具有以下优势：

• 零运行时开销：检测逻辑在编译期完成，不侵入 App 启动路径。
• 强制约束：生成的代码直接参与编译，若存在未注销风险可在编译期报错。
• IDE 友好：错误信息可精确指向文件行号，开发阶段即时修正。

针对 LifecycleObserver 未注销问题，APT 可检查被注解的类是否在构造方法或生命周期入口中调用了 removeObserver()，若缺失则生成编译错误或告警代码。

4.2 实现流程

1. 定义注解（如 @CheckLifecycle），标记需要检测的类或方法。
2. 创建 AbstractProcessor 子类，重写 process() 方法。
3. 注册 Processor（通过 META-INF/services 或 Google AutoService）。
4. 在 process() 中扫描被注解元素，解析其方法调用。
5. 基于解析结果生成 Java 源文件（如检测桩代码或编译错误消息）。
6. 配置构建系统（Gradle / Maven）启用注解处理。

整体数据流如下：

4.3 关键代码实现

4.3.1 自定义注解

package com.example.lifecycle.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)    // 保留到 class 文件，供 APT 读取
public @interface CheckLifecycle {
    String message() default "LifecycleObserver may not be unregistered";
}

4.3.2 AbstractProcessor 实现

package com.example.lifecycle.processor;

import com.example.lifecycle.annotation.CheckLifecycle;
import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import javax.tools.Diagnostic;
import java.util.Set;

@SupportedAnnotationTypes("com.example.lifecycle.annotation.CheckLifecycle")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class LifecycleCheckProcessor extends AbstractProcessor {

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        for (Element element : roundEnv.getElementsAnnotatedWith(CheckLifecycle.class)) {
            if (element.getKind() != ElementKind.CLASS) continue;
            TypeElement typeElement = (TypeElement) element;
            // 检查是否实现 LifecycleObserver 或类似接口（示例简化）
            boolean hasRemoveObserver = checkRemoveObserverCall(typeElement);
            if (!hasRemoveObserver) {
                String msg = element.getAnnotation(CheckLifecycle.class).message();
                processingEnv.getMessager().printMessage(
                    Diagnostic.Kind.ERROR,
                    msg + " in class: " + typeElement.getQualifiedName(),
                    element);
            } else {
                // 生成桩代码，注入移除检测逻辑（略）
                generateRegistrationCheckCode(typeElement);
            }
        }
        return true;
    }

    private boolean checkRemoveObserverCall(TypeElement type) {
        // 遍历所有方法，查找 removeObserver 调用（示例伪逻辑）
        for (Element enclosed : type.getEnclosedElements()) {
            if (enclosed instanceof ExecutableElement) {
                // 实际可通过 Elements API 或第三方库解析方法体
                String body = enclosed.toString(); // 简化示意
                if (body.contains("removeObserver")) return true;
            }
        }
        return false;
    }

    private void generateRegistrationCheckCode(TypeElement type) {
        // 使用 Filer 生成 Java 源文件，例如创建一个静态检查类
    }
}

4.3.3 注册处理器（META-INF/services）

// 文件：src/main/resources/META-INF/services/javax.annotation.processing.Processor
// 内容：
com.example.lifecycle.processor.LifecycleCheckProcessor

也可以使用 Google AutoService 注解 @AutoService(Processor.class) 自动生成注册文件。

4.4 构建配置（Gradle）

// app/build.gradle
android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    // 注解库（提供给 APT 使用，不打包到 APK）
    implementation project(':lifecycle-annotation')
    annotationProcessor project(':lifecycle-processor')
    // 如果使用 Kotlin，则替换为 kapt
}

4.5 调试与验证

4.6 常见错误与解决方案

4.7 性能与稳定性优化

• 缓存解析结果：对同一个 TypeElement 的多次解析结果可放入 Map<TypeElement, Boolean> 中，避免重复遍历方法体。
• 最小化 Filer 调用：生成文件是 I/O 操作，尽量合并逻辑，只在确认需要生成时调用 createSourceFile()。
• 避免使用反射：APT 阶段不能使用运行时反射，仅依赖 javax.lang.model 静态类型信息。
• 多轮处理（Round）：如果 Processor 需要依赖其他处理器生成的结果，需注意 RoundEnvironment.processingOver() 并善用 SupportedOptions。
• 增量编译适配：Gradle 增量注解处理要求 Processor 声明 @SupportedOptions("org.gradle.annotation.processing.incremental")，并妥善实现 getSupportedOptions()。