声明依赖基础 - Gradle 构建系统

依赖类型

在 Gradle 中有三种主要的依赖类型

模块依赖项：指向来自外部仓库的库。
项目依赖项：指向同一多项目构建中的其他项目。
文件依赖项：指向本地文件或目录，例如 .jar 或 .aar 文件。

1. 模块依赖项

模块依赖项是最常见的依赖项。它们指向通过模块坐标（组、名称和版本）标识的依赖项。

build.gradle.kts

dependencies {
    runtimeOnly(group = "org.springframework", name = "spring-core", version = "2.5")
    runtimeOnly("org.springframework:spring-aop:2.5")
    runtimeOnly("org.hibernate:hibernate:3.0.5") {
        isTransitive = true
    }
    runtimeOnly(group = "org.hibernate", name = "hibernate", version = "3.0.5") {
        isTransitive = true
    }
}

build.gradle

dependencies {
    runtimeOnly group: 'org.springframework', name: 'spring-core', version: '2.5'
    runtimeOnly 'org.springframework:spring-core:2.5',
            'org.springframework:spring-aop:2.5'
    runtimeOnly(
        [group: 'org.springframework', name: 'spring-core', version: '2.5'],
        [group: 'org.springframework', name: 'spring-aop', version: '2.5']
    )
    runtimeOnly('org.hibernate:hibernate:3.0.5') {
        transitive = true
    }
    runtimeOnly group: 'org.hibernate', name: 'hibernate', version: '3.0.5', transitive: true
    runtimeOnly(group: 'org.hibernate', name: 'hibernate', version: '3.0.5') {
        transitive = true
    }
}

Gradle 提供了多种用于声明模块依赖项的记法，包括字符串记法和映射记法。

字符串记法： 通过将组、名称和版本合并到一个字符串中来简化依赖项声明。
映射记法： 允许单独指定坐标的每个部分。

模块依赖项使用 ExternalModuleDependency 和 DependencyHandler API。这些 API 提供了各种属性和配置方法用于定义依赖项。

对于高级配置，例如强制严格版本，在使用这些记法的同时，您还可以提供一个闭包。

2. 项目依赖项

项目依赖项允许您在多项目 Gradle 构建中引用其他项目。

dependency management project dependencies

这对于将大型项目组织成更小、模块化的组件很有用。

web-service/build.gradle.kts

dependencies {
    implementation(project(":utils"))
    implementation(project(":api"))
}

web-service/build.gradle

dependencies {
    implementation project(':utils')
    implementation project(':api')
}

Gradle 使用 project() 函数来定义项目依赖项。此函数接受构建内目标项目的相对路径。路径通常使用冒号 (:) 来分隔项目结构的不同级别。

项目依赖项会自动解析，以便被依赖的项目总是在依赖它的项目之前构建。

类型安全的项目依赖项

类型安全的项目访问器是一个孵化中的功能，必须显式启用。其实现随时可能更改。

要添加对类型安全的项目访问器的支持，请将 enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") 添加到您的 settings.gradle(.kts) 文件中。

settings.gradle.kts

enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")

settings.gradle

enableFeaturePreview 'TYPESAFE_PROJECT_ACCESSORS'

使用 project(":some:path") 记法的一个缺点是需要记住依赖项的项目路径。此外，更改项目路径需要手动更新所有出现的地方，这增加了遗漏的风险。

取而代之的是，实验性的类型安全的项目访问器 API 提供了 IDE 补全功能，使依赖项声明变得更容易。

web-service/build.gradle.kts

dependencies {
    implementation(projects.utils)
    implementation(projects.api)
}

web-service/build.gradle

dependencies {
    implementation projects.utils
    implementation projects.api
}

使用此 API，Kotlin DSL 脚本中错误指定的项目会触发编译错误，从而帮助您避免遗漏更新。

项目访问器基于项目路径。例如，路径 :commons:utils:some:lib 变为 projects.commons.utils.some.lib，而 kebab-case (some-lib) 和 snake-case (some_lib) 则转换为 camel case：projects.someLib。

3. 文件依赖项

文件依赖项允许您通过引用其文件路径将外部 JAR 或其他文件直接包含到您的项目中。文件依赖项还允许您将一组文件直接添加到配置中，而无需使用仓库。

通常不建议使用文件依赖项。相反，首选声明对外部仓库的依赖，或者如果需要，使用 file:// URL 声明 Maven 或 Ivy 仓库。

文件依赖项是独特的，因为它们表示对文件系统上文件的直接引用，而不包含任何相关的元数据，例如传递依赖项、来源或作者信息。

build.gradle.kts

configurations {
    create("antContrib")
    create("externalLibs")
    create("deploymentTools")
}

dependencies {
    "antContrib"(files("ant/antcontrib.jar"))
    "externalLibs"(files("libs/commons-lang.jar", "libs/log4j.jar"))
    "deploymentTools"(fileTree("tools") { include("*.exe") })
}

build.gradle

configurations {
    antContrib
    externalLibs
    deploymentTools
}

dependencies {
    antContrib files('ant/antcontrib.jar')
    externalLibs files('libs/commons-lang.jar', 'libs/log4j.jar')
    deploymentTools(fileTree('tools') { include '*.exe' })
}

