其实 Gradle Transform 就是个纸老虎 —— Gradle 系列(4)

请点赞加关注，你的支持对我非常重要，满足下我的虚荣心。
Hi，我是小彭。本文已收录到 GitHub · Android-NoteBook 中。这里有 Android 进阶成长知识体系，有志同道合的朋友，欢迎跟着我一起成长。（联系方式在 GitHub）

前言

目前，使用 AGP Transform API 进行字节码插桩已经非常普遍了，例如 Booster、神策等框架中都有 Transform 的影子。Transform 听起来很高大上，其本质就是一个 Gradle Task。在这篇文章里，我将带你理解 Transform 的工作机制、使用方法和核心源码解析，并通过一个 Demo 帮助你融会贯通。

这篇文章是全面掌握 Gradle 构建系统系列的第 4 篇：

• 1、Gradle 基础
• 2、Gradle 插件
• 3、Gradle 依赖管理
• 4、APG Transform

---

1. 认识 Transform

1.1 什么是 Transform？

Transform API 是 Android Gradle Plugin 1.5 就引入的特性，主要用于在 Android 构建过程中，在 Class→Dex 这个节点修改 Class 字节码。利用 Transform API，我们可以拿到所有参与构建的 Class 文件，借助 Javassist 或 ASM 等字节码编辑工具进行修改，插入自定义逻辑。一般来说，这些自定义逻辑是与业务逻辑无关的。

使用 Transform 的常见的应用场景有：

• 埋点统计： 在页面展现和退出等生命周期中插入埋点统计代码，以统计页面展现数据；
• 耗时监控： 在指定方法的前后插入耗时计算，以观察方法执行时间；
• 方法替换： 将方法调用替换为调用另一个方法。

1.2 Transform 的基本原理

先大概了解下 Transform 的工作机制：

• 1、工作时机： Transform 工作在 Android 构建中由 Class → Dex 的节点；
• 2、处理对象： 处理对象包括 Javac 编译后的 Class 文件、Java 标准 resource 资源、本地依赖和远程依赖的 JAR/AAR。Android 资源文件不属于 Transform 的操作范围，因为它们不是字节码；
• 3、Transform Task： 每个 Transform 都对应一个 Task，Transform 的输入和输出可以理解为对应 Transform Task 的输入输出。每个 TransformTask 的输出都分别存储在 app/build/intermediates/transform/[Transform Name]/[Variant] 文件夹中；
• 4、Transform 链： TaskManager 会将每个 TransformTask 串联起来，前一个 Transform 的输出会作为下一个 Transform 的输入。

1.3 Transform API

了解 Transform 的基本工作机制后，我们先来看 Transform 的核心 API。这里仅列举出 Transform 抽象类中最核心的方法，有几个次要的方法后面再说。

com.android.build.api.transform.java

public abstract class Transform {

    // 指定 Transform 的名称，该名称还会用于组成 Task 的名称
    // 格式为 transform[InputTypes]With[name]For[Configuration]
    public abstract String getName();

    // （孵化中）用于过滤 Variant，返回 false 表示该 Variant 不执行 Transform
    public boolean applyToVariant(VariantInfo variant) {
        return true;
    }

    // 指定输入内容类型
    public abstract Set getInputTypes();

    // 指定输出内容类型，默认取 getInputTypes() 的值
    public Set getOutputTypes() {
        return getInputTypes();
    }

    // 指定消费型输入内容范畴
    public abstract Set getScopes();

    // 指定引用型输入内容范畴
    public Set getReferencedScopes() {
        return ImmutableSet.of();
    }

    // 指定是否支持增量编译
    public abstract boolean isIncremental();

    // 核心 API
    public void transform(TransformInvocation transformInvocation)
            throws TransformException, InterruptedException, IOException {
        // 分发到过时 API，以兼容旧版本的 Transform
        //noinspection deprecation
        transform(transformInvocation.getContext(), transformInvocation.getInputs(),
                transformInvocation.getReferencedInputs(),
                transformInvocation.getOutputProvider(),
                transformInvocation.isIncremental());
    }

    // 指定是否支持缓存
    public boolean isCacheable() {
        return false;
    }
}

1.4 ContentType 内容类型

ContentType 是一个枚举类接口，表示输入或输出内容的类型，在 AGP 中定义了 DefaultContentType 和 ExtendedContentType 两个枚举类。但是，我们在自定义 Transform 时只能使用 DefaultContentType 中定义的枚举，即 CLASSES 和 RESOURCES 两种类型，其它类型仅供 AGP 内置的 Transform 使用。

自定义 Transform 需要在两个位置定义内容类型：

• 1、Set getInputTypes()： 指定输入内容类型，允许通过 Set 集合设置输入多种类型；
• 2、Set getOutputTypes()： 指定输出内容类型，默认取 getInputTypes() 的值，允许通过 Set 集合设置输出多种类型。

