完整教程：Room 概要
jetpack Room 是 Google 官方推出的 Android 持久化存储解决方案，是对 SQLite 的封装与增强，旨在简化数据库操作、提升开发效率，并完美契合 Jetpack 组件生态。以下是从核心概念、组件解析、使用流程、高级特性到最佳实践的完整拆解：
一、Room 的核心定位与优势Room 的设计目标是“让 SQLite 更好用”，解决原生 SQLite 的痛点：
编译时检查：通过注解处理器在编译期验证 SQL 语句的正确性，避免运行时崩溃（如表名错误、列不存在）。
简化异步操作：原生支持协程（suspend函数）、LiveData、Flow，无需手动管理线程。
关系映射：通过注解轻松定义实体间的关系（一对一、一对多），避免手动编写 JOIN 逻辑。
类型安全：通过 TypeConverter 将复杂类型（如枚举、日期）与数据库字段映射，避免手动转换。
Jetpack 集成：与 ViewModel、LiveData、Navigation 等组件无缝协作，符合 Android 架构组件的设计规范。
二、Room 的三大核心组件Room 的架构基于三个核心注解类，共同定义数据库的结构与操作：
1. Entity（实体类）：定义数据库表Entity 是数据库表的 Kotlin 对象映射，通过 @Entity注解标记，每个属性对应表的一列。
关键注解：
@Entity(tableName = "users")：指定表名（默认类名）。
@PrimaryKey：定义主键（支持自增、复合主键）。
@ColumnInfo(name = "age", typeAffinity = ColumnInfo.INTEGER)：自定义列名、类型（默认与属性类型一致）。
@Ignore：忽略不需要持久化的属性（如计算属性）。
示例：用户表实体
@Entity(
tableName = "users",
indices = [Index(value = ["email"], unique = true)] // 唯一索引：邮箱不重复
)
data class User(
@PrimaryKey(autoGenerate = true) val id: Long = 0,
val name: String,
val email: String,
val age: Int,
@Ignore val fullName: String get() = "$name ($age)" // 忽略，不存数据库
)
2. DAO（数据访问对象）：定义数据库操作DAO 是数据库操作的接口，通过 @Dao注解标记，包含增删改查（CRUD）的方法。Room 会自动生成 DAO 的实现类。
关键注解：
@Insert(onConflict = OnConflictStrategy.REPLACE)：插入数据（冲突策略：替换旧数据）。
@Delete：删除数据。
@Update：更新数据。
@Query("SELECT * FROM users WHERE age > :minAge")：自定义 SQL 查询（支持参数绑定）。
@Query("DELETE FROM users")：自定义删除语句。
示例：用户 DAO
您可以将每个 DAO 定义为一个接口或一个抽象类。对于基本用例，您通常应使用接口。无论是哪种情况，您都必须始终使用 @Dao 为您的 DAO 添加注解。DAO 不具有属性，但它们定义了一个或多个方法，可用于与应用数据库中的数据进行交互。
* 1. OnConflictStrategy.REPLACE：冲突策略是覆盖旧数据同时继续事务。
* 2. OnConflictStrategy.ROLLBACK：冲突策略是回滚事务。
* 3. OnConflictStrategy.ABORT：冲突策略是终止事务。===========默认
* 4. OnConflictStrategy.FAIL：冲突策略是事务失败。
* 5. OnConflictStrategy.IGNORE：冲突策略是忽略冲突。
*/
@Dao
interface UserDao {
// 插入/替换用户
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun insertUser(user: User)
// 删除用户
@Delete
suspend fun deleteUser(user: User)
// 查询所有用户（返回 Flow，支持响应式更新）
@Query("SELECT * FROM users ORDER BY name ASC")
fun getAllUsers(): Flow>
// 查询年龄大于 minAge 的用户（参数绑定）
@Query("SELECT * FROM users WHERE age > :minAge")
suspend fun getUsersOlderThan(minAge: Int): List
// 自定义更新：修改用户邮箱
@Query("UPDATE users SET email = :newEmail WHERE id = :userId")
suspend fun updateUserEmail(userId: Long, newPassword: String)
}
3. Database（数据库类）：管理实体与 DAODatabase 是数据库的入口类，通过 @Database注解标记，继承 RoomDatabase，定义数据库的版本、实体列表和 DAO。
关键注解：
@Database(entities = [User::class], version = 1)：指定包含的实体和数据库版本。
abstract fun userDao(): UserDao：抽象方法，返回 DAO 实例（Room 自动生成实现）。
示例：用户数据库
@Database(
entities = [User::class],
version = 1,
exportSchema = true // 导出数据库 schema（用于迁移）
)
abstract class AppDatabase : RoomDatabase() {
abstract fun userDao(): UserDao // 获取 UserDao 实例
// 单例模式：避免多个数据库实例
companion object {
private var INSTANCE: AppDatabase? = null
fun getInstance(context: Context): AppDatabase {
return INSTANCE ?: synchronized(this) {
val instance = Room.databaseBuilder(
context.applicationContext,
AppDatabase::class.java,
"app_database" // 数据库文件名
).build()
INSTANCE = instance
instance
}
}
}
}
三、Room 的基础使用流程以 插入用户 → 查询所有用户 → 更新用户年龄 为例，演示 Room 的使用：
1. 添加依赖在 build.gradle.kts（Module 级）中添加 Room 依赖：
dependencies {
implementation("androidx.room:room-runtime:2.6.1")
kapt("androidx.room:room-compiler:2.6.1") // 注解处理器（Kotlin 用 kapt）
implementation("androidx.room:room-ktx:2.6.1") // 协程、Flow 支持
}
2. 初始化数据库在 Application 或 Activity 中初始化 AppDatabase：
// Application 中初始化
class MyApp : Application() {
val database by lazy { AppDatabase.getInstance(this) }
}
3. 执行 CRUD 操作通过 DAO 执行数据库操作（结合协程/Flow）：
// 插入用户（协程）
lifecycleScope.launch {
val user = User(name = "Alice", email = "alice@example.com", age = 25)
getAppDatabase().userDao().insertUser(user)
}
// 查询所有用户（响应式：数据变化时自动更新 UI）
lifecycleScope.launch {
getAppDatabase().userDao().getAllUsers()
.collect { users ->
// 更新 RecyclerView 或 TextView
userAdapter.submitList(users)
}
}
// 更新用户年龄（协程）
lifecycleScope.launch {
val user = getAppDatabase().userDao().getUserById(1) // 假设扩展方法
user?.let {
getAppDatabase().userDao().updateUser(it.copy(age = 26))
}
}
四、Room 的高级特性1. 实体关系映射Room 支持一对一、一对多、多对多关系，通过注解简化关联查询：
一对多（用户 → 订单）：
@Entity(tableName = "orders")
data class Order(
@PrimaryKey(autoGenerate = true) val id: Long = 0,
val userId: Long, // 关联 User 的 id
val productName: String,
val price: Double
)
// 在 User 中定义一对多关系（返回订单列表）
@Entity(tableName = "users")
data class User(
...
@Relation(parentColumn = "id", entityColumn = "userId")
val orders: List = emptyList()
)
// DAO 查询：获取用户及其订单
@Transaction
@Query("SELECT * FROM users")
suspend fun getUsersWithOrders(): List
// 关联实体（非必须，可简化返回类型）
data class UserWithOrders(
@Embedded val user: User,
@Relation(parentColumn = "id", entityColumn = "userId")
val orders: List
) 2. TypeConverter：复杂类型映射将非基本类型（如枚举、日期、自定义对象）转换为数据库支持的类型（如 String、Int）：
示例：日期类型转换
// 定义 TypeConverter
class DateConverter {
@TypeConverter
fun fromTimestamp(value: Long?): Date? = value?.let { Date(it) }
@TypeConverter
fun dateToTimestamp(date: Date?): Long? = date?.time
}
// 在 Database 中注册 Converter
@Database(entities = [User::class], version = 1)
@TypeConverters(DateConverter::class)
abstract class AppDatabase : RoomDatabase() { ... }
// 实体中使用日期类型
@Entity(tableName = "users")
data class User(
...
val birthDate: Date?
) 3. 数据库迁移（Migration）/maɪˈɡreɪʃn/当数据库版本升级时，通过 Migration处理 schema 变化（如新增表、修改列）：
示例：从版本 1 到版本 2（新增 birthDate列）
val MIGRATION_1_2 = object : Migration(1, 2) {
override fun migrate(database: SupportSQLiteDatabase) {
// 执行 SQL 语句：新增 birthDate 列
database.execSQL("ALTER TABLE users ADD COLUMN birthDate INTEGER DEFAULT 0")
}
}
// 在 Database 中添加 Migration
@Database(entities = [User::class], version = 2)
abstract class AppDatabase : RoomDatabase() {
companion object {
fun getInstance(context: Context): AppDatabase {
return INSTANCE ?: synchronized(this) {
val instance = Room.databaseBuilder(
context.applicationContext,
AppDatabase::class.java,
"app_database"
)
.addMigrations(MIGRATION_1_2) // 添加迁移逻辑
.build()
INSTANCE = instance
instance
}
}
}
} 4. RxJava/Flow 支持Room 原生支持 RxJava（Completable、Single） 和 Kotlin Flow，轻松实现响应式编程：
Flow 示例：查询所有用户并实时更新
@Query("SELECT * FROM users")
fun getAllUsers(): Flow> // 返回 Flow
// 收集 Flow 更新 UI
lifecycleScope.launch {
userDao.getAllUsers().collect { users ->
adapter.submitList(users)
}
} 5. 查询优化索引：通过 @Index加速查询（如唯一索引、复合索引）。
预编译语句：Room 自动缓存 SQL 语句，避免重复编译。
异步查询：通过 suspend函数或 LiveData避免阻塞主线程。
合理使用分页查询 ：在实现列表展示时，可以采用分页查询的方式逐步加载数据。
优化SQL语句 ：避免在SQL语句中使用子查询，尽量使用 JOIN 来替代，因为子查询可能会导致多次扫描同样的数据。
大致性能
借用一张图
五、Room 的常见问题与避坑指南编译时错误：“Cannot find entity”
原因：Entity 类未被 Database 的 entities列表包含。
解决：检查 @Database(entities = [...])是否添加了所有 Entity。
迁移失败：“Database schema mismatch”
原因：Migration 逻辑未正确处理 schema 变化。
解决：使用 Room.databaseBuilder().createFromAsset("database/v2.db")预填充数据库，或检查 migrate方法的 SQL 语句。
TypeConverter 不生效
原因：未在 Database 中注册 @TypeConverters。
解决：在 @Database注解中添加 @TypeConverters(Converter::class)。
Flow 不发射数据
原因：未在协程中收集 Flow，或 DAO 方法未返回 Flow。
解决：确保 DAO 方法用 @Query返回 Flow，并在 lifecycleScope中收集。
六、总结：Room 的最佳实践使用 Kotlin 数据类：Entity 用 data class，简化代码。
协程 + Flow：所有数据库操作用 suspend函数或 Flow，避免主线程阻塞。
抽象 DAO 接口：DAO 用接口定义，Room 自动生成实现，降低耦合。
版本控制：数据库版本升级时，务必添加 Migration 逻辑，避免数据丢失。
测试：使用 Room.inMemoryDatabaseBuilder创建内存数据库，单元测试 DAO 方法。
一句话概括：Room 是 Kotlin Android 项目中持久化存储的首选方案，通过注解简化 SQLite 操作，结合 Jetpack 组件实现响应式编程，大幅提升开发效率与代码可维护性。
参考
Android 数据库之 Room（五）_room basedao-CSDN博客
深入理解Android SQLite数据库操作指南-CSDN博客
