使用 Room 实体定义数据

当您使用 Room 持久性库存储应用数据时，您需要定义实体来表示要存储的对象。每个实体对应于关联 Room 数据库中的一个表，每个实体实例表示相应表中的一行数据。

这意味着您可以使用 Room 实体来定义您的数据库架构，而无需编写任何 SQL 代码。

实体的结构

您将每个 Room 实体定义为一个使用 @Entity 注解的类。Room 实体包含数据库中对应表每个列的字段，包括一个或多个组成主键的列。

以下代码是定义 User 表的简单实体示例，该表包含用于 ID、名字和姓氏的列：

Kotlin

@Entity
data class User(
    @PrimaryKey val id: Int,

    val firstName: String?,
    val lastName: String?
)

Java

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

    public String firstName;
    public String lastName;
}

默认情况下，Room 使用类名作为数据库表名。如果您希望表具有不同的名称，请设置 @Entity 注解的 tableName 属性。同样，Room 默认情况下使用字段名作为数据库中的列名。如果您希望列具有不同的名称，请向字段添加 @ColumnInfo 注解并设置 name 属性。以下示例演示了表及其列的自定义名称：

Kotlin

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

Java

@Entity(tableName = "users")
public class User {
    @PrimaryKey
    public int id;

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

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

定义主键

每个 Room 实体必须定义一个主键，用于唯一标识相应数据库表中的每一行。最直接的方法是使用 @PrimaryKey 注解单个列：

Kotlin

@PrimaryKey val id: Int

Java

@PrimaryKey
public int id;

定义复合主键

如果您需要通过多个列的组合来唯一标识实体实例，您可以通过在 @Entity 的 primaryKeys 属性中列出这些列来定义复合主键：

Kotlin

@Entity(primaryKeys = ["firstName", "lastName"])
data class User(
    val firstName: String?,
    val lastName: String?
)

Java

@Entity(primaryKeys = {"firstName", "lastName"})
public class User {
    public String firstName;
    public String lastName;
}

忽略字段

默认情况下，Room 为实体中定义的每个字段创建一个列。如果一个实体有您不希望持久化的字段，您可以使用 @Ignore 对其进行注解，如以下代码片段所示：

Kotlin

@Entity
data class User(
    @PrimaryKey val id: Int,
    val firstName: String?,
    val lastName: String?,
    @Ignore val picture: Bitmap?
)

Java

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

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

在实体继承父实体字段的情况下，通常更容易使用 @Entity 属性的 ignoredColumns 属性：

Kotlin

open class User {
    var picture: Bitmap? = null
}

@Entity(ignoredColumns = ["picture"])
data class RemoteUser(
    @PrimaryKey val id: Int,
    val hasVpn: Boolean
) : User()

Java

@Entity(ignoredColumns = "picture")
public class RemoteUser extends User {
    @PrimaryKey
    public int id;

    public boolean hasVpn;
}

提供表搜索支持

Room 支持多种注解类型，可让您更轻松地在数据库表中搜索详细信息。除非您的应用的 minSdkVersion 小于 16，否则请使用全文搜索。

支持全文搜索

如果您的应用需要通过全文搜索 (FTS) 非常快速地访问数据库信息，请让您的实体由使用 FTS3 或 FTS4 SQLite 扩展模块的虚拟表支持。要使用此功能（在 Room 2.1.0 及更高版本中可用），请向给定实体添加 @Fts3 或 @Fts4 注解，如以下代码片段所示：

Kotlin

// Use `@Fts3` only if your app has strict disk space requirements or if you
// require compatibility with an older SQLite version.
@Fts4
@Entity(tableName = "users")
data class User(
    /* Specifying a primary key for an FTS-table-backed entity is optional, but
       if you include one, it must use this type and column name. */
    @PrimaryKey @ColumnInfo(name = "rowid") val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String?
)

Java

// Use `@Fts3` only if your app has strict disk space requirements or if you
// require compatibility with an older SQLite version.
@Fts4
@Entity(tableName = "users")
public class User {
    // Specifying a primary key for an FTS-table-backed entity is optional, but
    // if you include one, it must use this type and column name.
    @PrimaryKey
    @ColumnInfo(name = "rowid")
    public int id;

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

在表支持多种语言的内容的情况下，使用 languageId 选项指定存储每行语言信息的列：

Kotlin

@Fts4(languageId = "lid")
@Entity(tableName = "users")
data class User(
    // ...
    @ColumnInfo(name = "lid") val languageId: Int
)

Java

@Fts4(languageId = "lid")
@Entity(tableName = "users")
public class User {
    // ...

