点赞关注，不再迷路，你的支持对我意义重大！

🔥 Hi，我是丑丑。本文 GitHub · Android-NoteBook 已收录，这里有 Android 进阶成长路线笔记 & 博客，欢迎跟着彭丑丑一起成长。（联系方式在 GitHub）

提示 2022年4月30日

这篇文章是 2021 年写的，今年我更新了一些新内容，你可以直接看：手把手带你自定义 Gradle 插件 —— Gradle 系列(2)

---

目录

---

1. 前置知识

这篇文章的内容会涉及以下前置 / 相关知识，贴心的我都帮你准备好了，请享用~

• Gradle 筑基： 「Gradle」| 筑基篇（概念 & Groovy & 配置 & 命令）

• Gradle 进阶： 「Gradle」| 进阶篇（Project & Task & 构建生命周期）

• 官方文档： Developing Custom Gradle Plugins

---

2. Gradle 插件概述

2.1 什么是 Gradle？什么是 Gradle 插件？

Gradle 插件的本质就是抽取高度模块化的逻辑，以便更高效地进行复用。 Gradle 和 Gradle 插件是两个概念，在前面的文章里，你已经了解过 Gradle 的核心工作原理。简单来说，Gradle 只是提供了一个构建流程。而其他可复用的 Task（例如编译 Java 工程、编译 Android 工程等），是通过应用 Gradle 插件来获取的。

• Gradle： 构建工具，提供核心构建流程
• Gradle 插件： 本质上是可复用的 task，依赖于 Gradle 环境

2.2 插件类型

Gradle 插件分为两大类：脚本插件 & 对象插件。

• 脚本插件： 一个脚本插件和一个普通的 build.gradle 文件没什么区别，虽然简单，但它是模块化的基础。脚本可以存在本地，也可以存在网络上，只需要提供脚本的相对路径或者 URL，例如：

apply other.gradle

• 对象插件： 编写一个对象插件的最低要求是提供一个 org.gradle.api.Plugin 接口的实现类，这个接口只要一个Plugin#apply(Project)方法。

Plugin.Java

package org.gradle.api;

public interface Plugin<T> {
    void apply(T var1);
}

2.3 应用插件

在 build.gradle 文件中，可以使用 apply 方法来应用插件，有两种语法：

• 语法 1：

apply plugin 'groovy'

• 语法 2：

plugins {
    id 'groovy'
    id 'maven'
}

这里的 id 是插件的简短名称，是在插件中resources/META-INF/gradle-plugins/[id].properties文件的文件名决定的。

注意： 在一个 build.gradle 中不要同时使用这两种语法。

---

3. 自定义插件

这一节，我们开始讨论自定义插件的细节。前面提到 Gradle 插件分为脚本插件 & 对象插件，因为脚本插件比较简单，同时使用较少，所以我们以讨论对象插件为主。

踩坑： 笔者在学习 Gradle 插件时踩了一个深坑，即：setting.gradle 中如果存在rootProjet.name='项目名'，那么在应用插件并 sync 后会报错：

An exception occurred applying plugin request [id 'hello'] > Failed to apply plugin [id 'hello']  > No such property: project for class HelloPlugin

删除rootProjet.name='项目名'就不会报这个问题，原因未查。

3.1 步骤一：创建插件项目

首先，我们需要创建一个单独存放插件代码的 Module。Module 的命名可以是任意的，不过倒是有一个特殊的 Module 名 —— 「buildSrc」。要点如下：

• 1、这个目录可以被自动识别为 Module，不需要在 setting.gradle 中进行包含；
• 2、在构建时自动编译打包并添加到 buildScript 中的 classpath 下，不需要手动发布插件；
• 3、buildSrc 编译时间先于工程编译。

3.2 步骤二：初始化插件项目

我们对新建的插件项目进行以下操作：

• 1、（可选，如果你的项目中用不到 Java 代码）移除 Java 文件夹；
• 2、（必选）添加 groovy 文件夹，用于存放插件代码；
• 3、（必选）添加 resources 文件夹，用于配置插件描述符；
• 4、（必选）修改 build.gradle 内容。

下面介绍下第 3、4 步：

3.2.1 配置插件描述符

你需要新建一个*.properties文件，存放路径为：

main
├── groovy
├── resources 
    ├── META-INF
        ├── gradle-plugins
            ├── *.properties

提示： 你可以通过 sourceSets {} 闭包方法来设置 resources 文件夹的位置。

这里只需要记住两个要点：

• 1、*.properties 文件名是插件的剪短名称（id），用于应用插件。例如：

com.xurui.plugin.properties 

• 2、*.properties 文件内容配置了插件实现类的映射，需要使用implementation-class来指定插件实习类的全限定类名。例如：

implementation-class=com.xurui.plugin.HelloPlugin 

3.2.2 修改 build.gradle 内容

插件 build.gradle

plugins {
    id 'groovy' // （必选）用于实现插件
    id 'maven' // 用于发布插件
}

