使用 Room DAO 访问数据

当您使用 Room 持久性库存储应用数据时，您可以通过定义数据访问对象 (DAO) 来与存储的数据进行交互。每个 DAO 都包含提供对应用数据库抽象访问的方法。在编译时，Room 会自动生成您定义的 DAO 的实现。

通过使用 DAO 访问应用数据库，而不是查询构建器或直接查询，您可以保持关注点分离，这是一项关键的架构原则。DAO 也使您在测试应用时更容易模拟数据库访问。

DAO 的构成

您可以将每个 DAO 定义为接口或抽象类。对于基本用例，通常使用接口。无论哪种情况，您都必须始终使用 @Dao 标注您的 DAO。DAO 没有属性，但它们确实定义了一个或多个方法用于与应用数据库中的数据进行交互。

以下代码是一个简单 DAO 的示例，它定义了用于在 Room 数据库中插入、删除和选择 User 对象的方法

Kotlin

@Dao
interface UserDao {
    @Insert
    fun insertAll(vararg users: User)

    @Delete
    fun delete(user: User)

    @Query("SELECT * FROM user")
    fun getAll(): List<User>
}

Java

@Dao
public interface UserDao {
    @Insert
    void insertAll(User... users);

    @Delete
    void delete(User user);

    @Query("SELECT * FROM user")
    List<User> getAll();
}

有两种类型的 DAO 方法定义了数据库交互

便利方法，让您无需编写任何 SQL 代码即可在数据库中插入、更新和删除行。
查询方法，让您可以编写自己的 SQL 查询来与数据库交互。

以下章节演示了如何使用这两种类型的 DAO 方法来定义应用所需的数据库交互。

便利方法

Room 提供了便利注解，用于定义执行简单插入、更新和删除的方法，而无需您编写 SQL 语句。

如果您需要定义更复杂的插入、更新或删除操作，或者您需要查询数据库中的数据，请改为使用查询方法。

插入

@Insert 注解允许您定义将参数插入数据库中相应表格的方法。以下代码显示了有效的 @Insert 方法示例，这些方法将一个或多个 User 对象插入数据库

Kotlin

@Dao
interface UserDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    fun insertUsers(vararg users: User)

    @Insert
    fun insertBothUsers(user1: User, user2: User)

    @Insert
    fun insertUsersAndFriends(user: User, friends: List<User>)
}

Java

@Dao
public interface UserDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    public void insertUsers(User... users);

    @Insert
    public void insertBothUsers(User user1, User user2);

    @Insert
    public void insertUsersAndFriends(User user, List<User> friends);
}

@Insert 方法的每个参数必须是使用 @Entity 标注的Room 数据实体类的实例，或是一组数据实体类实例的集合，每个实例都指向一个数据库。调用 @Insert 方法时，Room 会将每个传入的实体实例插入相应的数据库表。

如果 @Insert 方法接收单个参数，它可以返回一个 long 值，该值是被插入项的新 rowId。如果参数是数组或集合，则改为返回 long 值的数组或集合，其中每个值是被插入项之一的 rowId。要详细了解如何返回 rowId 值，请参阅 @Insert 注解的参考文档以及SQLite rowid 表格文档。

更新

@Update 注解允许您定义更新数据库表中特定行的方法。与 @Insert 方法类似，@Update 方法接受数据实体实例作为参数。以下代码显示了一个 @Update 方法的示例，该方法尝试更新数据库中的一个或多个 User 对象

Kotlin

@Dao
interface UserDao {
    @Update
    fun updateUsers(vararg users: User)
}

Java

@Dao
public interface UserDao {
    @Update
    public void updateUsers(User... users);
}

Room 使用主键将传入的实体实例与数据库中的行进行匹配。如果没有与主键相同的行，Room 不会进行任何更改。

一个 @Update 方法可以选择返回一个 int 值，表示成功更新的行数。

删除

@Delete 注解允许您定义从数据库表中删除特定行的方法。与 @Insert 方法类似，@Delete 方法接受数据实体实例作为参数。以下代码显示了一个 @Delete 方法的示例，该方法尝试从数据库中删除一个或多个 User 对象

Kotlin

@Dao
interface UserDao {
    @Delete
    fun deleteUsers(vararg users: User)
}

Java

@Dao
public interface UserDao {
    @Delete
    public void deleteUsers(User... users);
}

Room 使用主键将传入的实体实例与数据库中的行进行匹配。如果没有与主键相同的行，Room 不会进行任何更改。

一个 @Delete 方法可以选择返回一个 int 值，表示成功删除的行数。

查询方法

@Query 注解允许您编写 SQL 语句并将其公开为 DAO 方法。使用这些查询方法来查询应用数据库中的数据，或在需要执行更复杂的插入、更新和删除操作时使用它们。

Room 在编译时验证 SQL 查询。这意味着如果您的查询有问题，会在编译时发生错误，而不是在运行时失败。

