Android Room

Room 是 Android Jetpack 的一部分,用于在应用内把结构化数据持久化到本地数据库。官方文档指出,最常见的用途是缓存关键数据,让设备在没有网络时,用户仍能浏览这些内容。官方建议优先使用 Room,而不是直接调用 SQLite API。

三个核心组件

• 数据库类(Database):用 @Database 注解标注的抽象类,继承 RoomDatabase。它持有数据库,是访问底层持久化数据连接的主入口,需要在注解中列出所有关联的实体。
• 数据实体(Entity):每个实体类对应数据库中的一张表,实例对应表中的一行,用 @Entity、@PrimaryKey、@ColumnInfo 等注解定义。
• 数据访问对象(DAO):用 @Dao 标注的接口,通过 @Query、@Insert、@Delete 等函数完成查询、插入、更新和删除。

数据库类为每个 DAO 提供一个无参的抽象函数。应用通过 DAO 读取实体对象,也可以用实体创建新行或更新已有行。

主要优势

• 编译期校验 SQL 查询,把错误提前到构建阶段暴露。
• 用便捷注解减少重复且易错的样板代码。
• 简化数据库迁移流程。
• 官方文档提供对象关系(一对一、一对多、多对多、嵌套关系)、异步 DAO 查询、数据库视图、预填充数据库、迁移、测试与调试等专题指南。
• 官方文档提供从 SQLite 迁移到 Room 的指南,以及从 Room 2.x 迁移到 Room 3.0 的指南。
• 支持 Kotlin Multiplatform,可以与其他平台共享数据库层。

安装与使用

在模块的 build.gradle.kts 中添加依赖。官网当前文档展示的是 Room 3.0(示例版本 3.0.3),需要用 KSP 做注解处理:

dependencies {
    val room_version = "3.0.3"

    implementation("androidx.room3:room3-runtime:$room_version")
    ksp("androidx.room3:room3-compiler:$room_version")
}

之后定义实体、DAO 和数据库类,再用 Room.databaseBuilder 创建数据库实例。官网示例中的 DAO 函数使用 Kotlin 的 suspend 函数,并通过 setDriver(AndroidSQLiteDriver()) 指定驱动。

注意事项

• 单进程应用应以单例方式创建数据库实例,因为每个 RoomDatabase 实例开销较大,通常不需要多个实例。
• 多进程应用可以在构建数据库时调用 enableMultiInstanceInvalidation(),让一个进程中的失效通知自动传播到其他进程的实例。
• Room 面向设备上的数据持久化。如果需要跨设备同步、实时协作或带离线支持的云端后端,官方建议将 Room 与 WorkManager 和自建后端搭配,或使用 Cloud Firestore、Firebase SQL Connect 等托管云服务。

适用人群

适合需要在本地保存和查询结构化数据的 Android 开发者,也适合想用 Kotlin Multiplatform 共享数据库层的团队。