3. 项目依赖配置：Gradle 声明与核心依赖解析

本章聚焦于为《Kotlin Flow缓存更新案例》搭建正确的Gradle依赖环境。依赖配置直接影响协程作用域、Flow背压策略、Room编译与Retrofit动态代理是否能在运行时正确协作。错误的版本组合或遗漏的编译器插件会导致难以追踪的构建失败或运行时崩溃。

3.1 依赖声明全景

本案例基于 Android Gradle Plugin (AGP) 8.x 与 Kotlin 1.9.x / 2.0.x 构建。所有依赖通过 libs.versions.toml 版本目录管理。

3.2 核心依赖分解

3.2.1 Kotlin 协程与 Flow

Flow 是 kotlinx-coroutines-core 的一部分，不需要额外 artifact。但 Android 项目必须引入 kotlinx-coroutines-android 以获得 Dispatchers.Main 的正确实现。

// libs.versions.toml 片段
[versions]
kotlin = "1.9.22"
coroutines = "1.8.0"

[libraries]
kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" }

3.2.2 Retrofit 与 OkHttp

Retrofit 默认使用 OkHttp 作为网络层。本案例需要 logging-interceptor 用于调试缓存决策。

[libraries]
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-converter-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }
okhttp-logging = { module = "com.squareup.okhttp3:logging-interceptor", version.ref = "okhttp" }

3.2.3 Room 与 KSP 编译器

Room 使用 KSP (Kotlin Symbol Processing) 替代 kapt 进行编译期 DAO 实现生成。KSP 版本必须严格匹配 Kotlin 版本。

[libraries]
room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" }
room-ktx = { module = "androidx.room:room-ktx", version.ref = "room" }
room-compiler = { module = "androidx.room:room-compiler", version.ref = "room" }

[plugins]
kotlin-ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

3.3 Gradle 构建脚本示例

以下为 app/build.gradle.kts 的完整依赖声明，包含本案例所需全部组件。

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.ksp)
}

android {
    namespace = "com.example.flowcacheupdate"
    compileSdk = 34

    defaultConfig {
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }

    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // Kotlin 标准库
    implementation(libs.kotlin.stdlib)

    // 协程 & Flow
    implementation(libs.kotlinx.coroutines.core)
    implementation(libs.kotlinx.coroutines.android)

    // Retrofit + OkHttp
    implementation(libs.retrofit)
    implementation(libs.retrofit.converter.gson)
    implementation(libs.okhttp.logging)

    // Room
    implementation(libs.room.runtime)
    implementation(libs.room.ktx)
    ksp(libs.room.compiler)

    // ViewModel KTX (用于 viewModelScope)
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0")

    // Jetpack Compose (可选，用于 UI 层收集 Flow)
    implementation(platform("androidx.compose:compose-bom:2024.01.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.compose.runtime:runtime")
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.7.0")
}

3.4 常见错误与修复

dependencies {
    constraints {
        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0") {
            because("统一协程版本避免运行时冲突")
        }
        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0")
    }
    // 其他依赖...
}

3.5 验证依赖配置

依赖声明完成后，通过以下方式验证配置正确性：

1. Gradle 同步：确保 IDE 的 Gradle 面板显示 BUILD SUCCESSFUL in xs。
2. KSP 任务可见性：在 Terminal 执行 ./gradlew :app:kspDebugKotlin，应无错误退出。
3. 依赖树检查：运行 ./gradlew :app:dependencies --configuration debugRuntimeClasspath，确认协程、Retrofit、Room 版本符合预期。
4. 最小化测试：在 Application 子类中创建一个空的 CoroutineScope(Dispatchers.IO).launch { }，编译运行不崩溃。