擁抱 Android Studio 之五：Gradle 外掛開發

阿新 • • 發佈：2019-01-10

轉載處：http://geek.csdn.net/news/detail/64058

實踐出真知

筆者有位朋友，每次新學一門語言，都會用來寫一個貪吃蛇遊戲，以此來檢驗自己學習的成果。筆者也有類似體會。所謂紙上得來終覺淺，絕知此事要躬行。這一章，筆者將以開發和釋出一個 Gradle 外掛作為目標，加深學習成果。

官方文件給出了比較詳細的實現步驟，本文的脈絡會跟官方文件差不了太多，額外增補實際例子和一些實踐經驗。文中的程式碼已經託管到了 github 專案中。

需求

預設的 Android 打包外掛會把 apk 命名成 module-productFlavor-buildType.apk，例如 app-official-debug.apk

，並且會把包檔案釋出到固定的位置： module/build/outputs/apk 有的時候，這個命名風格並不是你所要的，你也想講 apk 輸出到別的目錄。咱們通過 gradle 外掛來實現自定義。這個外掛的需求是：

輸入一個名為 nameMap 的 Closure，用來修改 apk 名字
輸入一個名為 destDir 的 String，用於輸出位置

原理簡述

外掛之於 Gradle

根據官方文件定義，外掛打包了可重用的構建邏輯，可以適用於不同的專案和構建過程。

Gradle 提供了很多官方外掛，用於支援 Java、Groovy 等工程的構建和打包。同時也提供了自定義外掛的機制，讓每個人都可以通過外掛來實現特定的構建邏輯，並可以把這些邏輯打包起來，分享給其他人。

外掛的原始碼可以使用 Groovy、Scala、Java 三種語言，筆者不會 Scala，所以平時只是使用 Groovy 和 Java。前者用於實現與 Gradle 構建生命週期（如 task 的依賴）有關的邏輯，後者用於核心邏輯，表現為 Groovy 呼叫 Java 的程式碼。

另外，還有很多專案使用 Eclipse 或者 Maven 進行開發構建，用 Java 實現核心業務程式碼，將有利於實現快速遷移。

外掛打包方式

Gradle 的外掛有三種打包方式，主要是按照複雜程度和可見性來劃分：

Build script

把外掛寫在 build.gradle 檔案中，一般用於簡單的邏輯，只在該 build.gradle 檔案中可見，筆者常用來做原型除錯，本文將簡要介紹此類。

buildSrc 專案

將外掛原始碼放在 rootProjectDir/buildSrc/src/main/groovy 中，只對該專案中可見，適用於邏輯較為複雜，但又不需要外部可見的外掛，本文不介紹，有興趣可以參考此處。

獨立專案

一個獨立的 Groovy 和 Java 專案，可以把這個專案打包成 Jar 檔案包，一個 Jar 檔案包還可以包含多個外掛入口，將檔案包釋出到託管平臺上，供其他人使用。本文將著重介紹此類。

Build script 外掛

首先來直接在 build.gradle 中寫一個 plugin：

class ApkDistPlugin implements Plugin<Project> {

    @Override
    void apply(Project project) {
        project.task('apkdist') << {
            println 'hello, world!'
        }
    }
}

apply plugin: ApkDistPlugin

命令列執行

$ ./gradlew -p app/ apkdist
:app:apkdist
hello, world!

這個外掛建立了一個名為 apkdist 的 task，並在 task 中列印。

外掛是一個類，繼承自 org.gradle.api.Plugin 介面，過載 void apply(Project project) 方法，這個方法將會傳入使用這個外掛的 project 的例項，這是一個重要的 context。

接受外部引數

通常情況下，外掛使用方需要傳入一些配置引數，如 bugtags 的 SDK 的外掛需要接受兩個引數:

bugtags {
    appKey "APP_KEY"  //這裡是你的 appKey
    appSecret "APP_SECRET"    //這裡是你的 appSecret，管理員在設定頁可以檢視
}

同樣，ApkDistPlugin 這個 plugin 也希望接受兩個引數：

apkdistconf {
    nameMap { name ->
        println 'hello,' + name
        return name
    }
    destDir 'your-distribution-dir'
}

引數的內容後面繼續完善。那這兩個引數怎麼傳到外掛內呢？

org.gradle.api.Project 有一個 ExtensionContainer getExtensions() 方法，可以用來實現這個傳遞。

宣告引數類

宣告一個 Groovy 類，有兩個預設值為 null 的成員變數：

class ApkDistExtension {
    Closure nameMap = null;
    String destDir = null;
}

接受引數

project.extensions.create('apkdistconf', ApkDistExtension);

要注意，create 方法的第一個引數就是你在 build.gradle 檔案中的進行引數配置的 dsl 的名字，必須一致；第二個引數，就是引數類的名字。

獲取和使用引數

