Transform 被废弃，TransformAction 了解一下~

前言

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即可，关于具体的使用可见：Transform 被废弃，ASM 如何适配?

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

1. 
   
2. TransformAction是什么?
   
3. 如何自定义TransformAction
   
4. 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. 如果存在最短的变换链，则将其选中。
   
5. 在所有其他情况下，选择将失败并报告错误。
   

同时还有两个特殊情况:

1. 
   
2. 当已经存在与请求属性匹配的依赖项变体时，Gradle不会尝试选择产物转换。
   
3. 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 ...

    }

}

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

1. 
   
2. 实现TransformAction接口并声明参数类型
   
3. 实现参数接口，实现自定义参数
   
4. 获取输入并实现transform逻辑
   
5. 输出变换结果，当不需要变换时直接将输入作为变换结果
   

其实一个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"))

}

注册TransformAction也分为以下几步：

1. 
   
2. 添加minified属性
   
3. 将所有JAR文件的minified属性设置为false
   
4. 在所有可解析的配置上设置请求的属性为minified=true
   
5. 添加将要转换的依赖项
   
6. 注册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. 
   
2. 声明与注册自定义Transform，指定输入与输出的artifactType
   
3. 创建自定义的 configuration，指定输入的依赖是什么(当然也可以直接用AGP已有的configuration)
   
4. 在使用时，通过自定义configuration的artifactView，获取对应的产物
   
5. 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. 
   
2. 在DependencyConfigurator中注册Aar转换成各种类型资源的TransformAction
   
3. 在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. 
   
2. 读取并判断ENABLE_JETIFIER属性，这就是我们在gradle.properties中配置的jetifier开关
   
3. 为aar和jar类型的依赖都注册JetifyTransform转换
   
4. 在transform中对support包的依赖进行替换，完成后会将处理过的资源重新压缩，并且会带上jetified的前缀
   

总结

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

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

示例代码

本文所有代码可见：github.com/RicardoJian…