众所周知, Transform 接口在 AGP8.0 中已经被移除了, 而以往的大量工程实践都需求运用该接口结合 ASM 对字节码进行操作, 例如: 代码插桩, 代码替换等.

接下来将探索在 AGP8.0 中有哪些计划能够替代 Transform 到达相同的效果.

一. Instrumentation

Instrumentation 作为 Google 首推的 Transform 替代计划, 只需求完成 AsmClassVisitorFactory 接口即完成对字节码处理.

原 Transform 处理流程:

flowchart LR
input[Jar/classes]
transform1([Transform])
intermediate1[Jar/classes]
transform2([Transform])
output[Jar/classes]
input --> transform1
transform1 --> intermediate1
intermediate1 --> transform2
transform2 --> output

现 Instrumentation 处理流程:

flowchart LR
input[Jar/classes]
transform1([ClassVisitor])
transform2([ClassVisitor])
output[Jar/classes]
input --> transform1
transform1 --> transform2
transform2 --> output

相较于 Transform 处理流程, Instrumentation 流程免去对中间产品的读写, 而且一定是以 Jar/classes 文件为单位的增量处理, 使得全量编译和增量编译速度都有较大的提升.

插桩实践

下面以完成一个的 TraceAsmClassVisitorFactory 为例, 实践如何运用 Instrumentation 相关接口.

TraceAsmClassVisitorFactory 将在一切方法进口和出口插桩 Trace#beginSection 和 Trace#endSection 代码.

TraceClassVisitor

class TraceClassVisitor(
    api: Int,
    next: ClassVisitor
) : ClassVisitor(api, next) {
    private var className: String? = null
    // 开端处理 class 文件时, 记载当时 class 的姓名
    override fun visit(
        version: Int,
        access: Int,
        name: String?,
        signature: String?,
        superName: String?,
        interfaces: Array<out String>?
    ) {
        className = name
        super.visit(version, access, name, signature, superName, interfaces)
    }
    // 遍历 method 时, 运用 MethodVisitor 参加插桩逻辑
    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 TraceMethodVisitor(api, mv, access, name, descriptor)
    }
    private inner class TraceMethodVisitor(
        api: Int,
        methodVisitor: MethodVisitor?,
        access: Int,
        name: String?,
        descriptor: String?
    ) : AdviceAdapter(
        api,
        methodVisitor,
        access,
        name,
        descriptor
    ) {
        // method 进口刺进 `Trace#beginSection` 代码
        override fun onMethodEnter() {
            mv.visitLdcInsn("$className#$name")
            mv.visitMethodInsn(
                Opcodes.INVOKESTATIC,
                "android/os/Trace",
                "beginSection",
                "(Ljava/lang/String;)V",
                false
            )
        }
        // method 出口刺进 `Trace#endSection` 代码
        override fun onMethodExit(opcode: Int) {
            mv.visitMethodInsn(
                INVOKESTATIC,
                "android/os/Trace",
                "endSection",
                "()V",
                false
            )
        }
    }
}

TraceAsmClassVisitorFactory

abstract class TraceAsmClassVisitorFactory: AsmClassVisitorFactory<InstrumentationParameters.None> {
    // 对一切 class 文件都进行插桩处理
    override fun isInstrumentable(classData: ClassData): Boolean {
        return true
    }
    // 遍历 class 时, 运用 ClassVisitor 参加插桩逻辑
    override fun createClassVisitor(
        classContext: ClassContext,
        nextClassVisitor: ClassVisitor
    ): ClassVisitor {
        val apiVersion = instrumentationContext.apiVersion.get()
        return TraceClassVisitor(apiVersion, nextClassVisitor)
    }
}

TraceTransformPlugin

abstract class TraceTransformPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.withId("com.android.application") {
            project.extensions.configure(ApplicationAndroidComponentsExtension::class.java) { extension ->
                extension.onVariantsAsmClassVisitorFactory { variant ->
                    // 注册用于插桩的 AsmClassVisitorFactory
                    variant.instrumentation.transformClassesWith(
                        TraceAsmClassVisitorFactory::class.java,
                        InstrumentationScope.ALL
                    ) {}
                    //  因为对 method 进行了插桩, 需求从头计算被插桩函数的栈帧
                    variant.instrumentation.setAsmFramesComputationMode(FramesComputationMode.COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS)
                }
            }
        }
    }
}

优下风

