📚 课程目录第1章 Room数据库概述与核心组件

1. Room 数据库概述与核心组件

1.1 什么是 Room？

Room 是 Android 官方提供的持久化库，属于 Jetpack 组件之一。它在 SQLite 之上构建了一层抽象，让开发者以声明式接口操作数据库，而无需手写 SQLiteOpenHelper、游标适配或内容提供器。Room 的核心目标：编译时验证 SQL、减少样板代码、与 LiveData / Flow / RxJava 原生协作。

关键认知：Room 不是新的数据库引擎，而是 SQLite 的 ORM 封装。所有数据最终都存储在 SQLite 文件中，但开发者通过注解和 DAO 接口操作，而非直接操作 Cursor 或 SQLiteDatabase。

1.2 核心组件三件套

Room 由三个核心构件组成，缺一不可：

组件	角色	表现形式	关键注解
Entity（实体）	数据模型 / 表结构	Kotlin data class 或 Java POJO	@Entity, @PrimaryKey, @ColumnInfo
DAO（数据访问对象）	SQL 操作接口	interface 或 abstract class	@Dao, @Query, @Insert, @Update, @Delete
Database（数据库类）	数据库持有者 / 入口	继承 RoomDatabase 的抽象类	@Database

典型关系：1 个 Database 类 → 管理多个 Entity → 暴露多个 DAO。DAO 是业务代码唯一的数据操作入口，Database 负责创建/升级数据库。

1.3 实体（Entity）定义示例

@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val uid: Long = 0,

    @ColumnInfo(name = "full_name")
    val fullName: String,

    @ColumnInfo(name = "created_at")
    val createdAt: Long = System.currentTimeMillis()
)

每个 @Entity 注解的类对应一张表；字段默认映射为同名列，可通过 @ColumnInfo 自定义列名。@PrimaryKey 支持自动生成或复合主键。

1.4 DAO（数据访问对象）定义示例

@Dao
interface UserDao {
    @Query("SELECT * FROM users ORDER BY created_at DESC")
    fun getAllUsers(): List<User>

    @Query("SELECT * FROM users WHERE uid = :userId")
    fun getUserById(userId: Long): User?

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertUser(user: User): Long

    @Update
    suspend fun updateUser(user: User)

    @Delete
    suspend fun deleteUser(user: User)
}

DAO 中所有 SQL 都在编译期被 Room 验证。挂起函数（suspend）配合协程在后台线程执行；返回值支持 LiveData、Flow、RxJava 等响应式类型。

1.5 Database 类定义示例

@Database(
    entities = [User::class],
    version = 1,
    exportSchema = true
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao

    companion object {
        @Volatile
        private var INSTANCE: AppDatabase? = null

        fun getInstance(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,
                    AppDatabase::class.java,
                    "app_room.db"
                ).build()
                INSTANCE = instance
                instance
            }
        }
    }
}

@Database 注解声明实体列表、版本号和是否导出 Schema。推荐单例模式创建实例，避免重复打开连接。使用 applicationContext 防止内存泄漏。

1.6 SQLite 抽象层与编译时验证

Room 在 SQLite 之上维护了三层抽象：

应用层：开发者只接触 Entity / DAO / Database 注解接口。
编译层：kapt 或 KSP 注解处理器生成 UserDao_Impl 和 AppDatabase_Impl 实现类，内含所有 SQLiteDatabase 调用。
运行时层：生成的代码通过 SupportSQLiteOpenHelper 执行真实 SQL，与 SQLite 原生 API 一致。

  编译时验证机制：

  1. 检查 SQL 语法，表名/列名是否与 Entity 匹配。

  2. 检查返回值类型与查询结果是否兼容。

  3. 检查 DAO 方法是否在正确线程被调用（默认不允许在主线程操作）。

  4. 检查迁移（Migration）版本是否连续。

  这些检查在 gradle build 时完成，不会等到运行时崩溃。

1.7 与 SQLiteOpenHelper 对比

对比维度	SQLiteOpenHelper	Room
SQL 编写	手写 SQL 字符串，易出错	DAO 接口 + 注解，编译期验证 SQL
样板代码	大量 Cursor、ContentValues、close()	自动映射 POJO，无需手动解析游标
类型安全	运行时类型转换异常	编译期泛型校验
响应式支持	需手动观察数据库变化	原生 LiveData / Flow / RxJava
数据库迁移	手写 onUpgrade，版本逻辑混乱	Migration 对象，自动检查版本链
测试	依赖 Android 环境	支持内存数据库单元测试
学习曲线	低（直接 SQL）	中（注解 + DAO 模式）

注意：Room 不适合已有庞大原生 SQLite 代码的遗留项目迁移，也不适用于需要精细控制 WAL 模式、加密或 FTS 虚拟表的场景。对于这些需求，可直接使用 SQLiteOpenHelper 或 SQLCipher。

1.8 典型错误与调试

错误：Schema export 目录未配置 — 在 build.gradle 中设置 room.schemaLocation，或在 @Database 中关闭 exportSchema = false。
错误：在主线程操作数据库 — 调用 allowMainThreadQueries()（仅测试环境），或使用协程 / LiveData 异步。
错误：Entity 缺少空构造器或无参构造 — Room 需要反射创建实例，Kotlin data class 默认包含全参构造器，通常无需额外处理。
错误：数据库版本号跳跃 — 必须为每个版本提供 Migration，或使用 fallbackToDestructiveMigration()。

1.9 性能与稳定性优化建议

使用 @Transaction 包装批量操作：避免多次事务提交开销。
避免在 DAO 中返回 LiveData 且不做生命周期感知：应当配合 ViewModel 使用，防止 Activity 销毁后仍持有观察者。
合理使用索引：在 @Entity 的 indices 参数中声明高频查询列。
数据库打开超时：使用 setQueryTimeout() 或 openHelperFactory 自定义连接池。
Schema 版本演进：始终保留历史 Schema JSON 文件，便于调试迁移冲突。

1.10 Room 架构全景图

上图展示了 Room 从应用层到编译层再到运行时层的完整数据流。三个核心组件（Entity、DAO、Database）由开发者声明，编译期处理器生成实现类，最终在运行时通过 SQLite 引擎执行持久化操作。