Gradle系列之Java Gradle插件

前面幾篇學習了 Gradle 構建任務的基礎知識，建議先閱讀前面幾篇文章：

上篇文章中了解了 Gradle 插件相關知識以及如何自定義一個 Gradle 插件，本篇文章主要來學習 Java Gradle 插件相關的知識，因為 Java Gradle 插件相關的內容也是 Android Gradle 插件的基礎。使用 Gradle 來構建項目無非就是幫助開發者做一些重複性的工作，如配置第三方依賴、編譯源文件、單元測試、打包發布等，使用相應的 Gradle 插件可方便項目的構建以及一定程度上提高開發效率，下面是今天學習的主要內容：

Java Gradle 插件的使用
Java 插件約定的項目結構
配置第三方依賴
如何構建 Java 項目
SourceSet 源集概念
Java 插件可添加的任務
Java 插件可添加的屬性
多項目構建
發布構件

Java Gradle 插件的使用#

使用一個 Gradle 插件使用的是 Project 的 apply () 方法：

//java是Java Gradle插件的plugin id
apply plugin:'java'

使用 Java 插件之後會為當前工程添加默認設置和約定，如源代碼的位置、單元測試代碼的位置、資源文件的位置等，一般使用默認設置即可。

Java 插件約定的項目結構#

Java 插件設置一些默認的設置和約定，下面來看一看 Java 項目的默認工程目錄，目錄結構基本如下：

JavaGradle
└─src
    ├─main
    │  ├─java
    │  └─resources
    └─test
        ├─java
        └─resources

上面目錄結構中，src/main/java 默認是源代碼存放目錄，src/main/resources 是資源文件、配置文件等目錄，src/test 下面的目錄當然是與其相對應的單元測試相關文件的存儲目錄，main 和 test 是 Java Gradle 插件內置的兩個源代碼集合，當然除此之外可以自己定義其他源代碼集合，定義方式如下：

apply plugin : 'java'

sourceSets{
    //指定新的源代碼集合
    vip{
        
    }
}

然後在 src 下面創建相應的 java 和 resources 目錄，具體目錄下存放的文件內容與默認類似，默認目錄結構如下：

//源代碼目錄
src/vip/java
//資源文件目錄
src/vip/resource

上述目錄結構都是 Java Gradle 插件默認實現的，當然還可以修改具體目錄的位置，配置方式如下：

sourceSets{
    //修改默認目錄，下面還是和默認位置一樣，如需配置其他目錄修改即可
    main{
        java{
            srcDir 'src/java'
        }
        
        resources{
            srcDir 'src/resources'
        }
        
    }
}

配置第三方依賴#

開發過程中總會使用第三方 jar 包，此時就要對 jar 包進行依賴配置，依賴的倉庫類型以及倉庫的位置，具體依賴時 Gradle 就會從配置的倉庫中去尋找相關依賴，配置倉庫和配置具體依賴參考如下：

//配置倉庫位置
repositories{
    //倉庫類型如jcenter庫、ivy庫、maven中心庫、maven本地庫、maven私服庫等
    mavenCentral()
    mavenLocal()
    maven {
        uri "http"//xxxx
    }
    jcenter()
    google()
    //...
}

//配置具體的依賴
dependencies{
    //依賴三要素：group(組別)、name(名稱)、version(版本)
    //分別對應Maven中的GAV(groupid、artifactid、version)
    
    //完整寫法
    compile group: 'com.squareup.okhttp3', name: 'okhttp', version:'3.0.1'
    //簡寫
    compile 'com.squareup.okhttp3:okhttp:3.0.1'
}

上述代碼中 compile 是一個編譯時依賴，Gradle 還提供了其他依賴，具體參考如下：

compile：編譯時依賴
runtime：運行時依賴
testCompile：測試時編譯時依賴
testRuntime：僅在測試用例運行時依賴
archives：發布構件時依賴，如jar包等
default：默認依賴配置

在 Gradle 3.0 之後還會有 implementation、api 來替代 compile，這裡就不多說這兩個依賴方式了，關於新 API 的學習不是本文的重點，Java Gradle 插件還支持為不同的源代碼集合指定不同的依賴，具體參考如下：

//為不同的源代碼集合配置不同的依賴
dependencies{
    //配置格式：sourceSetCompile、sourceSetRuntime
    mainCompile 'com.squareup.okhttp3:okhttp:3.0.1'
    vipCompile 'com.squareup.okhttp3:okhttp:2.0.1'
}

