Gradle 8 使用教程：Maven 仓库导入、依赖管理与 TOML 配置详解

Gradle 是 Java 和 Android 项目中广泛使用的构建工具，以灵活和高效著称。然而，随着 Gradle 版本的迭代，它的配置方式也发生了变化。例如，Gradle 8 开始对一些老旧的配置方式进行优化，推荐新的 DSL 和工具，使构建脚本更具一致性和可维护性。

本文将带你深入了解：

1. Gradle 8 中如何导入其他 Maven 仓库。
2. 如何正确引入依赖。
3. TOML 文件在依赖管理中的作用及使用方法。
4. Gradle 新版工具链的优势和实战示例。

一、Gradle 8 中导入其他 Maven 仓库

Gradle 8 推荐使用 dependencyResolutionManagement 来集中管理项目的依赖仓库，而不是传统的 allprojects 配置。这种方式更加现代化，也更符合模块化开发的需求。

1.1 传统方式 (allprojects) 的问题

过去，仓库管理通常在 allprojects 中完成：

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://artifact.bytedance.com/repository/Volcengine/"
        }
    }
}

问题：

• 全局定义仓库可能导致重复配置，不够灵活。
• Gradle 官方对 allprojects 的支持逐渐减少，未来可能会完全废弃。

1.2 推荐的方式：dependencyResolutionManagement

在 settings.gradle.kts 或 settings.gradle 文件中，通过 dependencyResolutionManagement 集中管理仓库：

Kotlin DSL 示例：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://artifact.bytedance.com/repository/Volcengine/")
        }
    }
}

Groovy DSL 示例：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://artifact.bytedance.com/repository/Volcengine/'
        }
    }
}

配置解释：

1. repositoriesMode 设置：

   • FAIL_ON_PROJECT_REPOS：禁止模块级 build.gradle 自行定义仓库，强制集中管理。
   • PREFER_PROJECT：优先模块定义的仓库。

2. 仓库定义：

   • google() 和 mavenCentral() 是默认仓库。
   • 自定义仓库通过 maven 配置，推荐使用 uri() 方法来设置地址。

二、依赖的引入与管理

Gradle 8 提供了更加现代化的依赖管理工具，让开发者可以轻松地管理版本、模块和依赖关系。

2.1 在 build.gradle.kts 中添加依赖

使用 Kotlin DSL 时，添加依赖的方式如下：

dependencies {
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4")
    testImplementation("junit:junit:4.13.2")
}

2.2 配置依赖版本号

依赖的版本号可以直接写在代码中，但更好的方式是集中管理依赖版本号。Gradle 8 强烈推荐使用 TOML 文件。

三、TOML 文件简介与依赖版本管理

3.1 什么是 TOML？

TOML (Tom’s Obvious, Minimal Language) 是一种简单的配置文件格式，类似于 JSON 或 YAML，但更容易书写和阅读。Gradle 8 开始支持用 TOML 来集中管理依赖版本。

3.2 为什么使用 TOML？

• 集中管理版本：减少重复定义版本号。
• 易读性：文件结构清晰，一目了然。
• 模块化：支持按功能组织依赖。

3.3 配置 TOML 文件管理依赖

1. 在项目的 gradle 文件夹中创建 libs.versions.toml 文件：

   ├── gradle
   │   ├── libs.versions.toml
   ├── settings.gradle.kts
   ├── build.gradle.kts
   

2. 在 libs.versions.toml 文件中定义依赖：

   [versions]
   kotlin = "1.8.10"
   coroutines = "1.6.4"
   retrofit = "2.9.0"
   junit = "4.13.2"
   
   [libraries]
   kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
   coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" }
   retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
   junit = { module = "junit:junit", version.ref = "junit" }
   

3. 在项目中启用版本管理：
   在 settings.gradle.kts 文件中添加以下代码：

   dependencyResolutionManagement {
       versionCatalogs {
           create("libs") {
               from(files("gradle/libs.versions.toml"))
           }
       }
   }
   

4. 在 build.gradle.kts 文件中引用依赖：

   dependencies {
       implementation(libs.kotlinStdlib)
       implementation(libs.coroutinesAndroid)
       implementation(libs.retrofit)
       testImplementation(libs.junit)
   }
   

3.4 TOML 配置解析

• [versions]：定义依赖的版本号。
• [libraries]：定义依赖的模块和版本绑定。
• version.ref：引用 [versions] 中定义的版本号。

四、Gradle 新版工具链的优势

1. 高效依赖解析：集中管理仓库和依赖，避免模块间配置冲突。
2. 可维护性：通过 TOML 配置文件实现版本号集中管理，减少重复定义。
3. 灵活扩展：支持自定义版本目录和模块化配置。

五、Gradle 8 实战示例

以下是一个使用 TOML 配置和 Maven 仓库的完整示例：

5.1 settings.gradle.kts

pluginManagement {
    repositories {
        google()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://artifact.bytedance.com/repository/Volcengine/")
        }
    }
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

rootProject.name = "MyProject"
include(":app")

5.2 gradle/libs.versions.toml

[versions]
kotlin = "1.8.10"
coroutines = "1.6.4"
retrofit = "2.9.0"
junit = "4.13.2"

[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" }
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
junit = { module = "junit:junit", version.ref = "junit" }

5.3 build.gradle.kts

plugins {
    kotlin("android")
}

android {
    compileSdk = 34
    defaultConfig {
        applicationId = "com.example.myproject"
        minSdk = 21
        targetSdk = 34
    }
}

dependencies {
    implementation(libs.kotlinStdlib)
    implementation(libs.coroutinesAndroid)
    implementation(libs.retrofit)
    testImplementation(libs.junit)
}

六、总结

Gradle 8 的新特性让依赖管理更加集中化和模块化，特别是引入 TOML 文件后，依赖管理变得更高效。虽然新版本的配置方式可能需要一些学习成本，但它带来的灵活性和可维护性将使你的项目受益良多。

最后吐槽一下，Gradle是真tm难用