ASM 字节码插桩与 AGP Instrumentation API 实战：彻底告别 Transform API

字节码插桩是在 .class 生成之后、DEX 生成之前修改程序结构的技术。它可以用于埋点、性能追踪、权限检查、日志注入、方法耗时统计、测试覆盖率等场景。

早期 Android 工程常用 Transform API 拦截整条 class 流。现代 AGP 已经废弃这套模型，推荐使用 Instrumentation API，让插件以更精细、更增量、更受控的方式接入字节码处理。

可以把旧 Transform API 想象成在工厂总出口拦下一整车货，重新拆箱检查；Instrumentation API 更像在生产线上为特定零件安装检测工位，只处理自己声明要处理的 class。

ASM 处理的是什么

Kotlin/Java 编译后产物是 JVM class 文件。ASM 可以读取 class 文件结构，并通过 visitor 模型修改它：

.class
  |
  v
ClassReader
  |
  v
ClassVisitor / MethodVisitor
  |
  v
ClassWriter
  |
  v
modified .class

一个方法耗时插桩通常会在方法入口和出口插入字节码：

原始方法:
  method()
    real code

插桩后:
  method()
    start = System.nanoTime()
    try {
      real code
    } finally {
      report(System.nanoTime() - start)
    }

ASM 的难点不是 API 调用，而是 JVM 字节码约束：操作数栈、局部变量表、异常表、StackMapFrame 都必须保持合法。插入一条指令很容易，保持 class verifier 通过才是关键。

Transform API 的问题

旧 Transform API 常见问题：

• 粒度粗，容易全量处理所有 class。
• 增量状态复杂，插件作者容易写错。
• 多个 transform 顺序和输出目录难管理。
• 直接操作 AGP intermediates，和 AGP 内部实现强耦合。
• configuration cache 和 build cache 适配困难。

这些问题在大型工程里会直接变成构建慢、偶发坏包、升级 AGP 崩溃。

Instrumentation API 的接入方式

现代 AGP 提供基于 AsmClassVisitorFactory 的 API：

abstract class TraceClassVisitorFactory :
    AsmClassVisitorFactory<TraceParameters> {

    override fun createClassVisitor(
        classContext: ClassContext,
        nextClassVisitor: ClassVisitor
    ): ClassVisitor {
        return TraceClassVisitor(nextClassVisitor)
    }

    override fun isInstrumentable(classData: ClassData): Boolean {
        return classData.className.startsWith("club/zerobug/")
    }
}

在 variant 中注册：

androidComponents {
    onVariants { variant ->
        variant.instrumentation.transformClassesWith(
            TraceClassVisitorFactory::class.java,
            InstrumentationScope.PROJECT
        ) { params ->
            params.enabled.set(true)
        }

        variant.instrumentation.setAsmFramesComputationMode(
            FramesComputationMode.COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
        )
    }
}

这里的关键是：插件声明处理范围、参数和 frame 计算策略，由 AGP 把它插入正确的 class transform 管线。

Scope 决定处理边界

InstrumentationScope 常见选择：

埋点、日志、性能追踪通常优先从 PROJECT 开始。处理第三方依赖 class 容易触发 license、兼容性、签名、重复插桩等问题，也会显著增加构建时间。

Frame 计算不是细节

JVM class verifier 依赖 StackMapFrame 验证控制流类型安全。插桩修改控制流后，原有 frame 可能不再正确。

AGP 提供 frame 计算模式，插件应根据修改程度选择：

• 只插入简单指令且不改变控制流，成本较低。
• 改变 try/catch、分支、局部变量结构，需要更完整 frame 计算。

如果 frame 不正确，可能在构建期报 VerifyError，也可能在特定 Android 版本运行时崩溃。字节码工程最危险的地方就在于错误不一定立刻暴露。

插桩任务的增量与缓存

一个健康插桩插件必须：

• isInstrumentable 精确过滤 class。
• 参数使用 Property 声明，避免读取全局状态。
• 输出确定，不写时间戳或随机 ID。
• 不重复插桩同一方法。
• 对 synthetic、bridge、lambda、coroutine state machine 保持谨慎。
• 用字节码验证和运行测试覆盖关键路径。

