📚 2. 开发环境搭建

Room · KSP · KAPT · Gradle

添加Room依赖、配置KSP/KAPT、Gradle同步与版本兼容性

🧩 搭建Room开发环境是进入持久化殿堂的第一步。我们将使用 KSP (Kotlin Symbol Processing) 作为默认注解处理器（KAPT作为备选），并确保与Gradle、AGP、Kotlin版本完美兼容。下面按步骤拆解，配合表格与架构图，一目了然。

📌 1. 添加 Room 依赖

在 build.gradle.kts (Module :app) 中声明 Room 相关库。使用 BOM 统一管理版本，避免冲突。

// 版本号：请参考官方兼容性表，此处以 Room 2.6.1 为例
val roomVersion = "2.6.1"

dependencies {
    // Room 运行时
    implementation("androidx.room:room-runtime:$roomVersion")
    // Room Kotlin 扩展 + 协程支持
    implementation("androidx.room:room-ktx:$roomVersion")
    // Room 编译器 (KSP 或 KAPT 二选一)
    ksp("androidx.room:room-compiler:$roomVersion")
    // 如果使用 KAPT 则替换为 kapt("androidx.room:room-compiler:$roomVersion")
    
    // 可选: Room 测试辅助
    testImplementation("androidx.room:room-testing:$roomVersion")
}

✅ Room 2.5.0+ ✅ Kotlin 1.8+ ✅ KSP 1.9+ ✅ AGP 8.0+

⚙️ 2. 配置 KSP / KAPT

🔥 推荐 KSP 性能更优，支持增量编译。KAPT 为备用方案。在项目级 build.gradle.kts 添加插件。

🔧 项目级 build.gradle.kts

plugins {
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
    // 若使用 KAPT 则添加：
    // id("org.jetbrains.kotlin.kapt") version "1.9.22" apply false
}

📱 Module 级 build.gradle.kts

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

android {
    // ... 常规配置
}

dependencies {
    // Room 依赖如上
    ksp("androidx.room:room-compiler:$roomVersion")
    // 若使用 KAPT 则改为 kapt(...)
}

💡 提示： KSP 与 KAPT 不要同时启用。如果从 KAPT 迁移至 KSP，请移除 kapt 插件及所有 kapt 依赖，替换为 ksp。

🔄 3. Gradle 同步 & 版本兼容性

点击 Android Studio 中的 "Sync Now"，或执行 ./gradlew build。若出现版本冲突，请参考下表：

Room 版本	最低 Kotlin 版本	推荐 KSP 版本	AGP 最低版本	备注
2.6.x	1.8.0	1.9.22-1.0.17+	8.0	✅ 稳定版
2.5.x	1.7.0	1.8.0-1.0.11+	7.4	兼容性良好
2.4.x	1.6.0	KAPT 为主	7.2	旧项目可选
2.3.x	1.5.0	KAPT	7.0	已停止维护

📌 版本兼容黄金法则： Room 版本与 Kotlin 版本、KSP 版本、AGP 版本需保持大版本匹配。推荐使用 Room 版本兼容性页面检查。

🧩 Room 开发环境架构图

✅ 4. 搭建检查清单

🔹 确认 build.gradle.kts 中已应用 KSP 或 KAPT 插件。
🔹 Room 版本与 Kotlin 版本满足兼容性表格。
🔹 执行 Gradle 同步无红色报错。
🔹 编写一个简单的 @Entity 并编译，观察是否生成 AppDatabase_Impl 类。
🔹 若使用 KSP，检查 build/generated/ksp 目录下存在代码。

📖 小贴士： 使用 KSP 时，请在 gradle.properties 中添加 ksp.incremental=true 以启用增量编译，加快构建速度。

✏️ 基于 Room 2.6+ / Kotlin 2.0+ / KSP 1.9+ 编写