原生移动开发 / 系统课时
Room Entity 实体
Room Entity 实体
Room 的 Entity 决定 Kotlin 对象如何落到 SQLite 表中。本节用一个离线笔记模型建立 @Entity、@PrimaryKey 与 @ColumnInfo 的最小组合,并说明主键自动生成、列名映射以及后续修改实体时最容易踩到的边界。
学习目标
- 能用
@Entity把 Kotlin 数据类映射为 Room 表。 - 能正确设计自增主键,并用
@ColumnInfo固定数据库列名。 - 能通过构建结果确认 Room 可以处理当前实体定义。
把数据类声明成数据库表
@Entity 让 Room 把一个类纳入数据库模式,tableName 用来显式指定表名。属性默认映射到同名列;当 Kotlin 命名与数据库命名规范不同,例如 createdAt 对应 created_at,再使用 @ColumnInfo 固定列名。
下面是片段示例,依赖已经在 Android 模块中接入 Room 运行时和 Room 编译器(KSP 或 kapt)。
package com.example.offline
import androidx.room.ColumnInfo
import androidx.room.Entity
import androidx.room.PrimaryKey
@Entity(tableName = "notes")
data class NoteEntity(
@PrimaryKey(autoGenerate = true)
val id: Long = 0,
@ColumnInfo(name = "title")
val title: String,
@ColumnInfo(name = "body")
val body: String,
@ColumnInfo(name = "created_at")
val createdAt: Long
)这个类会被 Room 视为 notes 表的模式声明。id 是主键,title、body 和 created_at 是普通列;createdAt 只是在 Kotlin 侧使用驼峰命名,不会改变已经明确指定的数据库列名。
正确处理主键与列名
@PrimaryKey(autoGenerate = true) 适合由 SQLite 生成数值主键的场景。新建对象时让 id 保持默认值 0,插入后由 Room 返回实际生成的主键;业务代码不要提前把 0 当成持久化后的真实 ID。
@ColumnInfo 不需要给每个字段都写,但对需要稳定数据库列名的字段很有价值。比如未来把 Kotlin 属性 createdAt 重命名为 createdTime,只要仍然映射到 created_at,数据库列本身可以保持不变。
用构建确认 Room 能处理实体
在已经完成 Room 依赖配置的项目根目录执行构建。这个命令会触发 Room 的代码生成流程,因此实体声明存在不支持的类型、重复列名或处理器配置错误时,通常会在编译阶段暴露。
./gradlew assembleDebug预期输出(精简):
BUILD SUCCESSFUL in <TIME>实际耗时会不同。构建成功只说明 Entity 可以被当前工程处理;真正读写数据还需要 DAO 和 RoomDatabase。设计 Entity 时优先保持表名、主键和持久化列名稳定,可以显著降低后续迁移的复杂度。