依赖元数据是指与依赖项关联的、描述其特征、关系和要求的信息。

此元数据包括诸如以下详细信息:

  1. 身份:模块依赖项由其群组、名称和版本 (GAV) 坐标唯一标识。

  2. 依赖项:此依赖项所需的其他二进制文件的列表,包括它们的版本。

  3. 变体:组件的不同形式(例如,compile, runtime, apiElements, runtimeElements),可在不同上下文中使用。

  4. Artifacts:由组件产生的实际文件(如 JAR、ZIP 等),可能包括编译后的代码、资源或文档。

  5. 能力:描述模块提供或消耗的功能或特性,有助于在不同模块提供相同能力时避免冲突。

  6. 属性:用于区分变体的键值对(例如 org.gradle.jvm.version:8)。

根据仓库类型,依赖元数据以不同的格式存储

  • Gradle: Gradle Module Metadata (.module) 文件

  • Maven: Maven POM (pom.xml) 文件

  • Ivy: Ivy Descriptor (ivy.xml) 文件

有些仓库可能包含单个组件的多种元数据类型。当 Gradle 发布到 Maven 仓库时,它会发布 Gradle Module Metadata (GMM) 文件和 Maven POM 文件。

此元数据在依赖解析中起着关键作用,它允许在跟踪二进制 Artifact 本身的同时跟踪其依赖项。通过读取依赖元数据,Gradle 能够确定给定依赖项需要哪些版本的其他 Artifact。

在 Maven 中,一个模块可以有一个且只有一个 Artifact。在 Gradle 和 Ivy 中,一个模块可以有多个 Artifacts

支持的元数据格式

外部模块依赖项需要模块元数据,以便 Gradle 确定模块的传递性依赖项。Gradle 支持各种元数据格式来实现这一点。

Gradle Module Metadata (GMM) 文件

Gradle Module Metadata 专门设计用于支持 Gradle 依赖管理模型的所有功能,因此是首选格式。

您可以在此处找到规范

{
  "formatVersion": "1.1",
  "component": {
    "group": "com.example",
    "module": "my-library",
    "version": "1.0"
  }
}

POM 文件

Gradle 原生支持 Maven POM 文件。默认情况下,Gradle 会首先查找 POM 文件。但是,如果该文件包含一个特殊的标记,Gradle 将改用Gradle Module Metadata

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-library</artifactId>
  <version>1.0</version>
</project>

Ivy 文件

Gradle 也支持 Ivy 描述符文件。Gradle 会首先查找 ivy.xml 文件,但如果此文件包含一个特殊的标记,它将改用Gradle Module Metadata

<ivy-module version="2.0">
  <info organisation="com.example" module="my-library" revision="1.0"/>
  <dependencies>
    <dependency org="org.example" name="dependency" rev="1.2"/>
  </dependencies>
</ivy-module>

支持的元数据源

在仓库中搜索组件时,Gradle 默认会检查支持的元数据文件格式

  • Gradle 首先查找 .module (Gradle 模块元数据) 文件。

  • 在 Maven 仓库中,Gradle 接着查找 .pom 文件。

  • 在 Ivy 仓库中,它检查 ivy.xml 文件。

  • 在平面目录仓库中,它直接查找 .jar 文件,不期望任何元数据。

如果您定义自定义仓库,可以配置 Gradle 如何搜索元数据。例如,您可以设置一个 Maven 仓库,该仓库可以选择性地解析没有关联 POM 文件的 JAR。这通过配置仓库的元数据源来完成

build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/repo")
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}
build.gradle
repositories {
    maven {
        url = "http://repo.mycompany.com/repo"
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}

您可以指定多个元数据源,Gradle 将按预定义的顺序搜索它们。支持以下元数据源

元数据源 描述 默认顺序 Maven Ivy / 平面目录

gradleMetadata()

查找 Gradle .module 文件

第 1

mavenPom()

查找 Maven .pom 文件

第 2

ivyDescriptor()

查找 ivy.xml 文件

第 2

artifact()

直接查找没有关联元数据的 Artifact

第 3

默认情况下,Gradle 要求依赖项具有关联的元数据。

要放宽此要求并允许 Gradle 解析没有关联元数据的 Artifacts,请指定 artifact 元数据源

mavenCentral {
    metadataSources {
        mavenPom()
        artifact()
    }
}

上述示例指示 Gradle 首先从 POM 文件中查找组件元数据,如果不存在,则从 Artifact 本身派生元数据。

例如,如果您声明一个模块依赖项,Gradle 会在仓库中查找模块元数据文件 (.module, .pomivy.xml)。如果存在此类模块元数据文件,则会对其进行解析,并下载此模块的 Artifacts (例如,hibernate-3.0.5.jar) 及其依赖项 (例如,cglib)。如果不存在此类模块元数据文件,您需要配置元数据源定义以直接查找名为 hibernate-3.0.5.jar 的 Artifact 文件

repositories {
    maven {
        url "https://repo.example.com/maven"
        metadataSources {
            mavenPom()   // Look for a POM file
            artifact()   // If no metadata is found, look for JARs directly
        }
    }
}

解析元数据文件(Ivy 或 Maven)时,Gradle 会检查是否存在指示匹配的 Gradle Module Metadata 文件存在的标记。如果找到,Gradle 将优先使用 Gradle 元数据。

要禁用此行为,请使用 ignoreGradleMetadataRedirection() 选项

build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/repo")
        metadataSources {
            mavenPom()
            artifact()
            ignoreGradleMetadataRedirection()
        }
    }
}
build.gradle
repositories {
    maven {
        url = "http://repo.mycompany.com/repo"
        metadataSources {
            mavenPom()
            artifact()
            ignoreGradleMetadataRedirection()
        }
    }
}