优势: 运用简略, 只需重视 ClassVisitor 逻辑, 无需处理 class 文件的读取与写入.
下风: class 处理进程是固定的, 只能完成相对简略的代码插桩与替换, 无法满意个性化需求.

二. Transform Task

经过 Instrumentation 的确能很方便的完成插桩与替换逻辑, 但是理想很丰满，现实很骨感, 许多时候并不能满意需求, 例如:

先剖析再操作: 在完成 hook 框架时, 一般需求先对工程中的一切 class 进行一次遍历剖析后, 再对相关的 class 文件进行字节码操作.
输出文件产品: 上文中的 TraceClassVisitor 在调用 Trace#beginSection 时传入了完整的类名与方法名, 这往往会导致生成的 trace 文件过大. 工程实践中一般会生成 methodId 与 类名#方法名 的映射, 在 Trace#beginSection 调用时只是传入 methodId, 这时就需求在插桩结束后保存当时的 methodId 与 类名#方法名 的映射文件.

当对 class 的处理进程有自定义需求时, 就需求经过 Transform Task 来完成. Transform Task 经过自己完成一个 Gradle Task, 然后运用 ApplicationAndroidComponentsExtension 提供的接口将其注册到 class 的处理流程中.

class 处理流程:

flowchart LR
source[classes]
dependencies[jars]
intermediate_classes[classes]
intermediate_jars[jars]
output[jar]
asm_source([transformClassesWithAsm])
asm_dependencies([transformJartsWithAsm])
transform_task([Transform Task])
source --> asm_source
asm_source --> intermediate_classes
dependencies --> asm_dependencies
asm_dependencies --> intermediate_jars
intermediate_classes --> transform_task
intermediate_jars --> transform_task
transform_task --> output

Transform Task 会在 Instrumentation 履行完成后再履行, 而且输出的产品是一个包含一切 class 的 jar 文件.

插桩实践

下面以完成一个的 TraceTransformTask 为例, 调整上文的中的 TraceClassVisitor插桩逻辑, 在调用 Trace#beginSection 时传入 methodId 参数, 并在插桩完成后输出 methodId 与 类名#方法名 的映射文件.

TraceClassVisitor

class TraceClassVisitor(
    api: Int,
    next: ClassVisitor,
    private  val mapping: (String) -> Long,
) : ClassVisitor(api, next) {
    private var className: String? = null
    override fun visit(
        version: Int,
        access: Int,
        name: String?,
        signature: String?,
        superName: String?,
        interfaces: Array<out String>?
    ) {
        className = name
        super.visit(version, access, name, signature, superName, interfaces)
    }
    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 TraceMethodVisitor(api, mv, access, name, descriptor)
    }
    private inner class TraceMethodVisitor(
        api: Int,
        methodVisitor: MethodVisitor?,
        access: Int,
        name: String?,
        descriptor: String?
    ) : AdviceAdapter(
        api,
        methodVisitor,
        access,
        name,
        descriptor
    ) {
        override fun onMethodEnter() {
            // 运用 methodId 替代 className#methodName
            val methodId = mapping("$className#$name")
            mv.visitLdcInsn("$methodId")
            mv.visitMethodInsn(
                Opcodes.INVOKESTATIC,
                "android/os/Trace",
                "beginSection",
                "(Ljava/lang/String;)V",
                false
            )
        }
        override fun onMethodExit(opcode: Int) {
            mv.visitMethodInsn(
                INVOKESTATIC,
                "android/os/Trace",
                "endSection",
                "()V",
                false
            )
        }
    }
}

TraceTransformTask

