了解 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 {
        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
}

此页面对您有帮助吗？