了解 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 的使用會被中斷，只是它在降級模式下工作。

這必須被視為一種效能最佳化：而不是需要進行 2 次網路請求，一次取得 Gradle 模組元數據，然後在遺失的情況下取得 POM/Ivy 檔，Gradle 將首先查看最有可能存在的檔案，然後僅在模組實際上是使用 Gradle 模組元數據發佈的情況下執行第二次請求。

如果您知道您相依的模組始終使用 Gradle 模組元數據發佈，則可以透過組態儲存庫的元數據來源來最佳化網路呼叫

範例 2. 僅解析 Gradle 模組元數據

build.gradle.kts

repositories {
    maven {
        url = uri("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 模組元數據的發佈

您要上傳到的儲存庫拒絕元數據檔（未知格式）
您正在使用未正確對應到 Gradle 模組元數據的 Maven 或 Ivy 特定概念

在這種情況下，停用 Gradle 模組元數據的發佈只需停用產生元數據檔的工作即可

範例 4. 停用 Gradle 模組元數據的發佈

build.gradle.kts

tasks.withType<GenerateModuleMetadata> {
    enabled = false
}

build.gradle

tasks.withType(GenerateModuleMetadata) {
    enabled = false
}

此頁面是否對您有幫助？