Transform 被废弃，TransformAction 了解一下~

谁借莪１个温暖的怀抱￠ 2024-04-08 08:40 70阅读 0赞

### 前言 ###

`Transform API` 是 `AGP1.5` 就引入的特性，主要用于在 `Android` 构建过程中，在 `Class` 转 `Dex` 的过程中修改 `Class` 字节码。利用 `Transform API` ，我们可以拿到所有参与构建的 `Class` 文件，然后可以借助 `ASM` 等字节码编辑工具进行修改，插入自定义逻辑。

国内很多团队都或多或少的用 `AGP` 的 `Transform API` 来搞点儿黑科技，比如无痕埋点，耗时统计，方法替换等。但是在 `AGP7.0` 中 `Transform` 已经被标记为废弃了，并且将在 `AGP8.0` 中移除。

而 `Transrom` 被废弃之后，它的代替品则是 `Transform Action` ，它是由 `Gradle` 提供的产物变换 `API` 。

`Transform API` 是由 `AGP` 提供的，而 `Transform Action` 则是由Gradle提供。不光是 `AGP` 需要`Transform` ， `Java` 也需要，所以由 `Gradle` 来提供统一的 `Transform API` 也合情合理。

当然如果你只是想利用 `ASM` 对字节码插桩， `AGP` 提供了对基于 `TransformAction` 的 `ASM` 插桩的封装，只需要使用 `AsmClassVisitorFactory` 即可.

而本文主要包括以下内容:

1.  `TransformAction` 是什么?
2.  如何自定义 `TransformAction`
3.  `TransformAction` 在 `AGP` 中的应用

### `TransformAction` 是什么？ ###

简单来说， `TransformAction` 就是 `Gradle` 提供的产物转换 `API` ，可以注册两个属性间的转换`Action` ，将依赖从一个状态切换到另一个状态

我们在项目中的依赖，可能会有多个变体，例如，一个依赖可能有以下两种变体: `classes` （ `org.gradle.usage=java-api` , `org.gradle.libraryelements=classes` ）或 `JAR` （ `org.gradle.usage=java-api, org.gradle.libraryelements=jar` )

它们的主要区别就在于，一个的产物是 `jar` ，一个则是 `classes` (类目录)

当 `Gradle` 解析配置时，解析的配置上的属性将确定请求的属性，并选中匹配属性的变体。例如，当配置请求 `org.gradle.usage=java-api, org.gradle.libraryelements=classes` 时，就会选择 `classes` 目录作为输入。

但是如果依赖项没有所请求属性的变体，那么解析配置就会失败。有时我们可以将依赖项的产物转换为请求的变体。

例如，解压缩 `Jar` 的 `TranformAction` 会将 `java-api` , `jars` 转换为 `java-api,classes` 变体。

这种转换可以对依赖的产物进行转换，所以称为“产物转换” 。 `Gradle` 允许注册产物转换，并且当依赖项没有所请求的变体时， `Gradle` 将尝试查找一系列产物转换以创建变体。

#### `TransformAction` 选择和执行逻辑 ####

如上所述，当 `Gradle` 解析配置并且配置中的依赖关系不具有带有所请求属性的变体时， `Gradle` 会尝试查找一系列 `TransformAction` 以创建变体。

每个注册的转换都是从一组属性转换为一组属性。例如，解压缩转换可以从 `org.gradle.usage=java-api, org.gradle.libraryelements=jars` 转换至 `org.gradle.usage=java-api, org.gradle.libraryelements=classes` 。

为了找到一条这样的链， `Gradle` 从请求的属性开始，然后将所有修改某些请求的属性的 `TransformAction` 视为通向那里的可能路径。

例如，考虑一个 `minified` 属性，它有两个值： `true` 和 `false` 。 `minified` 属性表示依赖项的变体，表示删除了不必要的类文件。

如果我们的依赖只有 `minified=false` 的变体，并且我们的配置中请求了 `minified=true` 的属性，如果我们注册了 `minify` 的转换，那么它就会被选中

在找到的所有变换链中， `Gradle` 尝试选择最佳的变换链：

1.  如果只有一个转换链，则选择它。
2.  如果有两个变换链，并且一个是另一个的后缀，则将其选中。
3.  如果存在最短的变换链，则将其选中。
4.  在所有其他情况下，选择将失败并报告错误。

同时还有两个特殊情况:

