1. 项目初始化与依赖配置

1.1 原理概述

Room 是 Android 官方提供的持久化库，底层基于 SQLite，但通过编译时注解处理（KSP）自动生成 DAO 实现与数据库版本管理代码。WorkManager 是 Android 后台任务调度库，能够保证任务在满足约束条件时可靠执行，即使应用退出或设备重启也不会丢失。将 Room 与 WorkManager 结合，可以实现“后台任务 + 本地持久化”的完整数据链路。

KSP（Kotlin Symbol Processing）是 Kotlin 编译期注解处理的新一代方案，相比传统的 kapt，KSP 跳过 Java 桩代码生成阶段，直接操作 Kotlin 符号，编译速度提升约 2 倍。Room 从 2.6.0 版本开始正式将 KSP 作为首选编译器。三个组件的依赖关系如下：

1.2 实现流程

项目初始化阶段需要依次完成以下 4 个步骤：

1. 配置仓库与插件 — 在 settings.gradle.kts 中确保 google() 和 mavenCentral() 仓库已启用，并在项目级 build.gradle.kts 中声明 KSP 插件。
2. 声明模块级依赖 — 在模块级 build.gradle.kts 中添加 Room、WorkManager 以及 KSP 编译器的依赖坐标。
3. 启用 KSP 编译器 — 通过 ksp() 函数指定 Room 编译器模块，同时配置 Room 的 schema 导出目录（可选但推荐）。
4. 同步并校验 — 执行 Gradle Sync，检查控制台输出与依赖树，确认无版本冲突或缺失。

1.3 代码配置

以下是以 Kotlin DSL 编写的完整依赖配置片段：

项目级 build.gradle.kts — 声明 KSP 插件：

plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

模块级 build.gradle.kts — 应用插件并添加依赖：

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.roomworkdemo"
    compileSdk = 34
    defaultConfig {
        applicationId = "com.example.roomworkdemo"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }
    // 启用 Java 8+ 以支持 Room 与 WorkManager
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // ─── Room ───
    val roomVersion = "2.6.1"
    implementation("androidx.room:room-runtime:$roomVersion")
    implementation("androidx.room:room-ktx:$roomVersion")
    ksp("androidx.room:room-compiler:$roomVersion")

    // ─── WorkManager ───
    val workVersion = "2.9.0"
    implementation("androidx.work:work-runtime-ktx:$workVersion")
    // 多进程场景需额外添加（可选）
    // implementation("androidx.work:work-multiprocess:$workVersion")

    // ─── Android 核心库 ───
    implementation("androidx.core:core-ktx:1.12.0")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
    implementation("androidx.activity:activity-compose:1.8.2")
}

1.4 版本兼容参考

下表列出当前主流稳定版本之间的对应关系，实际开发时应以官方发行说明为准：

1.5 验证配置

同步完成后，在 Android Studio 的 Terminal 中运行以下命令检查依赖树：

./gradlew :app:dependencies --configuration implementation

在输出中应能看到 androidx.room:room-runtime:2.6.1、androidx.work:work-runtime-ktx:2.9.0 以及 com.google.devtools.ksp 相关任务。如果出现版本冲突，Gradle 会在控制台以 CONFLICT 或 Dependency resolve 形式告警。

1.6 常见错误与避坑

• KSP 版本不匹配：编译时报 ksp: symbol processing failed — 检查 Kotlin 版本与 KSP 版本前缀是否一致。
• Room 编译器未通过 KSP 引入：如果在 dependencies 中误用了 kapt 而非 ksp，Room 将不会生成 DAO 实现，运行时报 Database is not initialized。
• WorkManager 与 Lifecycle 版本冲突：WorkManager 2.9.x 依赖 Lifecycle 2.6+，若项目中混用低版本 Lifecycle，需统一通过 BOM 管理。
• JDK 版本过低：Room 2.6+ 与 AGP 8.x 要求 JDK 17，若使用 JDK 11 会出现 Unsupported class file major version。