上面介紹的是某個外部庫的依賴，除此之外在開發中還會遇到 Module 的依賴、文件的依賴，實際上 Module 的依賴實際上就是某個子項目的依賴，文件依賴一般就是 jar 包的依賴。

在 Gradle 系列之構建腳本基礎這篇文章中已經知道構建某個子項目必須在 setting.gradle 文件中使用 include 關鍵字將子項目引入進來，這裡也是一樣，現在 setting.gradle 文件中要依賴的項目引入進來，然後按照如下方式依賴某個子項目，具體如下：

//依賴一個子項目
dependencies{
    //setting.gradle文件中 include ':childProject'
    
    //依賴子項目
    compile project('childProject')
}

文件依賴主要就是 jar 包的依賴，一般都是將 jar 包放在項目的 libs 目錄下，然後在起來 jar 包，具體參考如下：

//依賴一個jar包
dependencies{
    //配置單個jar
    compile file('libs/java1.jar')
    //配置多個jar
    compile files('libs/java1.jar','libs/java2.jar')
    //批量配置jar,配置好jar所在路徑，會將後綴為jar的所有文件依賴到項目中
    compile fileTree(dir:'libs',include:'*.jar')
}

如何構建 Java 項目#

Gradle 中所有的操作都是基於任務的，Java Gradle 插件同樣內置了一系列的任務幫助我們構建項目，執行 build 任務 Gradle 就開始構建當前項目了，可以使用 gradlew build 開始執行構建任務，Gradle 會編譯源代碼文件、處理資源文件、生成 jar 包、編譯測試代碼、運行單元測試等。

如在 Android 開發中有個 clean 任務，執行 clean 操作就會刪除 build 文件夾以及其他構建項目生成的文件，如果編譯出錯可以嘗試向 clean 然後 build。此外還有 check 任務，該任務會在單元測試的時候使用到，javadoc 任務可以方便生成 Java 格式的 doc api 文檔，學習 Java 項目的構建目的還是為了學習 Android 項目構建做準備，所以如何使用 Gradle 構建一個 Java 項目就到此為止。

SourceSet 源集概念#

這一小節來認識一下 SourceSet ，這也就是前問中提到的源代碼集合，它是 Java Gradle 插件用來描述和管理源代碼及其資源的一個抽象概念，是一個 Java 源代碼文件和資源文件的集合，故可以通過源代碼集合配置源代碼文件的位置、設置源代碼集合的屬性等，源集可以針對不同的業務將源代碼分組管理，如 Java Gradle 插件默認提供的 main 和 test 源代碼目錄，一個用於業務代碼，另一個用於單元測試，非常方便。

Java Gradle 插件在 Project 下提供一個 sourceSet 屬性以及 sourceSet {} 閉包來訪問和配置源集，sourceSet 是一個 SourceSetContainer, 源集的常用屬性如下：

//比如main、test等表示源集的名稱
name(String)
//表示源集編譯後的class文件目錄
output.classDir(File)
//表示編譯後生成的資源文件目錄
output.resourcesDir(File)
//表示編譯後源集所需的classpath
compileClasspath(FileCollection)
//表示該源集的Java源文件
java(SourceDirectorySet)
//表示該源集的Java源文件所在目錄
java.srcDirs(Set)
//表示源集的資源文件
resources(SourceDirectorySet)
//表示該源集的資源文件所在目錄
resources.srcDirs(Set)

下面是設置 main 這個源集的輸出目錄，參考如下：

//設置某個源集的屬性
sourceSets{
    main{
        //源集名稱只讀
        println name
        //其他屬性設置
        //從4.0開始已經被過時。替代的是dir
        output.classesDir = file("a/b")
//        output.dir("a/b")
        output.resourcesDir = file("a/b")
        //....
    }
}

Java 插件可添加的任務#

項目的構建還是通過一系列 Gradle 插件提供的任務，下面是 Java 項目中常用的任務，具體如下：