1.  当已经存在与请求属性匹配的依赖项变体时， `Gradle` 不会尝试选择产物转换。
2.  `artifactType` 属性是特殊的，因为它仅存在于解析的产物上，而不存在于依赖项上。因此任何只变换 `artifactType` 的 `TransformAction` ，只有在使用ArtifactView时才会考虑使用

### 自定义 `TransformAction` ###

下面我们就以自定义一个 `MinifyTransform` 为例，来看看如何自定义 `TransformAction` ，主要用于过滤产物中不必要的文件

#### 定义 `TransformAction` ####

abstract class Minify : TransformAction<Minify.Parameters> {   // (1)
        interface Parameters : TransformParameters {               // (2)
            @get:Input
            var keepClassesByArtifact: Map<String, Set<String>>
    
        }
    
        @get:PathSensitive(PathSensitivity.NAME_ONLY)
        @get:InputArtifact
        abstract val inputArtifact: Provider<FileSystemLocation>
    
        override
        fun transform(outputs: TransformOutputs) {
            val fileName = inputArtifact.get().asFile.name
            for (entry in parameters.keepClassesByArtifact) {      // (3)
                if (fileName.startsWith(entry.key)) {
                    val nameWithoutExtension = fileName.substring(0, fileName.length - 4)
                    minify(inputArtifact.get().asFile, entry.value, outputs.file("${nameWithoutExtension}-min.jar"))
                    return
                }
            }
            println("Nothing to minify - using ${fileName} unchanged")
            outputs.file(inputArtifact)                            // (4)
        }
    
        private fun minify(artifact: File, keepClasses: Set<String>, jarFile: File) {
            println("Minifying ${artifact.name}")
            // Implementation ...
        }
    }
    复制代码

代码很简单，主要分为以下几步：

TransformAction
    transform

其实一个 `TransformAction` 主要就是输入，输出，变换逻辑三个部分

#### 注册 `TransformAction` ####

接下来就是注册了，您需要注册 `TransformAction` ，并在必要时提供参数，以便在解析依赖项时可以选择它们

val artifactType = Attribute.of("artifactType", String::class.java)
    val minified = Attribute.of("minified", Boolean::class.javaObjectType)
    
    val keepPatterns = mapOf(
        "guava" to setOf(
            "com.google.common.base.Optional",
            "com.google.common.base.AbstractIterator"
        )
    )
    
    dependencies {
        attributesSchema {
            attribute(minified)                      // <1>
        }
        artifactTypes.getByName("jar") {
            attributes.attribute(minified, false)    // <2>
        }
    }
    
    configurations.all {
        afterEvaluate {
            if (isCanBeResolved) {
                attributes.attribute(minified, true) // <3>
            }
        }
    }
    
    dependencies {                                 // (4)
        implementation("com.google.guava:guava:27.1-jre")
        implementation(project(":producer"))
    }
    
    dependencies {
        registerTransform(Minify::class) { // <5>
            from.attribute(minified, false).attribute(artifactType, "jar")
            to.attribute(minified, true).attribute(artifactType, "jar")
    
            parameters {
                keepClassesByArtifact = keepPatterns
                // Make sure the transform executes each time
                timestamp = System.nanoTime()
            }
        }
    }
    
    tasks.register<Copy>("resolveRuntimeClasspath") { 
        from(configurations.runtimeClasspath)
        into(layout.buildDirectory.dir("runtimeClasspath"))
    }
    复制代码

1.  添加 `minified` 属性
2.  将所有JAR文件的 `minified` 属性设置为 `false`
3.  在所有可解析的配置上设置请求的属性为 `minified=true`
4.  添加将要转换的依赖项
5.  注册 `Transformaction` ，设置 `from` 与 `to` 的属性，并且传递自定义参数

#### 运行 `TransformAction` ####

在定义与注册了 `TransformAction` 之后，下一步就是运行了

上面我们自定义了 `resolveRuntimeClasspath` 的 `Task` , `Minify` 转换会在我们请求 `minified=true` 的变体时调用

当我们运行 `gradle resolveRuntimeClasspath` 时就可以得到如下输出

> Task :resolveRuntimeClasspath
    Nothing to minify - using jsr305-3.0.2.jar unchanged
    Minifying guava-27.1-jre.jar
    Nothing to minify - using failureaccess-1.0.1.jar unchanged
    Nothing to minify - using listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar unchanged
    Nothing to minify - using j2objc-annotations-1.1.jar unchanged
    Nothing to minify - using checker-qual-2.5.2.jar unchanged
    Nothing to minify - using error_prone_annotations-2.2.0.jar unchanged
    Nothing to minify - using animal-sniffer-annotations-1.17.jar unchanged
    复制代码