简单查询

以下代码定义了一个方法，该方法使用一个简单的 SELECT 查询来返回数据库中的所有 User 对象

Kotlin

@Query("SELECT * FROM user")
fun loadAllUsers(): Array<User>

Java

@Query("SELECT * FROM user")
public User[] loadAllUsers();

以下章节演示了如何针对典型用例修改此示例。

返回表格列的子集

大多数情况下，您只需要返回正在查询的表格中的列的子集。例如，您的 UI 可能只显示用户的名字和姓氏，而不是关于该用户的每个详细信息。为了节省资源并简化查询的执行，只查询您需要的字段。

Room 允许您从任何查询中返回一个简单对象，只要您可以将结果列集映射到返回的对象上。例如，您可以定义以下对象来保存用户的名字和姓氏

Kotlin

data class NameTuple(
    @ColumnInfo(name = "first_name") val firstName: String?,
    @ColumnInfo(name = "last_name") val lastName: String?
)

Java

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

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

然后，您可以从查询方法中返回该简单对象

Kotlin

@Query("SELECT first_name, last_name FROM user")
fun loadFullName(): List<NameTuple>

Java

@Query("SELECT first_name, last_name FROM user")
public List<NameTuple> loadFullName();

Room 知道查询返回 first_name 和 last_name 列的值，并且这些值可以映射到 NameTuple 类中的字段。如果查询返回的列没有映射到返回对象中的字段，Room 会显示警告。

向查询传递简单参数

大多数情况下，您的 DAO 方法需要接受参数以便执行过滤操作。Room 支持在查询中使用方法参数作为绑定参数。

例如，以下代码定义了一个方法，该方法返回所有年龄在特定岁数以上的用户

Kotlin

@Query("SELECT * FROM user WHERE age > :minAge")
fun loadAllUsersOlderThan(minAge: Int): Array<User>

Java

@Query("SELECT * FROM user WHERE age > :minAge")
public User[] loadAllUsersOlderThan(int minAge);

您还可以向查询传递多个参数或多次引用同一参数，如下列代码所示

Kotlin

@Query("SELECT * FROM user WHERE age BETWEEN :minAge AND :maxAge")
fun loadAllUsersBetweenAges(minAge: Int, maxAge: Int): Array<User>

@Query("SELECT * FROM user WHERE first_name LIKE :search " +
       "OR last_name LIKE :search")
fun findUserWithName(search: String): List<User>

Java

@Query("SELECT * FROM user WHERE age BETWEEN :minAge AND :maxAge")
public User[] loadAllUsersBetweenAges(int minAge, int maxAge);

@Query("SELECT * FROM user WHERE first_name LIKE :search " +
       "OR last_name LIKE :search")
public List<User> findUserWithName(String search);

向查询传递参数集合

您的某些 DAO 方法可能需要您传入数量可变的参数，这些参数在运行时之前未知。Room 知道何时参数代表一个集合，并根据提供的参数数量在运行时自动展开它。

例如，以下代码定义了一个方法，该方法返回来自部分地区的所有用户的信息

Kotlin

@Query("SELECT * FROM user WHERE region IN (:regions)")
fun loadUsersFromRegions(regions: List<String>): List<User>

Java

@Query("SELECT * FROM user WHERE region IN (:regions)")
public List<User> loadUsersFromRegions(List<String> regions);

查询多个表格

您的某些查询可能需要访问多个表格来计算结果。您可以在 SQL 查询中使用 JOIN 子句来引用多个表格。

以下代码定义了一个方法，该方法将三个表格连接在一起，以返回当前借给特定用户的书籍

Kotlin

@Query(
    "SELECT * FROM book " +
    "INNER JOIN loan ON loan.book_id = book.id " +
    "INNER JOIN user ON user.id = loan.user_id " +
    "WHERE user.name LIKE :userName"
)
fun findBooksBorrowedByNameSync(userName: String): List<Book>

Java

@Query("SELECT * FROM book " +
       "INNER JOIN loan ON loan.book_id = book.id " +
       "INNER JOIN user ON user.id = loan.user_id " +
       "WHERE user.name LIKE :userName")
public List<Book> findBooksBorrowedByNameSync(String userName);

您还可以定义简单对象来返回多个连接表格中的列子集，如返回表格列的子集部分所述。以下代码定义了一个 DAO，其中包含一个方法，该方法返回用户的姓名以及他们借阅的书籍的名称

Kotlin

interface UserBookDao {
    @Query(
        "SELECT user.name AS userName, book.name AS bookName " +
        "FROM user, book " +
        "WHERE user.id = book.user_id"
    )
    fun loadUserAndBookNames(): LiveData<List<UserBook>>

    // You can also define this class in a separate file.
    data class UserBook(val userName: String?, val bookName: String?)
}

Java

