了解 Gradle 模組元資料 - Gradle 繁體中文

Gradle 模組元資料是一種用於序列化 Gradle 元件模型的格式。它類似於 Apache Maven™ 的 POM 檔案或 Apache Ivy™ ivy.xml 檔案。元資料檔案的目標是為使用者提供在儲存庫中發布內容的合理模型。

Gradle 模組元資料是一種獨特的格式，旨在透過使其成為多平台且具備變異感知，來改善相依性解析。

特別是，Gradle 模組元資料支援

發布 Gradle 模組元資料將能為使用者提供更好的相依性管理

透過偵測不相容的模組，提早發現問題
一致地選擇特定於平台的相依性
原生相依性版本比對
自動取得特定函式庫功能的相依性

使用Maven 發布外掛或Ivy 發布外掛時，會自動發布 Gradle 模組元資料。

Gradle 模組元資料的規格可以在這裡找到。

與其他格式對應

Gradle 模組元資料會自動發佈在 Maven 或 Ivy 存放庫中。不過，它並不會取代 pom.xml 或 ivy.xml 檔案：它會與這些檔案一起發佈。這樣做是為了最大化與第三方建置工具的相容性。

Gradle 會盡力將 Gradle 特有的概念對應到 Maven 或 Ivy。當建置檔案使用只能在 Gradle 模組元資料中表示的功能時，Gradle 會在發佈時警告您。下表摘要說明如何將一些 Gradle 特有的功能對應到 Maven 和 Ivy

表 1. 將 Gradle 特有的概念對應到 Maven 和 Ivy
Gradle	Maven	Ivy	說明
相依性約束	`<dependencyManagement>` 相依性	未發佈	Gradle 相依性約束是「傳遞性的」，而 Maven 的相依性管理區塊則「不是」
豐富的版本約束	發佈「需要」版本	發佈「需要」版本
元件功能	未發佈	未發佈	元件功能是 Gradle 特有的
功能變異	變異人工製品已上傳，相依性已發佈為「選用」相依性	變異人工製品已上傳，相依性未發佈	功能變異是選用相依性的良好替代方案
自訂元件類型	人工製品已上傳，相依性是對應中所描述的那些	人工製品已上傳，相依性已略過	自訂元件類型可能無法從 Maven 或 Ivy 消費。它們通常存在於自訂生態系統的環境中。

停用元資料相容性發佈警告

如果您想要抑制警告，可以使用下列 API 來執行此動作

對於 Maven，請參閱 MavenPublication 中的 suppress* 方法
對於 Ivy，請參閱 IvyPublication 中的 suppress* 方法

範例 1. 停用發佈警告

build.gradle.kts

publications {
    register<MavenPublication>("maven") {
        from(components["java"])
        suppressPomMetadataWarningsFor("runtimeElements")
    }
}

build.gradle

publications {
    maven(MavenPublication) {
        from components.java
        suppressPomMetadataWarningsFor('runtimeElements')
    }
}

與其他建置工具的互動

由於 Gradle 模組元資料並未廣泛傳播，而且它旨在最大化與其他工具的相容性，因此 Gradle 會執行下列幾件事

Gradle 模組元資料會系統性地與給定存放庫（Maven 或 Ivy）的正常描述符一起發佈
pom.xml 或 ivy.xml 檔案將包含「標記註解」，告訴 Gradle 此模組存在 Gradle 模組元資料

標記的目標並非讓其他工具解析模組的元資料：它僅供 Gradle 使用者使用。它向 Gradle 說明存在一個更佳的模組元資料檔案，且它應該改用該檔案。這並不表示從 Maven 或 Ivy 的使用會中斷，只表示它會以降級模式運作。

這必須視為效能最佳化：Gradle 會先查看最有可能存在的檔案，而不是必須執行 2 次網路要求，一次取得 Gradle 模組元資料，另一次在遺漏的情況下取得 POM/Ivy 檔案，然後僅在模組實際上已使用 Gradle 模組元資料發佈時才執行第二次要求。

如果您知道您依賴的模組總是使用 Gradle 模組元資料發佈，您可以透過設定儲存庫的元資料來源來最佳化網路呼叫

範例 2. 僅解析 Gradle 模組元資料

build.gradle.kts

repositories {
    maven {
        setUrl("http://repo.mycompany.com/repo")
        metadataSources {
            gradleMetadata()
        }
    }
}

build.gradle

repositories {
    maven {
        url "http://repo.mycompany.com/repo"
        metadataSources {
            gradleMetadata()
        }
    }
}

Gradle 模組元資料驗證

Gradle 模組元資料會在發佈前進行驗證。

強制執行下列規則

變異名稱必須唯一，
每個變異至少必須具備一個屬性，
兩個變異無法具備完全相同的屬性和功能，
如果存在相依性，則在所有變異中至少一個必須載有版本資訊。

這些規則可確保所產生的元資料品質，並協助確認使用不會有問題。

Gradle 模組元資料可重製性

由於實作方式，產生模組元資料檔案的任務目前從未由 Gradle 標記為UP-TO-DATE。不過，如果建置輸入或建置指令碼都沒有變更，則任務結果實際上是最新狀態：它總是產生相同的輸出。

如果使用者希望每個建置呼叫都有唯一的module檔案，則可以將所產生的元資料中的識別碼連結到建立它的建置。使用者可以在其publication中選擇啟用這個唯一識別碼

範例 3. 設定刊物的建置識別碼

build.gradle.kts

publishing {
    publications {
        create<MavenPublication>("myLibrary") {
            from(components["java"])
            withBuildIdentifier()
        }
    }
}

build.gradle

publishing {
    publications {
        myLibrary(MavenPublication) {
            from components.java
            withBuildIdentifier()
        }
    }
}

使用上述變更後，所產生的 Gradle 模組元資料檔案將永遠不同，強制下游任務將其視為過期。

停用 Gradle 模組元資料發佈

在某些情況下，您可能想要停用 Gradle 模組元資料的發佈

您上傳到的儲存庫拒絕元資料檔案（格式不明）
您使用的是 Maven 或 Ivy 特定概念，而這些概念無法正確對應到 Gradle 模組元資料

在這種情況下，停用 Gradle 模組元資料的發佈只要停用產生元資料檔案的任務即可

範例 4. 停用 Gradle 模組元資料的發佈

build.gradle.kts

tasks.withType<GenerateModuleMetadata> {
    enabled = false
}

build.gradle

tasks.withType(GenerateModuleMetadata) {
    enabled = false
}

此頁面有幫助嗎？