📚 课程目录第4章状态管理

4. 环境搭建：Android Studio版本、Gradle配置、Compose BOM版本、测试依赖声明

环境搭建是技术实现型课程的基石。针对“后台任务触发 Compose 界面刷新”的测试场景，开发环境的版本组合直接影响编译效率、运行时稳定性以及测试框架的兼容性。本章将详细说明推荐的工具版本、Gradle 核心配置参数、Compose BOM（Bill of Materials）的引入方式，以及关键测试依赖的声明规则。

4.1 Android Studio 与 JDK 版本建议

为确保 Compose 编译器与 AGP（Android Gradle Plugin）之间的兼容性，建议使用较新的稳定版本。以下是当前章节推荐的版本基线：

工具	推荐版本	备注
Android Studio	Hedgehog (2023.1.1) 或更高	内置 K2 编译器支持，提升 Compose 编译速度
JDK	17	AGP 8.x 及以上版本的强制要求
Kotlin	1.9.22	与 Compose Compiler 1.5.10 匹配
AGP	8.2.2	稳定且与 Compose BOM 2024.01.00 兼容

版本匹配原则：Compose Compiler 与 Kotlin 版本严格绑定。查阅官方兼容表（非网络图片，此处为示意）以确保版本组合无误。错误的版本组合会导致编译时“Backend Internal Error”或“Compose kotlin compiler plugin”异常。

4.2 Gradle 配置文件详解

项目级 build.gradle.kts（或 build.gradle）决定了依赖仓库、插件版本以及编译目标。以下是针对本课程优化后的关键配置片段。

4.2.1 项目级 build.gradle.kts

// project/build.gradle.kts
plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}

// 统一插件管理，避免子模块版本冲突
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        // 如需自定义 Compose Compiler 版本，可通过 classpath 声明
        // classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22")
    }
}

4.2.2 模块级 build.gradle.kts

在 app 模块的构建脚本中，通过 composeOptions 指定 Compose Compiler 版本，并启用非传递的 R 类引用以优化编译性能。

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        applicationId = "com.example.backgroundrefresh"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // 引入 Compose BOM，统一管理所有 Compose 依赖版本
    val composeBom = platform("androidx.compose:compose-bom:2024.01.00")
    implementation(composeBom)
    androidTestImplementation(composeBom)

    // Compose UI 核心库
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.ui:ui-graphics")
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")

    // Material3 设计组件
    implementation("androidx.compose.material3:material3")

    // Activity Compose 集成
    implementation("androidx.activity:activity-compose:1.8.2")

    // 生命周期 & LiveData/Flow 集成
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.7.0")
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.7.0")

    // 协程（用于后台任务调度）
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")

    // --- 测试依赖声明 ---
    testImplementation("junit:junit:4.13.2")
    // Compose UI 测试框架
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
    // 调试工具
    debugImplementation("androidx.compose.ui:ui-test-manifest")
    // 针对协程的测试支持
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3")
}

BOM 版本锁定风险：当使用 BOM 时，所有 Compose 库版本将严格遵从 BOM 中定义的版本。若项目中引用了 BOM 未覆盖的 Compose 库（如 compose-compiler），必须手动在 composeOptions 中指定，且版本必须与 BOM 隐式依赖的 Kotlin-Compiler-Extension 版本兼容。

4.3 Compose BOM 版本策略

BOM 是管理 Compose 系列库版本的推荐方式。使用 platform() 导入 BOM 后，后续的 Compose 依赖可以省略版本号。本课程采用 2024.01.00 版本，它锁定了以下核心库版本：

androidx.compose.ui:ui → 1.6.0
androidx.compose.material3:material3 → 1.2.0
androidx.compose.ui:ui-test-junit4 → 1.6.0

此组合能够提供稳定的 SnapshotState 和 Recomposer 行为，适合用于后台任务状态变更的测试。

4.4 测试依赖声明与作用域

为了对后台触发的 Compose 界面进行自动化验证，需要在依赖声明中区分单元测试与插桩测试的作用域：

依赖库	作用域	测试类型
`ui-test-junit4`	`androidTestImplementation`	插桩测试（需模拟器或设备）
`ui-test-manifest`	`debugImplementation`	提供测试专用 Activity 清单
`kotlinx-coroutines-test`	`testImplementation`	纯 JVM 单元测试
`junit`	`testImplementation`	基础断言
`lifecycle-runtime-testing`	`testImplementation`	模拟 ViewModel 生命周期

// 针对 ViewModel + Coroutine 的测试用例，添加生命周期测试支持
testImplementation("androidx.lifecycle:lifecycle-runtime-testing:2.7.0")

4.5 SVG 架构图：Gradle 依赖解析与测试运行生命周期

下图展示了从 Gradle 配置文件解析到测试执行期间，Compose BOM、编译选项与测试框架之间的协作关系。重点是后台任务（Coroutine/WorkManager）如何通过 SnapshotState 更新 UI，并被 ui-test-junit4 框架捕获验证。

4.6 常见环境配置错误

Kotlin 版本与 Compose Compiler 不匹配：编译时出现 This version of the Compose Compiler requires Kotlin version X.Y.Z。必须同步修改 composeOptions.kotlinCompilerExtensionVersion 与项目 Kotlin 版本。
BOM 版本未使用 platform() 包裹：直接声明 implementation("androidx.compose:compose-bom:2024.01.00") 会失效，需通过 platform("...") 声明。
测试依赖作用域混淆：将 ui-test-junit4 放到 implementation 而非 androidTestImplementation 会导致测试类无法运行。

验证配置是否正确的快速方法：在项目根目录执行 ./gradlew :app:dependencies --configuration debugRuntimeClasspath，查看 Compose 库版本是否与 BOM 声明一致。同时检查 ui-test-manifest 是否仅存在于 debug 配置中。

4.7 流程自查清单

确认 Android Studio 已升级至 Hedgehog 或更高版本。
配置 JDK 17 并更新 gradle-wrapper.properties 中的 Gradle 版本至 8.4+。
在项目级 build.gradle.kts 中正确引入 kotlin 和 android 插件。
在模块级 build.gradle.kts 中启用 compose = true，并匹配 Compose Compiler 版本。
通过 platform() 引入 Compose BOM，并省略其他 Compose 依赖的版本号。
将 ui-test-junit4 和 ui-test-manifest 添加到对应的测试作用域。
运行 ./gradlew assembleDebug 确认编译无错误，然后执行 ./gradlew connectedAndroidTest 验证测试框架初始化。