原生移动开发 / 系统课时

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)。

kotlin
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 的代码生成流程,因此实体声明存在不支持的类型、重复列名或处理器配置错误时,通常会在编译阶段暴露。

bash
./gradlew assembleDebug

预期输出(精简):

text
BUILD SUCCESSFUL in <TIME>

实际耗时会不同。构建成功只说明 Entity 可以被当前工程处理;真正读写数据还需要 DAO 和 RoomDatabase。设计 Entity 时优先保持表名、主键和持久化列名稳定,可以显著降低后续迁移的复杂度。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Room Entity 实体

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通