@Dao
public interface UserBookDao {
   @Query("SELECT user.name AS userName, book.name AS bookName " +
          "FROM user, book " +
          "WHERE user.id = book.user_id")
   public LiveData<List<UserBook>> loadUserAndBookNames();

   // You can also define this class in a separate file, as long as you add the
   // "public" access modifier.
   static class UserBook {
       public String userName;
       public String bookName;
   }
}

返回 multimap

在 Room 2.4 及更高版本中，您还可以通过编写返回multimap的查询方法来查询多个表格中的列，而无需定义额外的数据类。

考虑查询多个表格部分中的示例。您可以直接从查询方法返回 User 和 Book 的映射，而不是返回包含 User 和 Book 实例配对的自定义数据类实例列表

Kotlin

@Query(
    "SELECT * FROM user" +
    "JOIN book ON user.id = book.user_id"
)
fun loadUserAndBookNames(): Map<User, List<Book>>

Java

@Query(
    "SELECT * FROM user" +
    "JOIN book ON user.id = book.user_id"
)
public Map<User, List<Book>> loadUserAndBookNames();

当您的查询方法返回 multimap 时，您可以编写使用 GROUP BY 子句的查询，从而利用 SQL 的能力进行高级计算和过滤。例如，您可以修改您的 loadUserAndBookNames() 方法，使其仅返回借阅了三本或更多书籍的用户

Kotlin

@Query(
    "SELECT * FROM user" +
    "JOIN book ON user.id = book.user_id" +
    "GROUP BY user.name WHERE COUNT(book.id) >= 3"
)
fun loadUserAndBookNames(): Map<User, List<Book>>

Java

@Query(
    "SELECT * FROM user" +
    "JOIN book ON user.id = book.user_id" +
    "GROUP BY user.name WHERE COUNT(book.id) >= 3"
)
public Map<User, List<Book>> loadUserAndBookNames();

如果您不需要映射整个对象，您也可以通过在查询方法上设置 @MapInfo 注解中的 keyColumn 和 valueColumn 属性，来返回查询中特定列之间的映射

Kotlin

@MapInfo(keyColumn = "userName", valueColumn = "bookName")
@Query(
    "SELECT user.name AS username, book.name AS bookname FROM user" +
    "JOIN book ON user.id = book.user_id"
)
fun loadUserAndBookNames(): Map<String, List<String>>

Java

@MapInfo(keyColumn = "userName", valueColumn = "bookName")
@Query(
    "SELECT user.name AS username, book.name AS bookname FROM user" +
    "JOIN book ON user.id = book.user_id"
)
public Map<String, List<String>> loadUserAndBookNames();

特殊返回类型

Room 提供了一些特殊返回类型，用于与其他 API 库集成。

使用 Paging 库进行分页查询

Room 通过与 Paging 库集成来支持分页查询。在 Room 2.3.0-alpha01 及更高版本中，DAO 可以返回 PagingSource 对象，以便与 Paging 3 一起使用。

Kotlin

@Dao
interface UserDao {
  @Query("SELECT * FROM users WHERE label LIKE :query")
  fun pagingSource(query: String): PagingSource<Int, User>
}

Java

@Dao
interface UserDao {
  @Query("SELECT * FROM users WHERE label LIKE :query")
  PagingSource<Integer, User> pagingSource(String query);
}

有关为 PagingSource 选择类型参数的更多信息，请参阅选择键值类型。

直接光标访问

如果您的应用逻辑需要直接访问返回的行，您可以编写 DAO 方法以返回 Cursor 对象，如下例所示

Kotlin

@Dao
interface UserDao {
    @Query("SELECT * FROM user WHERE age > :minAge LIMIT 5")
    fun loadRawUsersOlderThan(minAge: Int): Cursor
}

Java

@Dao
public interface UserDao {
    @Query("SELECT * FROM user WHERE age > :minAge LIMIT 5")
    public Cursor loadRawUsersOlderThan(int minAge);
}

其他资源

要详细了解如何使用 Room DAO 访问数据，请参阅以下其他资源

示例

Android Sunflower

Codelabs

Android Room with a View (Java) (Kotlin)

使用实体定义数据

编写异步 DAO 查询

使用 Room DAO 访问数据 使用集合保持井然有序 根据您的偏好保存内容并分类。

DAO 的构成

Kotlin

Java

便利方法

插入

Kotlin

Java

更新

Kotlin

Java

删除

Kotlin

Java

查询方法

简单查询

Kotlin

Java

返回表格列的子集

Kotlin

Java

Kotlin

Java

向查询传递简单参数

Kotlin

Java

Kotlin

Java

向查询传递参数集合

Kotlin

Java

查询多个表格

Kotlin

Java

Kotlin

Java

返回 multimap

Kotlin

Java

Kotlin

Java

Kotlin

Java

特殊返回类型

使用 Paging 库进行分页查询

Kotlin

Java

直接光标访问

Kotlin

Java

其他资源

示例

Codelabs

使用 Room DAO 访问数据