使用 Room 在本地数据库中保存数据   是 Android Jetpack 的一部分。

处理大量结构化数据的应用可以从在本地持久化这些数据中获益匪浅。最常见的用例是缓存相关的数据片段，以便在设备无法访问网络时，用户仍然可以在脱机状态下浏览这些内容。

Room 持久性库在 SQLite 上提供了一个抽象层，允许流畅地访问数据库，同时利用 SQLite 的全部功能。特别是，Room 提供以下优势

  • SQL 查询的编译时验证。
  • 方便的注释，最大程度地减少重复且容易出错的样板代码。
  • 简化的数据库迁移路径。

由于这些原因，我们强烈建议您使用 Room 而不是 直接使用 SQLite API。

设置

要在您的应用中使用 Room，请将以下依赖项添加到应用的 build.gradle 文件中。

Kotlin

dependencies {
    val room_version = "2.6.1"

    implementation("androidx.room:room-runtime:$room_version")

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See Add the KSP plugin to your project
    ksp("androidx.room:room-compiler:$room_version")

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor("androidx.room:room-compiler:$room_version")

    // optional - Kotlin Extensions and Coroutines support for Room
    implementation("androidx.room:room-ktx:$room_version")

    // 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:$room_version")
}

Groovy

dependencies {
    def room_version = "2.6.1"

    implementation "androidx.room:room-runtime:$room_version"

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See KSP Quickstart to add KSP to your build
    ksp "androidx.room:room-compiler:$room_version"

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor "androidx.room:room-compiler:$room_version"

    // 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:$room_version"
}

主要组件

Room 中有三个主要组件

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

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

图 1. Room 库架构图。

示例实现

本节介绍具有单个数据实体和单个 DAO 的 Room 数据库的示例实现。

数据实体

以下代码定义了一个 User 数据实体。每个 User 实例表示应用数据库中 user 表中的一行。

Kotlin

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

Java

@Entity
public class User {
    @PrimaryKey
    public int uid;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;
}

要了解有关 Room 中数据实体的更多信息，请参阅 使用 Room 实体定义数据。

数据访问对象 (DAO)

以下代码定义了一个名为 UserDao 的 DAO。 UserDao 提供了应用其余部分用于与 user 表中的数据进行交互的方法。

Kotlin

@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)
}

Java

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

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    List<User> loadAllByIds(int[] userIds);

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

    @Insert
    void insertAll(User... users);

    @Delete
    void delete(User user);
}

要了解有关 DAO 的更多信息，请参阅 使用 Room DAO 访问数据。

数据库

以下代码定义了一个用于保存数据库的 AppDatabase 类。 AppDatabase 定义了数据库配置，并充当应用访问持久化数据的入口点。数据库类必须满足以下条件

  • 该类必须使用 @Database 注解进行注释，其中包含一个 entities 数组，该数组列出了与数据库关联的所有数据实体。
  • 该类必须是一个扩展 RoomDatabase 的抽象类。
  • 对于与数据库关联的每个 DAO 类，数据库类必须定义一个不带参数并返回 DAO 类实例的抽象方法。

Kotlin

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

Java

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}

注意： 如果您的应用在单个进程中运行，则在实例化 AppDatabase 对象时，应遵循单例设计模式。每个 RoomDatabase 实例都相当昂贵，并且您很少需要在单个进程中访问多个实例。

如果您的应用在多个进程中运行，请在数据库构建器调用中包含 enableMultiInstanceInvalidation()。这样，当您在每个进程中都有一个 AppDatabase 实例时，您可以在一个进程中使共享数据库文件失效，并且此失效会自动传播到其他进程中的 AppDatabase 实例。

用法

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

Kotlin

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

Java

AppDatabase db = Room.databaseBuilder(getApplicationContext(),
        AppDatabase.class, "database-name").build();

然后，您可以使用 AppDatabase 中的抽象方法获取 DAO 的实例。依次，您可以使用 DAO 实例中的方法与数据库交互。

Kotlin

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

Java

UserDao userDao = db.userDao();
List<User> users = userDao.getAll();

其他资源

要了解有关 Room 的更多信息，请参阅以下其他资源

示例

Codelabs

博客