使用 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 注解,您可以定义将其参数插入数据库中的相应表的方法。以下代码展示了将一个或多个 User 对象插入数据库的有效 @Insert 方法示例:

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 注解的参考文档以及 rowid 表的 SQLite 文档

更新

借助 @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();

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

返回表中多个列的子集

在大多数情况下,您只需要返回要查询的表中若干列的子集。例如,您的界面可能仅显示用户的名字和姓氏,而不是该用户的每一条详细信息。为了节省资源并简化查询的执行,请仅查询所需的字段。

借助 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_namelast_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;
   }
}

返回多重映射

在 Room 2.4 及更高版本中,您还可以通过编写返回多重映射的查询方法来查询多个表中的列,而无需定义其他数据类。

请参考查询多个表部分中的示例。您可以直接从您的查询方法返回 UserBook 的映射,而不是返回保存有 UserBook 实例配对的自定义数据类的实例列表。

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();

查询方法返回多重映射时,您可以编写使用 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 注解中设置 keyColumnvalueColumn 属性,返回查询中特定列之间的映射:

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 访问数据,请参阅以下其他资源:

示例

Codelab