实体(Entity)基础定义

Room 中的 Entity 用于描述一张数据库表的映射结构。每个标注 @Entity 的类对应一张表，类的成员变量对应表的列。本章逐一拆解 @Entity 注解的核心属性：表名、主键、字段列名、忽略字段以及索引声明，并通过完整的代码示例串联所有知识点。

@Entity 注解与表名

使用 @Entity 标记一个类为数据库实体。默认情况下表名与类名相同，可以通过 tableName 显式指定，从而隔离 Java 命名与 SQL 命名规范。例如类名 User 可映射为表 users。

主键定义

使用 @PrimaryKey 标注在字段上。支持以下三种场景：

• 单一自增主键：@PrimaryKey(autoGenerate = true)
• 单一手动主键：@PrimaryKey (无 autoGenerate)
• 复合主键：在 @Entity 中通过 primaryKeys 属性指定

字段列名映射

默认情况下，Room 按照字段名生成 SQL 列名，camelCase 转为 snake_case。如需精确控制列名，使用 @ColumnInfo(name = "...") 注解。常见场景：

• 数据库已使用不同命名风格，如 user_name
• 字段名包含 SQL 关键字，需要转义
• 缩短列名以优化存储

忽略字段

用 @Ignore 标注不需要持久化的字段。这些字段用于临时计算、UI 状态或对象引用，不会被写入数据库表。被忽略的字段可以被 transient 修饰，但 Room 推荐明确使用 @Ignore 提高可读性。

索引声明

在 @Entity 的 indices 属性中声明索引，可提升查询性能。索引支持以下选项：

完整实体示例：User

下面展示一个综合实体定义，覆盖表名、自增主键、列名映射、忽略字段和索引声明：

@Entity(
    tableName = "users",
    indices = {
        @Index(value = {"name", "age"}, unique = false),
        @Index(value = {"email"}, unique = true)
    }
)
public class User {
    @PrimaryKey(autoGenerate = true)
    @ColumnInfo(name = "user_id")
    private long id;

    @ColumnInfo(name = "name")
    private String name;

    @ColumnInfo(name = "age")
    private int age;

    @ColumnInfo(name = "email")
    private String email;

    @ColumnInfo(name = "address")
    private String address;

    @Ignore
    private String tempAvatarUrl;  // 临时头像 URL，不持久化

    // 构造函数、getter/setter 省略…
}

常见错误与避坑

• 自增主键不能是包装类型：Long/Integer 会导致运行时异常，必须用基本类型 long/int。
• 忽略字段的构造函数：如果实体有多个构造函数，Room 要求一个构造函数不包含忽略的字段，以便创建对象时直接赋值。
• 复合主键与 @NonNull：复合主键的任何字段都不能为 null，必须在实体中标注 @NonNull。
• 索引命名冲突：不同实体不建议使用相同索引名，Room 不会自动加前缀，建议手动命名如 "idx_users_email"。