任務名稱	類型	描述
默認源集通用任務
compileJava	JavaCompile	表示使用 javac 編譯 java 源文件
processResources	Copy	表示把資源文件複製到生成的資源文件目錄中
classes	Task	表示組裝產生的類和資源文件目錄
compileTestJava	JavaCompile	表示使用 javac 編譯測試 java 源文件
processTestResources	Copy	表示把資源文件複製到生成的資源文件目錄中
testClasses	Task	表示組裝產生的測試類和相關資源文件
jar	Jar	表示組裝 jar 文件
javadoc	Javadoc	表示使用 javadoc 生成 Java API 文檔
uploadArchives	Upload	表示上傳包含 Jar 的構建，使用 archives {} 閉包進行配置
clean	Delete	表示清理構建生成的目錄文件
cleanTaskName	Delete	表示刪除指定任務生成的文件，如 cleanJar 是刪除 jar 任務生成的文件
自定義源集任務		（SourceSet 是具體的源集名稱）
compileSourceSetJava	JavaCompile	表示使用 javac 編譯指定源集的源代碼
processSouceSetResources	Copy	表示把指定源集的資源文件複製到生成文件中的資源目錄中
sourcesSetClasses	Task	表示組裝給定源集的類和資源文件目錄

Java 插件可以添加的屬性#

Java Gradle 插件中的常用屬性都被添加到 Project 中，這些屬性可以直接使用，具體如下：

屬性名稱	類型	描述
sourceSets	SourceSetContauner	Java 項目的源集，可在閉包內進行相關配置
sourceCompatibility	JavaVersion	編譯 Java 源文件使用的 Java 版本
targetCompatinility	JavaVersion	編譯生成類的 Java 版本
archivesBaseName	String	打包成 jar 或 zip 文件的名稱
manifest	Manifest	用來訪問和配置 manifest 清單文件
libsDir	File	存放生成的類庫目錄
distsDir	File	存放生成的發布的文件目錄

多項目構建#

使用 Gradle 進行多個項目的構建，一般都是一個主項目依賴其他的子模塊項目，是否構建這些子項目主要在 Setting.gradle 文件中配置，是否使用這些子項目則必須要在主項目中配置項目依賴，上文中接受過依賴的三種方式：庫依賴、項目依賴和文件依賴，這裡使用到的就是項目依賴，多項目配置中經常使用到 subprojects 和 allprojects ，具體如下：

//子項目統一配置
subprojects{
    //配置子項目都使用Java Gradle插件
    apply plugin: 'java'
    //配置子項目都是用Maven中心庫
    repositories{
        mavenCentral()
    }
    //其他通用配置
    //...
}
//全部項目統一配置
allprojects{
    //配置所有項目都使用Java Gradle插件
    apply plugin: 'java'
    //配置所有項目都是用Maven中心庫
    repositories{
        mavenCentral()
    }
    //其他通用配置
    //...
}

發布構件#

Gradle 構建的產物，一般稱之為構件，一個構建可以是一個 jar 包、zip 包等，那麼如何發布構件呢，下面介紹如何發布一個 jar 構件到項目本地文件夾或 mavenLocal () 中，具體如下：

/**
 * 發布構件到項目文件夾/或mavenLocal()
 */
apply plugin : 'java'
//生成jar的任務，類似於自定義wrapper
task publishJar(type:Jar)
//構件版本
version '1.0.0'
//構件通過artifacts{}閉包配置
artifacts{
    archives publishJar
}
//構件發布上傳
uploadArchives{
    repositories{
        flatDir{
            name 'libs'
            dirs "$projectDir/libs"
        }
        //將構建發布到mavenLocal()
        mavenLocal()
    }
}

執行 uploadArchives 任務就會在相應的位置生成相應的 jar 文件，執行命令如下：

//執行uploadArchives
gradle uploadArchives

執行成功之後，就會在項目的 libs 目錄下看到生成的 jar 文件，如下圖所示：

執行成功之後，就會在用戶的 .m2/repository 目錄下看到生成的 jar 文件，如下圖所示：

下面是如何將 jar 發布到搭建的 maven 私服上，代碼參考如下：

/**
 * 發布構件到maven私服
 */
apply plugin : 'java'
apply plugin : 'maven'
//生成jar的任務，類似於自定義wrapper
task publishJar(type:Jar)
//構件版本
version '1.0.0'
//構件通過artifacts{}閉包配置
artifacts{
    archives publishJar
}
//構件發布上傳
uploadArchives{
    repositories{
        mavenDeployer{
            repository(url:'http://xxx'){
                //倉庫用戶名和密碼
                authentication(userName:'username',password:'pass')
            }
            snapshotRepository(url:'http://xxx'){
                authentication(userName:'username',password:'pass')
            }
        }
    }
}

上傳過程也是執行 uploadArchives 任務，有 maven 私服的可以嘗試一下，關於 Java Gradle 插件的學習就到此為止，下一篇正式進入 Android Gradle 插件的學習。