abstract class TransformTask : DefaultTask() {
    // 一切输入的 jar 文件
    @get:InputFiles
    abstract val allJars: ListProperty<RegularFile>
    // 一切输入的 classes 目录
    @get:InputFiles
    abstract val allDirectories: ListProperty<Directory>
    // 输出的 jar 文件
    @get:OutputFile
    abstract val outputJar: RegularFileProperty
    // 输出的 mapping 文件
    @get:OutputFile
    abstract val mappingFile: RegularFileProperty
    @TaskAction
    fun transform() {
        var currentMethodId = 0L
        val mapping = mutableMapOf<String, Long>()
        val factory: (ClassWriter) -> ClassVisitor = { next ->
            TraceClassVisitor(Opcodes.ASM9, next) { method ->
                mapping.getOrPut(method) { currentMethodId++ }
            }
        }
        JarOutputStream(
            outputJar.get().asFile
                .outputStream()
                .buffered()
        ).use { output ->
            // 遍历一切的 jar 文件输入, 并进行插桩
            allJars.get().forEach { jar ->
                transformJar(output, jar.asFile, factory)
            }
            // 遍历一切的 classes 目录输入, 并进行插桩
            allDirectories.get().forEach { dir ->
                transformClasses(output, dir.asFile, factory)
            }
        }
        // 插桩后, 输出 mapping 信息
        mappingFile.get().asFile
            .writeText(mapping.toString())
    }
    private fun transformJar(
        output: JarOutputStream,
        jar: File,
        factory: (ClassWriter) -> ClassVisitor
    ) {
        JarInputStream(
            jar.inputStream()
                .buffered()
        ).use { input ->
            while (true) {
                val entry = input.nextEntry ?: break
                if (entry.isDirectory) continue
                if (!entry.name.endsWith(".class")) continue
                transform(entry.name, input, output, factory)
            }
        }
    }
    private fun transformClasses(
        output: JarOutputStream,
        rootDir: File,
        factory: (ClassWriter) -> ClassVisitor
    ) {
        rootDir.walk().forEach { child ->
            if (child.isDirectory) return@forEach
            if (!child.name.endsWith(".class")) return@forEach
            val name = child.toRelativeString(rootDir)
            child.inputStream()
                .buffered()
                .use { input ->
                    transform(name, input, output, factory)
                }
        }
    }
    // 创建 ClassReader, ClassVisitor, ClassWriter 进行插桩
    private fun transform(
        name: String,
        input: InputStream,
        output: JarOutputStream,
        factory: (ClassWriter) -> ClassVisitor
    ) {
        val entry = ZipEntry(name)
        output.putNextEntry(entry)
        val cr = ClassReader(input)
        val cw = ClassWriter(ClassWriter.COMPUTE_MAXS)
        cr.accept(factory(cw), ClassReader.EXPAND_FRAMES)
        output.write(cw.toByteArray())
        output.closeEntry()
    }
}

TraceTransformPlugin

abstract class TraceTransformPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.withId("com.android.application") {
            project.extensions.configure(ApplicationAndroidComponentsExtension::class.java) { extension ->
                extension.onVariants {
                    // 装备 mapping 文件输出路径
                    val transformTask = project.tasks.register(
                        "transform${it.name.capitalized()}",
                        TransformTask::class.java
                    ) { task ->
                        task.mappingFile.set(project.buildDir.resolve("outputs/transform/mapping.txt"))
                    }
                    // 将 TransformTask 注册到 class 处理流程中
                    it.artifacts
                        .forScope(ScopedArtifacts.Scope.ALL)
                        .use(transformTask)
                        .toTransform(
                            ScopedArtifact.CLASSES,
                            TransformTask::allJars,
                            TransformTask::allDirectories,
                            TransformTask::outputJar
                        )
                }
            }
        }
    }
}

优下风

优势:
- 处理 class 文件的方法更加灵活, 能够按需完成对应的处理流程, 例如能够先对全工程进行剖析再进行字节码操作.
- 能够与其它的 Gradle Task 合作, 运用其它 Gradle Task 的输出作为输入或将其输出作为其它 Gradle Task 的输入.
下风:
- 相较于 Instrumentation 需求处理许多额定的逻辑, 例如对 class 文件的读写.
- 完成一个高性能的 Task 需求付出许多额定的尽力, 例如完成 Incremental tasks 等.

参考资料

Transform API is removed

AGP8.0 时代的 Transform 实践

一. Instrumentation

插桩实践

TraceClassVisitor

TraceAsmClassVisitorFactory

TraceTransformPlugin

优下风

二. Transform Task

插桩实践

TraceClassVisitor

TraceTransformTask

TraceTransformPlugin

优下风

参考资料

作者信息

AGP8.0 时代的 Transform 实践

一. Instrumentation

插桩实践

TraceClassVisitor

TraceAsmClassVisitorFactory

TraceTransformPlugin

优下风

二. Transform Task

插桩实践

TraceClassVisitor

TraceTransformTask

TraceTransformPlugin

优下风

参考资料

相关文章

2022总结 | 一年里五个月在准备面试是啥情况

使用HorizontalGridView实现一个TV应用的分类标题栏

fastlane自动化打包iOS APP

Midjourney：使用摄影prompt，AI 红外摄影，探索影像的奇境

作者信息