可以看出，当我们执行 `task` 的时候， `gradle` 自动调用了 `TransformAction` ，对 `guava.jar`进行了变换，并将结果存储在 `layout.buildDirectory.dir("runtimeClasspath")` 中

### 变换 `ArtifactType` 的 `TransformAction` ###

上文提到， `artifactType` 属性是特殊的，因为它仅存在于解析的产物上，而不存在于依赖项上。因此任何只变换 `artifactType` 的 `TransformAction` ，只有在使用ArtifactView时才会考虑使用

其实在 `AGP` 中，相当一部分自定义 `TransformAction` 都是属于只变换 `ArtifactType` 的，下面我们来看下如何自定义一个这样的 `TransformAction`

class TransformActionPlugin : Plugin<Project> {
        override fun apply(project: Project) {
            project.run {
                val artifactType = Attribute.of("artifactType", String::class.java)
                dependencies.registerTransform(MyTransform::class.java) { // 1
                    it.from.attribute(artifactType, "jar")
                    it.to.attribute(artifactType, "my-custom-type")
                }
                val myTaskProvider = tasks.register("myTask", MyTask::class.java) { 
                    it.inputCount.set(10)
                    it.outputFile.set(File("build/myTask/output/file.jar"))
                }
                val includedConfiguration = configurations.create("includedConfiguration") // 2
                dependencies.add(includedConfiguration.name, "org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.10")
    
                val combinedInputs = project.files(includedConfiguration, myTaskProvider.map { it.outputFile })
                val myConfiguration = configurations.create("myConfiguration")
                dependencies.add(myConfiguration.name, project.files(project.provider { combinedInputs }))
    
                tasks.register("consumerTask", ConsumerTask::class.java) { // 3
                    it.artifactCollection = myConfiguration.incoming.artifactView {viewConfiguration ->
                        viewConfiguration.attributes.attribute(artifactType, "my-custom-type")
                    }.artifacts
                    it.outputFile.set(File("build/consumerTask/output/output.txt"))
                }
            }
        }
    }
    复制代码

主要分为以下几步：

1.  声明与注册自定义 `Transform` ，指定输入与输出的 `artifactType`
2.  创建自定义的 `configuration` ，指定输入的依赖是什么(当然也可以直接用 `AGP` 已有的 `configuration` )
3.  在使用时，通过自定义 `configuration` 的 `artifactView` ，获取对应的产物
4.  `ConsumerTask` 中消费自定义 `TransformAction` 的输出产物

然后我们运行 `./gradlew consumerTask` 就可以得到以下输出

> Task :app:consumerTask
    Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-common/1.7.10/bac80c520d0a9e3f3673bc2658c6ed02ef45a76a/kotlin-stdlib-common-1.7.10.jar. File exists = true
    Processing ~/AndroidProject/2022/argust/GradleTutorials/app/build/myTask/output/file.jar. File exists = true
    Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk8/1.7.10/d70d7d2c56371f7aa18f32e984e3e2e998fe9081/kotlin-stdlib-jdk8-1.7.10.jar. File exists = true
    Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains/annotations/13.0/919f0dfe192fb4e063e7dacadee7f8bb9a2672a9/annotations-13.0.jar. File exists = true
    Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib/1.7.10/d2abf9e77736acc4450dc4a3f707fa2c10f5099d/kotlin-stdlib-1.7.10.jar. File exists = true
    Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk7/1.7.10/1ef73fee66f45d52c67e2aca12fd945dbe0659bf/kotlin-stdlib-jdk7-1.7.10.jar. File exists = true
    复制代码

可以看出，当运行 `consumerTask` 时，执行了 `MyTransform` ，并将 `jar` 类型的产物转化成了 `my-custom-type`

### `TransformAction` 在 `AGP` 中的应用 ###

现在 `AGP` 中的 `Transform` 已经基本上都改成 `TransformAction` 了，我们一起来看几个例子

#### `AarTransform` ####

`Android ARchive` ，也就是 `.aar` 后缀的资源包， `gradle` 是如何使用它的呢？