ExtendedContentType.java

// 加强类型，自定义 Transform 无法使用
public enum ExtendedContentType implements ContentType {

    // DEX 文件
    DEX(0x1000),

    // Native 库
    NATIVE_LIBS(0x2000),

    // Instant Run 加强类
    CLASSES_ENHANCED(0x4000),

    // Data Binding 中间产物
    DATA_BINDING(0x10000),

    // Dex Archive
    DEX_ARCHIVE(0x40000),
    ;
}

QualifiedContent.java

enum DefaultContentType implements ContentType {

    // Java 字节码，包括 Jar 文件和由源码编译产生的
    CLASSES(0x01),

    // Java 资源
    RESOURCES(0x02);
}

在 TransformManager 中，预定义了一部分内容类型集合，常用的是 CONTENT_CLASS 操作 Class。

TransformManager.java

public static final Set CONTENT_CLASS = ImmutableSet.of(CLASSES);
public static final Set CONTENT_JARS = ImmutableSet.of(CLASSES, RESOURCES);
public static final Set CONTENT_RESOURCES = ImmutableSet.of(RESOURCES);

1.5 ScopeType 作用域

ScopeType 也是一个枚举类接口，表示输入内容的范畴。在 AGP 中定义了 InternalScope 和 Scope 两个枚举类。但是，我们在自定义 Transform 只能使用 Scope 中定义的枚举，其它类型仅供 AGP 内置的 Transform 使用。

Transform 需要在两个位置定义输入内容范围：

• 1、Set getScopes() 消费型输入内容范畴： 此范围的内容会被消费，因此当前 Transform 必须将修改后的内容复制到 Transform 的中间目录中，否则无法将内容传递到下一个 Transform 处理；
• 2、Set getReferencedScopes() 指定引用型输入内容范畴： 默认是空集合，此范围的内容不会被消费，因此不需要复制传递到下一个 Transform，也不允许修改。

InternalScope.java

// 内部使用的作用域，自定义 Transform 无法使用
public enum InternalScope implements QualifiedContent.ScopeType {

    MAIN_SPLIT(0x10000),

    LOCAL_DEPS(0x20000),

    FEATURES(0x40000),
    ;
}

QualifiedContent.java

enum Scope implements ScopeType {

    // 当前模块
    PROJECT(0x01),
    // 子模块
    SUB_PROJECTS(0x04),
    // 外部依赖，包括当前模块和子模块本地依赖和远程依赖的 JAR/AAR
    EXTERNAL_LIBRARIES(0x10),
    // 当前变体所测试的代码（包括依赖项）
    TESTED_CODE(0x20),
    // 本地依赖和远程依赖的 JAR/AAR（provided-only）
    PROVIDED_ONLY(0x40),
}

在 TransformManager 中，预定义了一部分作用域集合，常用的是 SCOPE_FULL_PROJECT 所有模块。需要注意，Library 模块注册的 Transform 只能使用 Scope.PROJECT。

TransformManager.java

public static final Set PROJECT_ONLY = ImmutableSet.of(Scope.PROJECT);
public static final Set SCOPE_FULL_PROJECT = ImmutableSet.of(Scope.PROJECT, Scope.SUB_PROJECTS, Scope.EXTERNAL_LIBRARIES);

1.6 transform 方法

transform() 是实现 Transform 的核心方法，方法的参数是 TransformInvocation，它提供了所有与输入输出相关的信息：

public interface TransformInvocation {

    Context getContext();

    // 消费型输入内容
    Collection getInputs();

    // 引用型输入内容
    Collection getReferencedInputs();

    // 额外输入内容
    Collection getSecondaryInputs();

    // 输出信息
    TransformOutputProvider getOutputProvider();

    // 是否增量构建
    boolean isIncremental();
}

• isIncremental()： 当前 Transform 任务是否增量构建；
• getInputs()： 获取 TransformInput 对象，它是消费型输入内容，对应于 Transform#getScopes() 定义的范围；
• getReferencedInputs()： 获取 TransformInput 对象，它是引用型输入内容，对应于 Transform#getReferenceScope() 定义的内容范围；
• getOutPutProvider()： TransformOutputProvider 是对输出文件的抽象。

输入内容 TransformInput 由两部分组成：

• DirectoryInput 集合： 以源码方式参与构建的输入文件，包括完整的源码目录结构及其中的源码文件；
• JarInput 集合： 以 Jar 和 aar 依赖方式参与构建的输入文件，包含本地依赖和远程依赖。

输入内容信息 TransformOutputProvider 有两个功能：

• deleteAll()： 当 Transform 运行在非增量构建模式时，需要删除上一次构建产生的所有中间文件，可以直接调用 deleteAll() 完成；
• getContentLocation()： 获得指定范围+类型的输出目标路径。

TransformOutputProvider.java