在 create 了 extension 之後，如果傳入了引數，則會攜帶在 project 例項中，

def closure = project['apkdistconf'].nameMap;
closure('wow!');

println project['apkdistconf'].destDir

進化版本一：引數

class ApkDistExtension {
    Closure nameMap = null;
    String destDir = null;
}

class ApkDistPlugin implements Plugin<Project> {

    @Override
    void apply(Project project) {

        project.extensions.create('apkdistconf', ApkDistExtension);

        project.task('apkdist') << {
            println 'hello, world!'

            def closure = project['apkdistconf'].nameMap;
            closure('wow!');

            println project['apkdistconf'].destDir
        }
    }
}

apply plugin: ApkDistPlugin

apkdistconf {
    nameMap { name ->
        println 'hello, ' + name
        return name
    }
    destDir 'your-distribution-directory'
}

執行結果：

$ ./gradlew -p app/ apkdist
:app:apkdist
hello, world!
hello, wow!
your-distribution-directory

獨立專案外掛

程式碼寫到現在，已經不適合再放在一個 build.gradle 檔案裡面了，那也不是我們的目的。建立一個獨立專案，把程式碼搬到對應的地方。

理論上，IntelliJ IDEA 開發外掛要比 Android Studio 要方便一點點，因為有對應 Groovy module 的模板。但其實如果我們瞭解 IDEA 的專案檔案結構，就不會受到這個侷限，無非就是一個 build.gradle 構建檔案加 src 原始碼資料夾。

最終專案的資料夾結構是這樣：

Java-Library

下面我們來一步步講解。

建立專案

在 Android Studio 中新建 Java Library module “plugin”。

修改 build.gradle 檔案

新增 Groovy 外掛和對應的兩個依賴。

//removed java plugin 
apply plugin: 'groovy'

dependencies {
    compile gradleApi()//gradle sdk
    compile localGroovy()//groovy sdk
    compile fileTree(dir: 'libs', include: ['*.jar'])
}

修改專案資料夾

src/main 專案檔案下：

移除 java 資料夾，因為在這個專案中用不到 java 程式碼
新增 groovy 資料夾，主要的程式碼檔案放在這裡
新增 resources 資料夾，存放用於標識 gradle 外掛的 meta-data

建立對應檔案

.
├── build.gradle
├── libs
├── plugin.iml
└── src
    └── main
        ├── groovy
        │   └── com
        │       └── asgradle
        │           └── plugin
        │               ├── ApkDistExtension.groovy
        │               └── ApkDistPlugin.groovy
        └── resources
            └── META-INF
                └── gradle-plugins
                    └── com.asgradle.apkdist.properties

注意：

groovy 資料夾中的類，一定要修改成 .groovy 字尾，IDE 才會正常識別。
resources/META-INF/gradle-plugins 這個資料夾結構是強制要求的，否則不能識別成外掛。

com.asgradle.apkdist.properties 檔案

如果寫過 Java 的同學會知道，這是一個 Java 的 properties 檔案，是 key=value 的格式。這個檔案內容如下：

implementation-class=com.asgradle.plugin.ApkDistPlugin

按其語義推斷，是指定這個外掛的入口類。

英文敏感的同學可能會問了，為什麼這個檔案的承載資料夾是叫做 gradle-plugins，使用複數？沒錯，這裡可以指定多個 properties 檔案，定義多個外掛，擴充套件性一流，可以參考 linkedin 的外掛的組織方式。
使用這個外掛的時候，將會是這樣：
```
apply plugin:'com.asgradle.apkdist'
```
因此，com.asgradle.apkdist 這個字串在這裡，又稱為這個外掛的 id，不允許跟別的外掛重複，取你擁有的域名的反向就不會錯。

將 plugin module 傳到本地 maven 倉庫

新增 gradle.properties

PROJ_NAME=gradleplugin
PROJ_ARTIFACTID=gradleplugin
PROJ_POM_NAME=Local Repository

LOCAL_REPO_URL=file:///Users/changbinhe/Documents/Android/repo/

PROJ_GROUP=com.as-gradle.demo

PROJ_VERSION=1.0.0
PROJ_VERSION_CODE=1

PROJ_WEBSITEURL=http://kvh.io
PROJ_ISSUETRACKERURL=https://github.com/kevinho/Embrace-Android-Studio-Demo/issues
PROJ_VCSURL=https://github.com/kevinho/Embrace-Android-Studio-Demo.git
PROJ_DESCRIPTION=demo apps for embracing android studio

PROJ_LICENCE_NAME=The Apache Software License, Version 2.0
PROJ_LICENCE_URL=http://www.apache.org/licenses/LICENSE-2.0.txt
PROJ_LICENCE_DEST=repo

DEVELOPER_ID=your-dev-id
DEVELOPER_NAME=your-dev-name
DEVELOPER_EMAIL=[email protected]