如果有同学尝试过就知道，如果是默认使用 `java-libray` 的工程，肯定无法依赖并使用 `aar`的，引入时会报 `Could not resolve ${dependencyNotation}` ，说明在 `Android Gradle Plugin`当中，插件对 `aar` 包的依赖进行了处理，只有通过了插件处理，才能正确使用 `aar` 内的资源。那就来看看 `AGP` 是如何在 `TransformAction` 的帮助下做到这点的

`Aar` 转换的实现就是 `AarTransform` ，我们一起来看下源码：

// DependencyConfigurator.kt
    for (transformTarget in AarTransform.getTransformTargets()) {
        registerTransform(
            AarTransform::class.java,
            AndroidArtifacts.ArtifactType.EXPLODED_AAR,
            transformTarget
        ) { params ->
            params.targetType.setDisallowChanges(transformTarget)
            params.sharedLibSupport.setDisallowChanges(sharedLibSupport)
        }
    }
    
    public abstract class AarTransform implements TransformAction<AarTransform.Parameters> {
    
        @NonNull
        public static ArtifactType[] getTransformTargets() {
            return new ArtifactType[] {
                ArtifactType.SHARED_CLASSES,
                ArtifactType.JAVA_RES,
                ArtifactType.SHARED_JAVA_RES,
                ArtifactType.PROCESSED_JAR,
                ArtifactType.MANIFEST,
                ArtifactType.ANDROID_RES,
                ArtifactType.ASSETS,
                ArtifactType.SHARED_ASSETS,
                ArtifactType.JNI,
                ArtifactType.SHARED_JNI,
                // ...
            };
        }
    
        @Override
        public void transform(@NonNull TransformOutputs transformOutputs) {
            // 具体实现
        }        
    复制代码

代码也比较简单，主要做了下面几件事：

1.  在 `DependencyConfigurator` 中注册 `Aar` 转换成各种类型资源的 `TransformAction`
2.  在 `AarTransform` 中根据类型将 `aar` 包中的文件解压到输出到各个目录

#### `JetifyTransform` ####

`Jetifier` 也是在迁移到 `AndroidX` 之后的常用功能，它可以将引用依赖内的 `android.support.*` 引用都替换为对 `androidx` 的引用，从而实现对 `support` 包的兼容

下面我们来看一下 `JetifyTransform` 的代码

// com.android.build.gradle.internal.DependencyConfigurator
    
    if (projectOptions.get(BooleanOption.ENABLE_JETIFIER)) {
        registerTransform(
            JetifyTransform::class.java,
            AndroidArtifacts.ArtifactType.AAR,
            jetifiedAarOutputType
        ) { params ->
            params.ignoreListOption.setDisallowChanges(jetifierIgnoreList)
        }
        registerTransform(
            JetifyTransform::class.java,
            AndroidArtifacts.ArtifactType.JAR,
            AndroidArtifacts.ArtifactType.PROCESSED_JAR
        ) { params ->
            params.ignoreListOption.setDisallowChanges(jetifierIgnoreList)
        }
    }
    
    // com.android.build.gradle.internal.dependency.JetifyTransform
    override fun transform(transformOutputs: TransformOutputs) {
        val inputFile = inputArtifact.get().asFile
    
        val outputFile = transformOutputs.file("jetified-${inputFile.name}")
        jetifierProcessor.transform2(
            input = setOf(FileMapping(inputFile, outputFile)),
            copyUnmodifiedLibsAlso = true,
            skipLibsWithAndroidXReferences = true
        )
    }
    复制代码

1.  读取并判断 `ENABLE_JETIFIER` 属性，这就是我们在 `gradle.properties` 中配置的 `jetifier`开关
2.  为 `aar` 和 `jar` 类型的依赖都注册 `JetifyTransform` 转换
3.  在 `transform` 中对 `support` 包的依赖进行替换，完成后会将处理过的资源重新压缩，并且会带上 `jetified` 的前缀

### 总结 ###

本文主要讲解了 `TransformAction` 是什么， `TransformAction` 自定义，以及 `TransformAction`在 `AGP` 中的应用，可以看出，目前 `AGP` 中的产物转换已经基本上都用 `TransformAction` 来实现了

事实上， `AGP` 对 `TransformAction` 进行了一定的封装，如果你只是想利用 `ASM` 实现字节码插桩，那么直接使用 `AsmClassVisitorFactory` 就好了。但如果想要阅读 `AGP` 的源码，了解 `AGP` 构建的过程，还是需要了解一下 `TransformAction` 的基本使用与原理的