Kotlin 协程尤其需要注意。一个 suspend 函数会被编译成状态机，源码里的一个方法可能变成带 Continuation 参数和状态字段的字节码结构。按源码直觉插入方法入口/出口，可能得不到预期耗时边界。

从 Transform API 迁移

迁移时不要逐行搬旧代码。应重新按 AGP 模型拆分：

1. 明确只处理 project class 还是依赖 class。
2. 把全局开关和参数做成 extension。
3. 用 androidComponents.onVariants 按 variant 注册。
4. 用 AsmClassVisitorFactory 替代手写遍历目录/jar。
5. 用 AGP frame 计算策略替代自管 ClassWriter 细节。
6. 用 Build Scan 比较迁移前后构建耗时和增量行为。

迁移目标不是“旧功能还能跑”，而是让插桩重新回到 AGP 可追踪、可增量、可缓存的管线里。

工程风险与观测清单

ASM 字节码插桩与 AGP Instrumentation API 实战：彻底告别 Transform API 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。

因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。

关键风险矩阵

需要持续观测的指标

• 配置阶段耗时是否随模块数量线性或超线性增长。
• 单次本地 debug 构建的关键路径任务是谁。
• CI clean build 与 incremental build 的耗时差距。
• 远程 Build Cache 的 hit rate、miss 原因和下载耗时。
• Configuration Cache 的命中率和失效原因。
• Kotlin/Java 编译任务是否被不相关资源或依赖变化触发。
• 资源合并、DEX、R8、打包任务是否在小改动后全量重跑。
• 自定义插件是否提前实现了无关任务。
• 构建日志中是否出现未声明输入、重叠输出、deprecated API。
• 发布产物是否能追溯到唯一的源码提交、依赖锁和构建扫描。
• 失败是否可稳定复现，还是只在特定机器、特定并发下出现。
• 变更是否影响开发构建、测试构建和发布构建三条路径。

回滚与降级策略

• 构建逻辑变更与业务代码变更分开提交，便于二分定位。
• Gradle、AGP、Kotlin、JDK 升级必须保留兼容矩阵和回滚版本。
• 新插件能力先只接入一个低风险模块，再扩大到全工程。
• 远程缓存先 pull 后 push，确认产物稳定后再允许 CI 写入。
• 新增插桩、生成代码、资源处理逻辑必须提供开关。
• 发布构建失败时，优先回滚构建逻辑版本，而不是清空所有缓存碰运气。
• 对 CI 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
• 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。

最小验证矩阵

审计问题

1. 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
2. 它是否读取了没有声明为输入的文件、环境变量或系统属性。
3. 它是否在配置阶段执行了本应放到任务动作里的工作。
4. 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
5. 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
6. 它是否把权限、密钥、签名文件路径写进了仓库。
7. 它是否破坏了并发执行，例如多个任务写同一个目录。
8. 它是否能在失败时输出足够日志，帮助定位根因。
9. 它是否能通过一个开关降级，避免阻塞全工程构建。
10. 它是否有最小复现样例或 TestKit/集成测试覆盖。
11. 它是否会让下游模块承担不必要的依赖或任务成本。
12. 它是否能在升级 Gradle/AGP 后继续工作，还是依赖内部 API。

反模式清单

• 用 clean 掩盖输入输出声明错误。
• 用 afterEvaluate 修补本可以用 Provider 表达的依赖关系。
• 用动态版本解决依赖冲突，却让构建不可复现。
• 把所有公共配置塞进一个巨型 convention plugin。
• 在 debug 构建默认开启 release 级别的重型优化。
• 在任务动作里读取 project 或全局 configuration。
• 在多个任务中共享同一个临时目录。
• 缓存命中率异常时只重启 CI，不分析 miss reason。
• 把构建扫描链接当作可选附件，而不是性能回归证据。
• 用本地 IDE 成功运行证明 CI 发布链路安全。

最小实操脚本

./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 ASM 字节码插桩与 AGP Instrumentation API 实战：彻底告别 Transform API 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

延伸阅读

• Android Gradle Plugin Instrumentation API
• ASM Project
• Android Improve Build Speed - Transform API Migration Context