在此示例中，每个依赖项都显式指定其在文件系统中的位置。引用这些文件的常用方法包括：

Project.files()：直接接受一个或多个文件路径。
ProjectLayout.files()：直接接受一个或多个文件路径。
Project.fileTree()：定义一个目录并包含或排除特定的文件模式。

FileTree 中文件的顺序不能保证是稳定的，即使在同一台计算机上也是如此。因此，使用 FileTree 的依赖配置可能会产生顺序不同的解析结果，这会影响使用这些结果作为输入的任务的可缓存性。为了确保更可预测和稳定的行为，建议尽可能使用更简单的 files 方法。

或者，您可以使用平面目录仓库来指定多个文件依赖项的源目录。

理想情况下，您应该使用带本地 URL 的 Maven 或 Ivy 仓库。

repositories {
    maven {
        url = 'file:///path/to/local/files' // Replace with your actual path
    }
}

要将文件添加为依赖项，请将文件集合传递给配置。

build.gradle.kts

dependencies {
    runtimeOnly(files("libs/a.jar", "libs/b.jar"))
    runtimeOnly(fileTree("libs") { include("*.jar") })
}

build.gradle

dependencies {
    runtimeOnly files('libs/a.jar', 'libs/b.jar')
    runtimeOnly fileTree('libs') { include '*.jar' }
}

请注意，文件依赖项不包含在您项目的已发布依赖描述符中。但是，它们在同一构建中的传递依赖项中可用，这意味着它们可以在当前构建中使用，但不能在构建外部使用。

您应该指定哪些任务为文件依赖项生成文件。否则，当您从另一个项目传递依赖这些文件时，必要的任务可能不会运行。

build.gradle.kts

dependencies {
    implementation(files(layout.buildDirectory.dir("classes")) {
        builtBy("compile")
    })
}

tasks.register("compile") {
    doLast {
        println("compiling classes")
    }
}

tasks.register("list") {
    val compileClasspath: FileCollection = configurations["compileClasspath"]
    dependsOn(compileClasspath)
    doLast {
        println("classpath = ${compileClasspath.map { file: File -> file.name }}")
    }
}

build.gradle

dependencies {
    implementation files(layout.buildDirectory.dir('classes')) {
        builtBy 'compile'
    }
}

tasks.register('compile') {
    doLast {
        println 'compiling classes'
    }
}

tasks.register('list') {
    FileCollection compileClasspath = configurations.compileClasspath
    dependsOn compileClasspath
    doLast {
        println "classpath = ${compileClasspath.collect { File file -> file.name }}"
    }
}

$ gradle -q list
compiling classes
classpath = [classes]

特定于 Gradle 发行版的依赖项

Gradle API 依赖项

您可以使用 DependencyHandler.gradleApi() 方法声明对当前版本 Gradle API 的依赖。这在您开发自定义 Gradle 任务或插件时很有用。

build.gradle.kts

dependencies {
    implementation(gradleApi())
}

build.gradle

dependencies {
    implementation gradleApi()
}

Gradle TestKit 依赖项

您可以使用 DependencyHandler.gradleTestKit() 方法声明对当前版本 Gradle TestKit API 的依赖。这对于编写和执行 Gradle 插件和构建脚本的功能测试很有用。

build.gradle.kts

dependencies {
    testImplementation(gradleTestKit())
}

build.gradle

dependencies {
    testImplementation gradleTestKit()
}

本地 Groovy 依赖项

您可以使用 DependencyHandler.localGroovy() 方法声明对 Gradle 发行版附带的 Groovy 的依赖。这在您使用 Groovy 开发自定义 Gradle 任务或插件时很有用。

build.gradle.kts

dependencies {
    implementation(localGroovy())
}

build.gradle

dependencies {
    implementation localGroovy()
}

记录依赖项

在声明依赖项或依赖约束时，您可以提供一个原因来阐明包含该依赖项的原因。这有助于您的构建脚本和依赖洞察报告更易于理解。

build.gradle.kts

plugins {
    `java-library`
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.ow2.asm:asm:7.1") {
        because("we require a JDK 9 compatible bytecode generator")
    }
}

build.gradle

plugins {
    id 'java-library'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation('org.ow2.asm:asm:7.1') {
        because 'we require a JDK 9 compatible bytecode generator'
    }
}

在此示例中，because() 方法提供了包含 asm 库的原因，这有助于解释其在构建上下文中的用途。

$ gradle -q dependencyInsight --dependency asm
org.ow2.asm:asm:7.1
  Variant compile:
    | Attribute Name                 | Provided | Requested    |
    |--------------------------------|----------|--------------|
    | org.gradle.status              | release  |              |
    | org.gradle.category            | library  | library      |
    | org.gradle.libraryelements     | jar      | classes      |
    | org.gradle.usage               | java-api | java-api     |
    | org.gradle.dependency.bundling |          | external     |
    | org.gradle.jvm.environment     |          | standard-jvm |
    | org.gradle.jvm.version         |          | 11           |
   Selection reasons:
      - Was requested: we require a JDK 9 compatible bytecode generator

org.ow2.asm:asm:7.1
\--- compileClasspath

A web-based, searchable dependency report is available by adding the --scan option.

此页面有帮助吗？