了解 Gradle 模块元数据

Gradle 模块元数据是一种用于序列化 Gradle 组件模型的格式。它类似于Apache Maven™ 的 POM 文件或Apache Ivy™ ivy.xml文件。元数据文件的目标是向消费者提供存储库上发布内容的合理模型。

Gradle 模块元数据是一种独特的格式，旨在通过使其具有多平台和变体感知能力来改进依赖关系解析。

特别是，Gradle 模块元数据支持：

Gradle 模块元数据的发布将为您的消费者提供更好的依赖管理：

使用Maven Publish 插件或Ivy Publish 插件时，Gradle 模块元数据会自动发布。

Gradle 模块元数据的规范可以在这里找到。

与其他格式的映射

Gradle 模块元数据自动发布在 Maven 或 Ivy 存储库上。但是，它不会替换pom.xml或ivy.xml文件：它与这些文件一起发布。这样做是为了最大限度地提高与第三方构建工具的兼容性。

Gradle 尽力将 Gradle 特定的概念映射到 Maven 或 Ivy。当构建文件使用只能在 Gradle 模块元数据中表示的功能时，Gradle 将在发布时向您发出警告。下表总结了一些 Gradle 特定功能如何映射到 Maven 和 Ivy：

表 1. Gradle 特定概念到 Maven 和 Ivy 的映射
摇篮	梅文	常春藤	描述
依赖约束	`<dependencyManagement>`依赖关系	未发表	Gradle 依赖约束是可传递的，而 Maven 的依赖管理块则不是
丰富版本限制	发布所需版本	发布了需要的版本
组件能力	未发表	未发表	组件功能是 Gradle 独有的
功能变体	上传变体工件，将依赖项发布为可选依赖项	变体工件已上传，依赖项未发布	功能变体是可选依赖项的良好替代品
自定义组件类型	工件已上传，依赖项是映射所描述的依赖项	工件已上传，依赖项被忽略	无论如何，自定义组件类型可能无法从 Maven 或 Ivy 中使用。它们通常存在于自定义生态系统的背景下。

禁用元数据兼容性发布警告

如果您想抑制警告，可以使用以下 API 来实现：

对于Maven，请参阅MavenPublicationsuppress*中的方法
对于Ivy，请参阅IvyPublicationsuppress*中的方法

Example 1. Disabling publication warnings

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 模块元数据发布，则可以通过配置存储库的元数据源来优化网络调用：

Example 2. Resolving Gradle Module Metadata only

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 模块元数据再现性

UP-TO-DATE由于其实现方式，生成模块元数据文件的任务目前从未被 Gradle 标记。但是，如果构建输入和构建脚本均未更改，则任务结果实际上是最新的：它始终生成相同的输出。

如果用户希望module每次构建调用都有一个唯一的文件，则可以将生成的元数据中的标识符链接到创建它的构建。用户可以选择在其以下位置启用此唯一标识符publication：

Example 3. Configuring the build identifier of a publication

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 模块元数据的发布：

Example 4. Disabling publication of Gradle Module Metadata

build.gradle.kts

tasks.withType<GenerateModuleMetadata> {
    enabled = false
}

build.gradle

tasks.withType(GenerateModuleMetadata) {
    enabled = false
}

此页面是否有帮助？