dependencies {
    implementation gradleApi()
    implementation localGroovy()
}

// 设置源文件路径
sourceSets {
    main {
        groovy {
            srcDir 'src/main/groovy'
        }

        resources {
            srcDir 'src/main/resources'
        }
    }
}

应用 Groovy 插件，并将 Gradle API 添加为编译时依赖项。在 External Libraries 中生成三个 jar 文件：

3.3 步骤三：实现插件

在 groovy 文件夹下实现插件的主题逻辑，例如：

com.xurui.plugin.HelloPlugin.groovy

class HelloPlugin implements Plugin<Project  > {
    @Override
    void apply(Project target) {
        println "自定义插件"
    }
}

提示： 文件后缀使用.groovy。

3.4 步骤四：应用插件

在 build.gradle 文件中，可以使用 apply 方法来应用插件，有两种语法。例如：

• 语法 1：

apply plugin 'com.xurui.plugin'
apply plugin 'com.android.application'

• 语法 2：

plugins {
    id 'com.xurui.plugin'
    id 'com.android.application'
}

应用插件后，从构建过程输出（Build Output）就可以看到我们的插件生效了：

Executing tasks: [:app:generateDebugSources] in project  E:\workspace\...

【初始化阶段结束】，总共耗时：9ms

> Configure project :app
自定义插件
【配置阶段结束】，总耗时：1864ms

> Task :app:preBuild UP-TO-DATE
> Task :app:preDebugBuild UP-TO-DATE
> Task :app:checkDebugManifest UP-TO-DATE
> Task :app:compileDebugAidl NO-SOURCE
...
> Task :app:assembleDebug
【执行阶段结束】，总耗时：141ms

BUILD SUCCESSFUL in 2s
4 actionable tasks: 4 up-to-date

---

4. 发布 & 依赖插件

发布插件有两种选择，这两种选择其实无非是发布的地址不同：

• 发布到本地仓库；
• 发布到远程仓库。

4.1 插件的属性

发布的插件需要配置三个属性，这三个属性共同形成了插件的唯一表示：

插件属性	描述
groupId	组织 / 公司名称
artifactId	项目 / 模块名称
version	项目 / 模块的当前版本号

4.2 配置插件属性

我们使用 mavenDeployer 插件 来发布仓库，你需要在插件 build.gradle 中增加以下配置：

插件 build.gradle

plugins {
    id 'groovy' // （必选）用于实现插件
    id 'maven' // （mavenDeployer 插件）用于发布插件
}

...

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: uri('../repo')) // 插件的输出路径
            pom.groupId = 'xurui_groupId'
            pom.artifactId = 'xurui_artifactId'
            pom.version = '1.0.0'
        }
    }
}

如果需要发布到远程仓库，只需要修改 repository url 地址，例如：

repository(url: RELEASE_URL) {
    authentication(userName: "xurui", password: "xxx")
}

4.3 发布插件

随后，执行gradlew uploadArchives命令（注意相对路径）来执行这个 uploadArchives task，实现插件发布。也可以使用 Gradle window 快速执行：

发布完成后在指定路径下就会生成插件文件：

4.4 依赖插件

提示： 如果在 buildSrc 目录下实现插件，就不要手动添加依赖了。Gradle 会自动将 buildSrc 构建产物加入到 classpath。

在需要依赖插件的项目里，我们需要添加插件到 classpath 中。例如：

项目根 build.gradle

buildscript {
    repositories {
        google()
        jcenter()
        maven { url uri('./repo') }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.3'
        classpath 'xurui_groupId:xurui_artifactId:1.0.0'
    }
}

allprojects {
    repositories {
        google()
        jcenter()

    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

其中 xurui_groupId 是 group，xurui_artifactId 是 artifactId，1.0.0 是版本号，也可以用这种语法：

dependencies {
     classpath group: 'xurui_groupId ', name: 'xurui_artifactId ', version: '1.0.0'
 }

4.5 应用插件

完成这一步，就可以顺利应用插件了：

项目 build.gradle

plugins {
    id 'com.xurui.plugin'
    id  'com.android.application'
}

---

5. 自定义 Extension 与 Task

Editting...

---

6. 总结

• Gradle 是构建工具，提供核心构建流程，而 Gradle 插件 本质上是可复用的 task，依赖于 Gradle 环境；
• 插件类型分为脚本插件 & 对象插件，对象插件使用比较多；
• 这篇文章主要是手把手带你完成自定义插件的步骤，希望能帮助你避坑。在后面的文章里，我将和你一起使用自定义 Gradle 插件完成实战功能。请关注~

---

参考资料

• 《Gradle核心思想（六）自定义Gradle插件的三种方式》 —— 刘望舒 著
• 《深度探索 Gradle 自动化构建技术（四、自定义 Gradle 插件）》 —— JsonChao 著
• 《实战 Gradle》（第 8 章）—— [美] Benjamin Muschko 著

---

创作不易，你的「三连」是丑丑最大的动力，我们下次见！