public interface TransformOutputProvider {

    // 删除所有中间文件
    void deleteAll()

    // 获取指定范围+类型的目标路径
    File getContentLocation(String name,
    Set types,
    Set scopes,
    Format format);
}

获取输入内容对应的输出路径：

for (input in transformInvocation.inputs) {
    for (jarInput in input.jarInputs) {
        // 输出路径
        val outputJar = outputProvider.getContentLocation(
            jarInput.name,
            jarInput.contentTypes,
            jarInput.scopes,
            Format.JAR
        )
    }
}

1.7 Transform 增量模式

任何构建系统都会尽量避免重复执行相同工作，Transform 也不例外。虽然增量构建并不是必须的，但作为一个合格的 Transform 实现应该具备增量能力。

1、增量模式标记位： Transform API 有两个增量标志位，不要混淆：

• Transform#isIncremental()： Transform 增量构建的使能开关，返回 true 才有可能触发增量构建；
• TransformInvocation#isIncremental()： 当次 TransformTask 是否增量执行，返回 true 表示正在增量模式。

2、Task 增量模式与 Transform 增量模式的区别： Task 增量模式与 Transform 增量模式的区别在于，Task 增量执行时会跳过整个 Task 的动作列表，而 Transform 增量执行依然会执行 TransformTask，但输入内容会增加变更内容信息。

3、增量模式的输入： 增量模式下的所有输入都是带状态的，需要根据这些状态来做不同的处理，不需要每次所有流程都重新来一遍。比如新增的输入就需要处理，而未修改的输入就不需要处理。Transform 定义了四个输入文件状态：

com.android.build.api.transform.Status.java

public enum Status {

    // 未修改，不需要处理，也不需要复制操作
    NOTCHANGED,
    
    // 新增，正常处理并复制给下一个任务
    ADDED,
    
    // 已修改，正常处理并复制给下一个任务
    CHANGED,
        
    // 已删除，需同步移除 OutputProvider 指定的目标文件
    REMOVED;
}

1.8 注册 Transform

在 BaseExtension 中维护了一个 Transform 列表，自定义 Transform 需要注册才能生效，而且还支持额外设置 TransformTask 的依赖。

BaseExtension.kt

abstract class BaseExtension {
    private val _transforms: MutableList = mutableListOf()
    private val _transformDependencies: MutableList> = mutableListOf()
    ...

    fun registerTransform(transform: Transform, vararg dependencies: Any) {
        _transforms.add(transform)
        _transformDependencies.add(listOf(dependencies))
    }
}

注册 Transform：

// 获取 Android 扩展
val androidExtension = project.extensions.getByType(BaseExtension::class.java)
// 注册 Transform，支持额外增加依赖
androidExtension.registerTransform(ToastTransform(project)/* 支持增加依赖*/)

提示： 为了提高编译效率，可以判断 Variant 为 release 类型才注册 Transform，也可以通过重写 Transform#applyToVariant() 来决定是否执行 Transform。

---

2. Transform 核心源码分析

这一节我们来分析 Transform 相关核心源码，这里我们引用的是 Android Gradle Plugin 7.1.0 版本的源码。

2.1 Transform 与 Task 的关系

Project 的构建逻辑由一系列 Task 的组成，每个 Task 负责完成一个基本的工作，例如 Javac 编译 Task。Transform 也是依靠 Task 执行的，在配置阶段，Gradle 会为注册的 Transform 创建对应的 Task。

提示： 说 “创建” 可能不太严谨，TransformManager 使用 register 懒创建的方式注册 Task，其实还没有创建 Task 实例。我们不要复杂化了，就说创建吧。

而 Task 的依赖关系是通过 TransformTask 的输入输出关系隐式确定的，TransformManager 通过 TransformStream 链接各个 TransformTask 的输入输出，进而控制 Transform 的依赖关系顺序。

LibraryTaskManager.java

@Override
protected void doCreateTasksForVariant(ComponentInfo variantInfo) {
    ...
    // ----- External Transforms -----
    // apply all the external transforms.
    List customTransforms = extension.getTransforms();
    List> customTransformsDependencies = extension.getTransformsDependencies();

    final IssueReporter issueReporter = libraryVariant.getServices().getIssueReporter();

    for (int i = 0, count = customTransforms.size(); i < count; i++) {
        Transform transform = customTransforms.get(i);

        // Check the transform only applies to supported scopes for libraries:
        // We cannot transform scopes that are not packaged in the library
        // itself.
        Sets.SetView difference = Sets.difference(transform.getScopes(), TransformManager.PROJECT_ONLY);
        if (!difference.isEmpty()) {
            String scopes = difference.toString();
            issueReporter.reportError(
                    Type.GENERIC,
                    String.format(
                            "Transforms with scopes '%s' cannot be applied to library projects.",
                            scopes));
        }

        List