1. 程式人生 > >擁抱 Android Studio 之五:Gradle 外掛開發

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

 轉載處: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》系列第五篇,其他篇請點選: