依赖类型
在 Gradle 中有三种主要的依赖类型
-
模块依赖项:指向来自外部仓库的库。
-
项目依赖项:指向同一多项目构建中的其他项目。
-
文件依赖项:指向本地文件或目录,例如
.jar
或.aar
文件。
1. 模块依赖项
模块依赖项是最常见的依赖项。它们指向通过模块坐标(组、名称和版本)标识的依赖项。
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
}
}
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 构建中引用其他项目。

这对于将大型项目组织成更小、模块化的组件很有用。
dependencies {
implementation(project(":utils"))
implementation(project(":api"))
}
dependencies {
implementation project(':utils')
implementation project(':api')
}
Gradle 使用 project()
函数来定义项目依赖项。此函数接受构建内目标项目的相对路径。路径通常使用冒号 (:
) 来分隔项目结构的不同级别。
项目依赖项会自动解析,以便被依赖的项目总是在依赖它的项目之前构建。
类型安全的项目依赖项
类型安全的项目访问器是一个孵化中的功能,必须显式启用。其实现随时可能更改。
要添加对类型安全的项目访问器的支持,请将 enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
添加到您的 settings.gradle(.kts)
文件中。
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
enableFeaturePreview 'TYPESAFE_PROJECT_ACCESSORS'
使用 project(":some:path")
记法的一个缺点是需要记住依赖项的项目路径。此外,更改项目路径需要手动更新所有出现的地方,这增加了遗漏的风险。
取而代之的是,实验性的类型安全的项目访问器 API 提供了 IDE 补全功能,使依赖项声明变得更容易。
dependencies {
implementation(projects.utils)
implementation(projects.api)
}
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 仓库。 |

文件依赖项是独特的,因为它们表示对文件系统上文件的直接引用,而不包含任何相关的元数据,例如传递依赖项、来源或作者信息。
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") })
}
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()
:定义一个目录并包含或排除特定的文件模式。
|
或者,您可以使用平面目录仓库来指定多个文件依赖项的源目录。
理想情况下,您应该使用带本地 URL 的 Maven 或 Ivy 仓库。
repositories {
maven {
url = 'file:///path/to/local/files' // Replace with your actual path
}
}
要将文件添加为依赖项,请将文件集合传递给配置。
dependencies {
runtimeOnly(files("libs/a.jar", "libs/b.jar"))
runtimeOnly(fileTree("libs") { include("*.jar") })
}
dependencies {
runtimeOnly files('libs/a.jar', 'libs/b.jar')
runtimeOnly fileTree('libs') { include '*.jar' }
}
请注意,文件依赖项不包含在您项目的已发布依赖描述符中。但是,它们在同一构建中的传递依赖项中可用,这意味着它们可以在当前构建中使用,但不能在构建外部使用。
您应该指定哪些任务为文件依赖项生成文件。否则,当您从另一个项目传递依赖这些文件时,必要的任务可能不会运行。
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 }}")
}
}
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 任务或插件时很有用。
dependencies {
implementation(gradleApi())
}
dependencies {
implementation gradleApi()
}
Gradle TestKit 依赖项
您可以使用 DependencyHandler.gradleTestKit() 方法声明对当前版本 Gradle TestKit API 的依赖。这对于编写和执行 Gradle 插件和构建脚本的功能测试很有用。
dependencies {
testImplementation(gradleTestKit())
}
dependencies {
testImplementation gradleTestKit()
}
本地 Groovy 依赖项
您可以使用 DependencyHandler.localGroovy() 方法声明对 Gradle 发行版附带的 Groovy 的依赖。这在您使用 Groovy 开发自定义 Gradle 任务或插件时很有用。
dependencies {
implementation(localGroovy())
}
dependencies {
implementation localGroovy()
}
记录依赖项
plugins {
`java-library`
}
repositories {
mavenCentral()
}
dependencies {
implementation("org.ow2.asm:asm:7.1") {
because("we require a JDK 9 compatible bytecode generator")
}
}
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.