编程 Java/Android

Android Gradle 插件自定义Plugin实现注意事项

Posted in Java/Android onJune 16, 2022

Android Gradle Plugin

在 Android 项目中的 build.gradle 文件中，经常可以看见一些 plugin 声明：

plugins {
    id 'com.android.application'
	  id 'com.android.library'
}
// or
apply plugin: 'com.android.application'
apply plugin: 'com.android.library'

上面是两种引用 gradle 插件的常用代码，com.android.application 是用来构建 apk 的 gradle 插件；com.android.library 是用来构建 Android Library 的 gradle 插件。

Gradle 是什么？

Gradle 是自动化构建工具，多项目构建而设计的。通过 groovy 或 kotlin 来编写构建脚本。主要用来处理：

自动处理包依赖关系
自动处理部署问题

过去 Java 开发者常用 Maven 和 Ant 等工具进行封装布署的自动化，或是两者兼用，不过这两个包彼此有优缺点：

如果频繁改变相依包版本，使用 Ant 相当麻烦，
如果琐碎工作很多，Maven 功能不足
而且两者都使用 XML 描述，相当不利于设计 if、switch 等判断式，即使写了可读性也不佳

而 Gradle 改良了过去 Maven、Ant 带给开发者的问题，至今也成为 Android Studio 内置的封装布署工具。

官方文档：What is Gradle?

Gradle 插件

Gradle 的核心是提供自动化处理流程。所有有用的特性，比如编译 Java 代码的能力，都是由插件添加的。

插件实际的作用有：

拓展 Gradle Model （例如：添加可配置的新 DSL 元素）
根据约定配置项目（例如：添加新的 Gradle Task 或配置一些合理的默认值）
应用指定的配置（例如：添加一些仓库或执行标准）

好处：

通过应用插件，而不是向项目构建脚本添加逻辑，可以获得的好处有：

提高复用能力，减少跨多个项目维护类似逻辑的开销：同一个插件可以应用到不同的项目。
更好的模块化：通过插件的形式，可以使项目架构更加明确更容易理解。
封装重要的逻辑，允许构建脚本尽可能具有声明性。

使用插件

要使用插件中封装的构建逻辑，Gradle 需要执行两个步骤。首先，解析插件，然后需要将插件应用到一个目标上，通常是一个 org.gradle.api.Project 对象。

