深入 Android 字节码插桩全链路：从 ASM ClassVisitor 到 Gradle Plugin 的编译期 AOP 工程实践
做 APM SDK 时碰到过一个棘手问题：需要无侵入地统计每个页面 onCreate 的耗时，但业务方不愿意在每个 Activity 里手动埋点。运行时 Hook 的方案在 Android 9+ 上被 Hidden API 限制卡得死死的，最后只能把目光转向编译期字节码插桩。
这条路走通后发现，编译期 AOP 能做的事远不止性能监控。本文梳理从 Gradle Plugin 入口到 ASM 字节码操控的完整链路，以及三个实际落地场景。
插桩入口：从 Transform 到 AsmClassVisitorFactory
Gradle 插桩的核心问题是：在编译的哪个阶段、以什么方式拿到字节码。
AGP 7.0 之前用的是 Transform API，它本质上是一个任务链，在 class 转 dex 之前拦截字节码：
// AGP 4.x Transform 方式
class MyTransform extends Transform {
@Override
String getName() { return "bytecode-hook" }
@Override
void transform(TransformInvocation invocation) {
invocation.inputs.each { input ->
input.directoryInputs.each { dir ->
// 遍历 .class 文件，用 ASM 处理
}
}
}
}这套 API 的问题很明显：增量编译支持差，每次都要遍历全量文件，大项目的编译速度很难扛住。Transform 在 AGP 7.0 被标记废弃，8.0 彻底移除。
替代方案是 AsmClassVisitorFactory，直接注册到 AGP 的字节码处理管线中：
// AGP 7.0+ 推荐方式
abstract class TimingClassVisitorFactory : AsmClassVisitorFactory<InstrumentationParameters.None> {
override fun createClassVisitor(
classContext: ClassContext,
nextClassVisitor: ClassVisitor
): ClassVisitor {
return TimingClassVisitor(nextClassVisitor)
}
override fun isInstrumentable(classData: ClassData): Boolean {
// 只处理目标包下的类，减少不必要的遍历
return classData.className.startsWith("com/example/app")
}
}注册方式也从 android.registerTransform() 变成了声明式：
class MyPlugin : Plugin<Application> {
override fun apply(project: Project) {
project.extensions.getByType(ApplicationAndroidComponentsExtension::class.java)
.onVariants { variant ->
variant.instrumentation.transformClassesWith(
TimingClassVisitorFactory::class.java,
InstrumentationScope.ALL
) {}
variant.setAsmFramesComputationMode(FramesComputationMode.COMPUTE_FRAMES)
}
}
}isInstrumentable 是性能的关键——在这里做类名过滤，能省掉大量无意义的 ClassVisitor 创建。实际项目中我会把白名单写在 gradle.properties 里动态读取，而不是硬编码包名。
ASM 核心：Visitor 模式下的字节码操控
ASM 的设计本质是事件驱动的 Visitor 链。ClassReader 读取字节码并依次回调 ClassVisitor 的各个 visit 方法，你在链中插入自己的 ClassVisitor 就能拦截和修改字节码。
最常用的两个钩子：
class MethodTimingVisitor(
api: Int,
next: ClassVisitor,
private val targetMethods: Set<String>
) : ClassVisitor(api, next) {
override fun visitMethod(
access: Int, name: String, descriptor: String,
signature: String?, exceptions: Array<out String>?
): MethodVisitor {
val mv = super.visitMethod(access, name, descriptor, signature, exceptions)
return if (name in targetMethods) {
TimingMethodVisitor(api, mv, access, name, descriptor)
} else mv
}
}关键设计：在 visitMethod 中决定是否包装 MethodVisitor。如果方法不在目标列表中，直接返回父类的 MethodVisitor，零开销跳过。
MethodVisitor 里做具体的代码注入：
class TimingMethodVisitor(
api: Int, mv: MethodVisitor,
private val access: Int, private val name: String, private val desc: String
) : MethodVisitor(api, mv) {
override fun visitCode() {
// 方法入口：插入 startTime = System.currentTimeMillis()
mv.visitMethodInsn(INVOKESTATIC, "java/lang/System", "currentTimeMillis", "()J", false)
val startLocal = if ((access and ACC_STATIC) != 0) 0 else 1
mv.visitVarInsn(LSTORE, startLocal)
super.visitCode()
}
override fun visitInsn(opcode: Int) {
// RETURN/ARETURN 等返回指令前插入耗时计算
if (opcode in Opcodes.IRETURN..Opcodes.RETURN || opcode == Opcodes.ATHROW) {
mv.visitMethodInsn(INVOKESTATIC, "java/lang/System", "currentTimeMillis", "()J", false)
// 与入口时间做差，上报
// ...
}
super.visitInsn(opcode)
}
}这里踩过一个坑：静态方法局部变量索引从 0 开始，实例方法从 1 开始（0 是 this）。写死索引会导致静态方法注入后校验失败，用 (access and ACC_STATIC) != 0 动态判断。
实战：三场景统一插桩框架
把以上机制抽象后，我搭了一套可配置的插桩框架，覆盖三个场景。
场景一：页面性能监控。 对 Activity 和 Fragment 的生命周期方法注入计时。visitCode 记录时间戳，visitInsn 在 RETURN 指令前计算耗时，通过一个工具类回调给 APM 模块。业务代码零侵入，接入成本为一行 plugin 依赖。
场景二：隐私合规日志注入。 对调用敏感 API 的方法（如 getDeviceId、getMacAddress）在调用前后插入日志：
// 目标：在 TelephonyManager.getDeviceId() 前插入日志
override fun visitMethodInsn(
opcode: Int, owner: String, name: String, descriptor: String, isInterface: Boolean
) {
if (owner == "android/telephony/TelephonyManager" && name == "getDeviceId") {
// 调用前插入 Logger.log("getDeviceId 被调用")
mv.visitLdcInsn("getDeviceId 被调用")
mv.visitMethodInsn(INVOKESTATIC, "com/example/Logger", "log",
"(Ljava/lang/String;)V", false)
}
super.visitMethodInsn(opcode, owner, name, descriptor, isInterface)
}相比运行时 Hook，编译期注入不依赖反射，不受 Hidden API 限制，在 Android 14 上照样跑。
场景三：方法耗时统计。 对标注了自定义注解 @Trace 的方法自动注入打点逻辑。AnnotationVisitor 读取注解信息，决定是否包装 MethodVisitor，实现声明式埋点。
三个场景共用一套 ClassVisitor 链，通过配置决定注入策略，不同变体（debug/release）可以启用不同规则。
工程化踩坑
实际落地中踩过的几个坑：
Stack Map Frame 的计算。 Java 7+ 的字节码在跳转指令处需要 stack map frame。ASM 插桩改变了字节码结构后，frame 信息可能失效。解决方案是在注册时设置 setAsmFramesComputationMode(FramesComputationMode.COMPUTE_FRAMES)，让 ASM 自动重算，代价是编译时间增加约 5%-10%。
多 Module 并行编译的竞态。 如果插桩逻辑依赖全局状态（比如方法 ID 生成器），并行编译会出问题。我的做法是把状态收敛到 Variant 级别，利用 variant.instrumentation 的隔离性保证安全。
增量编译的缓存失效。 isInstrumentable 返回值变化时 AGP 会自动触发重新编译，但如果你在 ClassVisitor 内部读取了外部文件（比如配置文件），变化不会被感知。做法是把配置文件的 hash 作为 InstrumentationParameters 的一部分传入，这样配置变更时会触发缓存失效。
编译期 AOP 本质是用编译时间换运行时效率和代码整洁度。如果你的场景需要极致编译速度，只对核心模块开启插桩；如果追求零侵入的监控能力，这套方案值得投入。