概述

本文大部分内容来至 jetpack官方room文档

处理大量结构化数据的应用可极大地受益于在本地保留这些数据。最常见的使用场景是缓存相关的数据，这样一来，当设备无法访问网络时，用户仍然可以在离线状态下浏览该内容。

Room 持久性库在 SQLite 上提供了一个抽象层，以便在充分利用 SQLite 的强大功能的同时，能够流畅地访问数据库。具体来说，Room 具有以下优势：

• 针对 SQL 查询的编译时验证。
• 可最大限度减少重复和容易出错的样板代码的方便注解。
• 简化了数据库迁移路径。

出于这些方面的考虑，强烈建议您使用 Room

导入、设置

dependencies {
    def room_version = "2.4.3" //编写本文时的最新版本，并非您阅读本文时的最新版本，可查看官方文档获取最新版本

    implementation "androidx.room:room-runtime:$room_version" //必选
    annotationProcessor "androidx.room:room-compiler:$room_version" // java选

    // To use Kotlin annotation processing tool (kapt)
    kapt "androidx.room:room-compiler:$room_version" // kotlin选，需要先导入kapt插件

    // To use Kotlin Symbol Processing (KSP)
    ksp "androidx.room:room-compiler:$room_version" //非必选 ，可提高kotlin编译速度

    // optional - RxJava2 support for Room
    implementation "androidx.room:room-rxjava2:$room_version" //非必选 

    // optional - RxJava3 support for Room
    implementation "androidx.room:room-rxjava3:$room_version" //非必选

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "androidx.room:room-guava:$room_version" //非必选

    // optional - Test helpers
    testImplementation "androidx.room:room-testing:$room_version" //非必选

    // optional - Paging 3 Integration
    implementation "androidx.room:room-paging:2.5.0-alpha03" //非必选
}

主要组件

Room 包含三个主要组件：

• 数据库类，用于保存数据库并作为应用持久性数据底层连接的主要访问点。
• 数据实体，用于表示应用的数据库中的表。
• 数据访问对象 (DAO)，提供您的应用可用于查询、更新、插入和删除数据库中的数据的方法。

数据库类为应用提供与该数据库关联的 DAO 的实例。反过来，应用可以使用 DAO 从数据库中检索数据，作为关联的数据实体对象的实例。此外，应用还可以使用定义的数据实体更新相应表中的行，或者创建新行供插入。图 1 说明了 Room 的不同组件之间的关系。

图1

示例

• 实体类

Room 允许通过实体创建表，以下代码定义了一个 User 数据实体。User 的每个实例都代表应用数据库中 user 表中的一行。
@Entity(tableName = "xxx") 每个 @Entity 类代表一个 SQLite 表，默认表明是类名
@PrimaryKey 主键
@PrimaryKey(autoGenerate = true)可自动生成唯一的主键。
@ColumnInfo(name = "xxx") 可自定义表中列的字段，默认字段是成员变量名
@Ignore 如果实体类中有不想保存到数据库的成员变量，则可以使用 @Ignore

@Entity(tableName = "user") 
data class User(
    @PrimaryKey val uid: Int,
    @ColumnInfo(name = "first_name") val firstName: String?,
    @ColumnInfo(name = "last_name") val lastName: String?,
    @Ignore val age: Int
)

• 数据访问对象 (DAO)

以下代码定义了一个名为 UserDao 的 DAO。UserDao 提供了应用的其余部分用于与 user 表中的数据交互的方法，在 DAO（数据访问对象）中，可以指定 SQL 查询并将其与方法调用相关联，DAO 必须是一个接口或抽象类

@Dao
interface UserDao {
    @Query("SELECT * FROM user")
    fun getAll(): List<User>

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    fun loadAllByIds(userIds: IntArray): List<User>

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND " +
           "last_name LIKE :last LIMIT 1")
    fun findByName(first: String, last: String): User

    @Insert
    fun insertAll(vararg users: User)

    @Delete
    fun delete(user: User)
}

• 数据库

以下代码定义了用于保存数据库的 AppDatabase 类。 AppDatabase 定义数据库配置，并作为应用对持久性数据的主要访问点。数据库类必须满足以下条件：

1. 该类必须带有 @Database注解，该注解包含列出所有与数据库关联的数据实体的 entities数组。
2. 该类必须是一个抽象类，用于扩展 RoomDatabase。
3. 对于与数据库关联的每个 DAO 类，数据库类必须定义一个具有零参数的抽象方法，并返回 DAO 类的实例。

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

• 操作数据库

定义数据实体、DAO 和数据库对象后，您可以使用以下代码创建数据库实例

val db = Room.databaseBuilder(
            applicationContext,
            AppDatabase::class.java, "database-name"
        ).build()

然后，您可以使用 AppDatabase 中的抽象方法获取 DAO 的实例，转而可以使用 DAO 实例中的方法与数据库进行交互：

val userDao = db.userDao()
val users: List<User> = userDao.getAll()