解析插件：解析插件的工作是找到包含给定插件的正确版本的 jar 并将其添加到脚本类路径中。一旦一个插件被解析，它的 API 就可以在构建脚本中使用。
应用插件：应用插件意味着在要使用插件的项目上实际执行插件的Plugin.apply(T 。应用插件是幂等的。也就是说，您可以安全地多次应用任何插件而不会产生副作用。

本篇文章主要介绍如何实现一个二进制插件。

实现一个插件

最简单的构建 Gradle 插件的方式是通过命令来构建：

gradle init // or ./gradlew init

执行命令：

Android Gradle 插件自定义Plugin实现注意事项

第一步，选择项目类型，4 是 Gradle 插件项目。
第二步，选择实现芋圆，这里主要是插件的代码语言，支持 Groovy、Java 和 Kotlin。
第三步，选择 DSL 语言（构建脚本语言），支持 Groovy 和 Kotlin。
第四步，输入项目名称和插件包名。

最后会显示构建结果。构建完的项目结构是这样的：

Android Gradle 插件自定义Plugin实现注意事项

这里有很多不需要的文件目录，包括用来测试和 Gradle 的一些相关内容，都可以删除（当然你也可以不处理），因为当我们把这个项目引入到一个 Android 项目中时，Android 项目提供了 Gradle 相关文件。

Android Gradle 插件自定义Plugin实现注意事项

如图所示，ExamplePlugin 目录下 gradle 相关的文件，在 Android 的根目录中都存在。其中构建插件相关的内容都在 build.gradle 文件中，首先是，插件项目引用的插件：

plugins {
    id 'java-gradle-plugin' 
    id 'maven' // maven 仓库
    id 'groovy'	// groovy 支持
}

需要重点注意的是，使用一些第三方依赖如果下载不到，要检查引用的远程仓库是否在包含想要引用的依赖：

repositories {
    // Use JCenter for resolving dependencies.
    jcenter()
}

当我想引用 com.android.tools.build:gradle 依赖时，一直报错，原因是 jcenter 中不存在这个项目，需要添加 google()。

然后是一些依赖：

dependencies {
    // ...
    testImplementation 'org.spockframework:spock-core:1.3-groovy-2.5'
}

接下来是比较重要的插件定义：

gradlePlugin {
    // Define the plugin
    plugins {
        customName {
            id = 'com.example.plugin.customname'
            implementationClass = 'com.example.plugin.ComExamplePluginPlugin'
        }
    }
}

这里需要注意的是 customName 是你可以随意定义的字符串，这个字符串会在 Plugin.apply 方法中使用到。 Id 就是插件唯一标识，后续在其他项目中引用的时候，也是引用这个 id 。 implementationClass 的值指向一个实际的代码类，这个类实现了 org.gradle.api.Plugin 。自动生成的 Plugin 实现类是这样的：

class ComExamplePluginPlugin implements Plugin<Project> {
    void apply(Project project) {
        // Register a task
        project.tasks.register("customName") {
            doLast {
                println("Hello from plugin 'com.example.plugin.customname'")
            }
        }
    }
}

在这个 apply 方法中，使用之前我们定义的 customName 注册了一个 Task 。实际上 Gradle 后续就是执行这个 Task ，来执行代码块中的代码的。

在很多之前的 Gradle 插件实现方案中，需要创建 resources/META-INF/gradle-plugin/xxx.properties ，而通过上面的方式，不需要在去创建这个文件了。这样一个插件的定义基本上就完成了。

发布插件

我们已经定义好了一个 Gradle 插件，那么应该如何校验这个插件是否真的能够使用呢？为了解决这个问题，我们要把 Gradle 插件发布到远程仓库或者本地目录，然后供其他项目引用，以此来测试插件。以本地发布为例，在插件项目的根目录下的 build.gradle 文件中添加：

plugins {
	  // ...
    id 'maven-publish' // 用来发布插件
}
publishing {
    repositories {
        maven {
            // $rootDir 表示你项目的根目录
			  // 这里配置发布到的本地目录
            url = "$rootDir/repo" 
        }
    }
    publications {
        publish(MavenPublication) {
            // 插件的组ID，建议设置为插件的包名
            groupId = 'com.example.plugin.customname'
            // 插件的名字，后续在引用时会用到
            artifactId = 'customName'
            version = '0.0.1'
            // 组件类型
            from components.java
        }
    }
}

如果发布到本地，运行 Gradle 命令：

./gradlew publishPublishPublicationToMavenLocal

则会发布到本地目录 /Users/XXX/.m2/repository/ 中。

./gradlew publishPublishPublicationToMavenRepository

会发布到你在 build.gradle 中，指定的目录 "$rootDir/repo" 中。

Android Gradle 插件自定义Plugin实现注意事项

引用插件

在 Android 项目中引用的第一步是在根目录的 build.gradle中添加 maven 仓库，这样 Gradle 才能从特定的本地目录中找到我们的 jar 包：

repositories {
    jcenter()
    google()
    maven {
        url = "$rootDir/repo"
    }
}

第二步，在根目录的 build.gradle 中添加依赖：

dependencies {
    classpath "com.example.plugin.customname:customName:0.0.1"
}

这个就是我们在发布插件时，指定的 groupId 、artifactId 和 version，规则是：

classpath "$groupId:$artifactId:$version"

然后，在需要引用的 module 下的 build.gradle 文件中应用插件：

plugins {
    id 'com.example.plugin.customname'
}

这里的 id 是我们在定义插件时在 gradlePlugin 代码块中指定的。这样我们就成功的通过 jar 包的形式引用到了插件。这里以我另一个项目为例，我在 gradlePlugin 中指定的代码块自定义名称为 transfrom ：

gradlePlugin {
    plugins {
        transform {
			 // ...
        }
    }
}

引用成功后会在 Gradle Task 中多一个同名的任务：

Android Gradle 插件自定义Plugin实现注意事项

对应的 Groovy 中实现 apply 方法：

@Override
void apply(Project project) {
    project.tasks.register("transform") {
        doLast {
            println("Hello from plugin 'com.chunyu.transform.plugin'")
        }
    }
}

执行该任务，会看到 log 面板中有对应的输出：