    @ColumnInfo(name = "lid")
    int languageId;
}

Room 提供了其他几个选项来定义 FTS 支持的实体，包括结果排序、分词器类型以及作为外部内容管理的表。有关这些选项的更多详细信息，请参阅 FtsOptions 参考。

索引特定列

如果您的应用必须支持不支持 FTS3 或 FTS4 表支持的实体的 SDK 版本，您仍然可以索引数据库中的某些列来加快查询速度。要向实体添加索引，请在 @Entity 注解中包含 indices 属性，列出您希望包含在索引或复合索引中的列名。以下代码片段演示了此注解过程：

Kotlin

@Entity(indices = [Index(value = ["last_name", "address"])])
data class User(
    @PrimaryKey val id: Int,
    val firstName: String?,
    val address: String?,
    @ColumnInfo(name = "last_name") val lastName: String?,
    @Ignore val picture: Bitmap?
)

Java

@Entity(indices = {@Index("name"),
        @Index(value = {"last_name", "address"})})
public class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String address;

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

    @Ignore
    Bitmap picture;
}

有时，数据库中的某些字段或字段组必须是唯一的。您可以通过将 @Index 注解的 unique 属性设置为 true 来强制执行此唯一性属性。以下代码示例阻止表中出现具有相同 firstName 和 lastName 列值集的两行：

Kotlin

@Entity(indices = [Index(value = ["first_name", "last_name"],
        unique = true)])
data class User(
    @PrimaryKey val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String?,
    @ColumnInfo(name = "last_name") val lastName: String?,
    @Ignore var picture: Bitmap?
)

Java

@Entity(indices = {@Index(value = {"first_name", "last_name"},
        unique = true)})
public class User {
    @PrimaryKey
    public int id;

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

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

    @Ignore
    Bitmap picture;
}

包含基于 AutoValue 的对象

在 Room 2.1.0 及更高版本中，您可以将使用 @AutoValue 注解的基于 Java 的不可变值类用作应用数据库中的实体。当两个实体实例因其列包含相同值而相等时，此支持特别有用。

当使用使用 @AutoValue 注解的类作为实体时，您可以使用 @PrimaryKey、@ColumnInfo、@Embedded 和 @Relation 注解类的抽象方法。但是，使用这些注解时，您必须每次都包含 @CopyAnnotations 注解，以便 Room 正确解释方法的自动生成实现。

以下代码片段显示了 Room 识别为实体的、使用 @AutoValue 注解的类示例：

User.java

@AutoValue
@Entity
public abstract class User {
    // Supported annotations must include `@CopyAnnotations`.
    @CopyAnnotations
    @PrimaryKey
    public abstract long getId();

    public abstract String getFirstName();
    public abstract String getLastName();

    // Room uses this factory method to create User objects.
    public static User create(long id, String firstName, String lastName) {
        return new AutoValue_User(id, firstName, lastName);
    }
}

下一步

使用 DAO 访问数据

使用 Room 实体定义数据 使用集合保持井井有条 根据您的偏好保存内容并分类。

实体的结构

Kotlin

Java

Kotlin

Java

定义主键

Kotlin

Java

定义复合主键

Kotlin

Java

忽略字段

Kotlin

Java

Kotlin

Java

提供表搜索支持

支持全文搜索

Kotlin

Java

Kotlin

Java

索引特定列

Kotlin

Java

Kotlin

Java

包含基于 AutoValue 的对象

使用 Room 实体定义数据