在 build.gradle 新增上傳功能

apply plugin: 'maven'

uploadArchives {
    repositories.mavenDeployer {
        repository(url: LOCAL_REPO_URL)
        pom.groupId = PROJ_GROUP
        pom.artifactId = PROJ_ARTIFACTID
        pom.version = PROJ_VERSION
    }
}

上傳可以通過執行：

$ ./gradlew -p plugin/ clean build uploadArchives

在 app module 中使用外掛

在專案的 buildscript 新增外掛作為 classpath

buildscript {
    repositories {
        maven{
            url 'file:///Users/your-user-name/Documents/Android/repo/'
        }
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.1.0-alpha3'        
        classpath 'com.as-gradle.demo:gradleplugin:1.0.0'
    }
}

在 app module 中使用外掛：

apply plugin: 'com.asgradle.apkdist'

命令列執行：

$ ./gradlew -p app apkdist
:app:apkdist
hello, world!
hello, wow!
your-distribution-directory

可能會遇到問題

Error:(46, 0) Cause: com/asgradle/plugin/ApkDistPlugin : Unsupported major.minor version 52.0
<a href="openFile:/Users/your-user-name/Documents/git/opensource/embrace-android-studio-demo/s5-GradlePlugin/app/build.gradle">Open File</a>

應該是本機的 JDK 版本是1.8，預設將 plugin module 的 groovy 原始碼編譯成了1.8版本的 class 檔案，放在 Android 專案中，無法相容。需要對 plugin module 的 build.gradle 檔案新增兩個引數：

sourceCompatibility = 1.6
targetCompatibility = 1.6

真正的實現外掛需求

讀者可能會觀察到，到目前為止，外掛只是跑通了流程，並沒有實現本文提出的兩個需求，

那接下來就具體實現一下。

class ApkDistPlugin implements Plugin<Project> {

    @Override
    void apply(Project project) {

        project.extensions.create('apkdistconf', ApkDistExtension);

        project.afterEvaluate {

            //只可以在 android application 或者 android lib 專案中使用
            if (!project.android) {
                throw new IllegalStateException('Must apply \'com.android.application\' or \'com.android.library\' first!')
            }

            //配置不能為空
            if (project.apkdistconf.nameMap == null || project.apkdistconf.destDir == null) {
                project.logger.info('Apkdist conf should be set!')
                return
            }

            Closure nameMap = project['apkdistconf'].nameMap
            String destDir = project['apkdistconf'].destDir

            //列舉每一個 build variant
            project.android.applicationVariants.all { variant ->
                variant.outputs.each { output ->
                    File file = output.outputFile
                    output.outputFile = new File(destDir, nameMap(file.getName()))
                }
            }
        }
    }
}

必須指出，本文外掛實現的需求，其實可以直接在 app module 的 build.gradle 中寫指令碼就可以實現。這裡做成外掛，只是為了做示範。

後記

至此，這系列開篇的時候挖下的坑，終於填完了。很多人藉助這系列的講解，真正理解了 Android Studio 和它背後的 Gradle、Groovy，筆者十分高興。筆者也得到了很多讀者的鼓勵和支援，心中十分感激。

寫部落格真的是一個很講究執行力和耐力的事情，但既然挖下了坑，就得填上，對吧？

這半年來，個人在 Android 和 Java 平臺上也做了更多的事情，也有了更多的體會。

AS 系列，打算擴充幾個主題：

Proguard 混淆
Java & Android Testing
Maven 私有倉庫深入
持續整合
……待發掘

記得有人說，只懂 Android 不懂 Java，是很可怕的。在這半年以來，筆者在工作中使用 Java 實現了一些後端服務，也認真學習了 JVM 位元組碼相關的知識並把它使用到了工作中。在這個過程中，真的很為 Java 平臺的活力、豐富的庫資源、幾乎無止境的可能性所折服。接下來，會寫一些跟有關的學習體會，例如：

Java 多執行緒與鎖
JVM 部分原理
位元組碼操作
Java 8部分特性
……待學習

隨著筆者工作的進展，我也有機會學習使用了別的語言，例如 Node.js，並實現了一些後端服務。這個語言的活力很強，一些比 Java 現代的地方，很吸引人。有精力會寫一寫。

因為業務所需，筆者所經歷的系統，正在處於像面向服務的演化過程中，我們期望建立統一的通訊平臺和規範，抽象系統的資源，拆分業務，容器化。這是一個很有趣的過程，也是對我們的挑戰。筆者也希望有機會與讀者分享。

一不小心又挖下了好多明坑和無數暗坑，只是為了激勵自己不斷往前。在探索事物本質的旅途中，必然十分艱險，又十分有趣，沿途一定風光絢麗，讓我們共勉。

參考文獻

官方文件

系列導讀

本文是筆者《擁抱 Android Studio》系列第五篇，其他篇請點選：