07.1.1.8.1 Room 实体、DAO、关系与迁移
所属:全栈开发面试题库 / 07 端侧与桌面开发 / 07.1 原生移动开发 / 07.1.1 Android / 07.1.1.8 Room 与数据层
本节要解决的问题
本节聚焦 Room 数据访问层的建模细节:实体与主键策略、列映射与类型转换器、一对多与多对多关系、DAO 返回类型与查询注解,以及数据库迁移、预填充与加密的落地约束。面试常从实体定义一路追问到迁移脚本与生成代码行为。版本前提:Room 2.6+/2.7、Android 14、KSP 注解处理;版本敏感处标「待确认」并写明验证点。
07.1.1.8.1-001 Room 实体类必须满足哪些约束?
一句话结论
实体必须是被 @Entity 标注的类,至少有一个 @PrimaryKey 字段,字段类型可被 SQLite 类型亲和性映射,且提供可读可写的访问方式。
概念解释
Room 编译期把实体字段映射为表列:Kotlin data class 的构造参数或属性都会被扫描,字段名默认作为列名,类型按亲和性归类为 INTEGER/TEXT/REAL/BLOB。实体不需要继承 Room 的基类,但主键、可空性、索引等元数据要通过注解显式声明。
原理流程
@Entity 标注 → 编译期扫描字段与注解 → 生成表结构元数据
→ 运行期通过反射或生成代码读写实体实例
代码或图示
@Entity
data class Note(
@PrimaryKey val id: Long,
val title: String,
val content: String,
val createdAt: Long
)
常见误区
- 把实体字段写成方法局部变量或函数返回值,Room 扫描不到。
- 实体里混入仅用于界面的临时状态,导致表列被无谓扩写。
追问
- 实体必须用 data class 吗?答:不是,普通 class 加可读写属性也可以,data class 只是便于值比较与复制。
- 实体可以继承父类字段吗?答:可以,父类中的可持久化字段会一并映射,层级过深时需在迁移脚本里同步列。
07.1.1.8.1-002 @PrimaryKey 如何声明?自增主键怎么配?
一句话结论
在字段上加 @PrimaryKey;自增把类型设为 Long 并配置 autoGenerate = true,插入时由 SQLite 分配主键。
概念解释
autoGenerate = true 对应 SQLite 的 INTEGER PRIMARY KEY AUTOINCREMENT 行为(底层行号关联),新记录不传主键时自动取未使用的最大行号加一。业务主键(如服务端 ID)不要依赖自增,应直接存入实体字段。
原理流程
插入语句省略主键列 → SQLite 分配自增主键 → 回填到实体实例
代码或图示
@Entity
data class Item(
@PrimaryKey(autoGenerate = true) val id: Long = 0,
val name: String
)
常见误区
- 自增主键用
Int,数据量增长后溢出风险;自增列推荐Long。 - 既有记录迁移过来后主键重复,或忘记给
id默认值导致编译告警。
追问
- AUTOINCREMENT 与普通 INTEGER PRIMARY KEY 的区别?答:后者复用删除后的空闲行号,前者单调递增不回收;序号连续性要求高时才用后者。
- 服务端下发的 ID 怎么存?答:作为普通业务字段,必要时另建唯一索引,不要混入自增语义。
07.1.1.8.1-003 主键类型为什么推荐 Long 而不是 Int?
一句话结论
SQLite 行号与自增主键按 64 位整数处理,Room 主键用 Long 与底层行号语义一致,也避免本地数据量增长后的溢出。
概念解释
INTEGER 在 SQLite 内部按 64 位有符号整数存储,Room 映射到 Kotlin Long 最直接;Int 在写入大值时需要拆箱转换,且自增到 21 亿以上会越界。跨端同步的实体主键若来自服务端雪花 ID、时间戳 ID,本身就超过 32 位。
原理流程
底层 64 位行号 ↔ Kotlin Long 直接映射;Int 需截断检查
代码或图示
@PrimaryKey val userId: Long
常见误区
- 用
Int存雪花 ID 或时间戳 ID,反序列化阶段就丢精度。 - 主键可空,与 SQLite 主键非空约束冲突,运行期报错。
追问
- 主键能是字符串吗?答:可以,TEXT 主键合法,但自增语义不适用,写入与索引代价高于整数主键。
- 复合主键各字段类型有约束吗?答:组合内每个字段都要非空,类型同样受亲和性约束。
07.1.1.8.1-004 复合主键怎么定义?适用什么场景?
一句话结论
在 @Entity 上用 primaryKeys = ["字段A", "字段B"] 声明联合主键,适合没有独立自增 ID、由多个业务字段唯一确定一条记录的表。
概念解释
单字段主键无法保证唯一性时,用多列组合唯一标识记录,例如 (orderId, itemId) 明细行。复合主键自动形成覆盖这些列的索引;插入冲突按整组字段判断,而不是单列。
原理流程
表结构创建:PRIMARY KEY (colA, colB)
→ 插入/更新按 (colA, colB) 整组查重
代码或图示
@Entity(primaryKeys = ["orderId", "itemId"])
data class OrderItem(
val orderId: Long,
val itemId: Long,
val quantity: Int
)
常见误区
- 复合主键字段用可空类型,违背主键非空约束。
- 先加自增 ID 又配复合主键,两套唯一标识并存,关系表连接时容易连错列。
追问
- 复合主键能被外键引用吗?答:能,但引用方外键要包含对应数量的列,外键声明按列顺序对齐。
- 复合主键与唯一索引怎么选?答:主键即唯一且非空;未来可能拆分独立 ID 的表,优先用单列自增主键加唯一索引。
07.1.1.8.1-005 @Entity 的 tableName 与 indices 如何配置?
一句话结论
tableName 覆盖默认类名作为表名;indices 列表声明普通索引与唯一索引,编译期生成 CREATE INDEX 语句。
概念解释
表名默认是实体类名,多模块下类名重名时必须显式改名。索引声明在实体上,迁移时新索引需要在 Migration 脚本里单独 CREATE INDEX;索引覆盖高频 WHERE、JOIN、ORDER BY 列以避免全表扫描。
原理流程
@Entity(indices = [Index(value = ["createdAt"])])
→ 建表语句附带索引定义
代码或图示
@Entity(
tableName = "notes",
indices = [
Index(value = ["createdAt"]),
Index(value = ["userId"], unique = true)
]
)
data class Note(...)
常见误区
- 只在实体上加索引,迁移脚本漏建,老库升级后查询仍是全表扫描。
- 索引列顺序与查询条件不匹配,复合索引左侧列用不上。
追问
unique = true与单独列唯一约束等价吗?答:等价于在这些列上建唯一索引,重复组合插入会被拒绝。- 索引能在实体之外动态创建吗?答:可以在迁移脚本或回调里
execSQL,但 Room 元数据不感知,测试校验需自行覆盖。
07.1.1.8.1-006 唯一约束(UNIQUE)怎么在 Room 里声明?
一句话结论
列级唯一用 Index(value = ["列"], unique = true);也可在 @Entity(indices = ...) 内声明,Room 生成唯一索引或表级 UNIQUE 约束。
概念解释
唯一约束保证一列或一组组合在全表内不重复:unique = true 的索引底层就是唯一索引。业务上手机号、订单号、外部回调 ID 这类需要去重的字段应加唯一约束,而不是靠应用层先查再插。
原理流程
插入重复值 → SQLite 约束冲突 → 抛出 SQLException
→ DAO 的冲突策略决定是回退、替换还是报错
代码或图示
@Entity(indices = [Index(value = ["phone"], unique = true)])
data class Contact(val id: Long, val phone: String)
常见误区
- 依赖应用层判重,并发插入时两个请求都通过检查导致重复。
- 可空列上唯一约束的空值语义:SQLite 中 NULL 互不相等,多条空值可以共存。
追问
- 唯一索引与普通索引写入代价差多少?答:唯一约束需要额外查重,写入略高;高频写入、唯一性不强的字段不必强行加唯一索引。
- 唯一约束冲突如何优雅处理?答:DAO
@Insert(onConflict = ...)选择 ABORT 后捕获异常,或用 IGNORE/REPLACE 按业务语义处理。
07.1.1.8.1-007 @ColumnInfo 的 name、typeAffinity、collate 各有什么用?
一句话结论
name 指定列名,typeAffinity 覆盖类型亲和性归类,collate 指定排序规则(BINARY/NOCASE/RTRIM/LOCALIZED)。
概念解释
默认列名取属性名,name 用于与旧表列名对齐。typeAffinity 强制把字段归入 INTEGER/TEXT/REAL/BLOB,例如把枚举存成 TEXT。collate 影响比较与排序:NOCASE 忽略大小写,中文排序通常依赖 LOCALIZED 或自行排序。
原理流程
注解元数据 → 生成列定义 → 查询比较时按 collate 规则执行
代码或图示
@ColumnInfo(name = "nick_name", typeAffinity = ColumnInfo.TEXT)
val nickname: String?
@ColumnInfo(collate = ColumnInfo.NOCASE)
val email: String
常见误区
- 改了属性名但没设
name,迁移后列名跟着变,旧数据查不到。 - 期望中文拼音排序,却依赖默认 BINARY 规则,结果按 Unicode 码位排列。
追问
- typeAffinity 与 TypeConverter 有什么区别?答:前者只改 SQLite 侧归类,后者负责 Java/Kotlin 类型与 SQLite 存储类型之间的双向转换。
- collate 能在建表后改吗?答:列排序规则随表结构定义,修改通常要重建表或在查询
ORDER BY ... COLLATE中指定。
07.1.1.8.1-008 实体字段设计为什么要避免直接暴露可变状态?
一句话结论
实体应是不可变或值语义的对象,构造即定型;可变公开属性会让 Repository 层难以追踪修改,也容易在查询回调中被并发改写。
概念解释
Room 读出的实体会被 Flow/List 等载体分发到界面层,若属性可变且被界面直接修改,本地数据库与内存对象状态可能不一致。Kotlin data class 默认不可变属性配合 copy() 派生新对象,是推荐写法。
原理流程
数据库读出不可变实体 → 界面展示 → 需要变更时 copy 出新实体 → DAO 写回
代码或图示
data class Profile(val id: Long, val name: String) {
fun rename(newName: String) = copy(name = newName)
}
常见误区
- 实体类内部带
var字段并在 Activity 里直接改,绕过 DAO 持久化。 - 把网络请求状态、加载中标志等 UI 状态塞进实体表列。
追问
- 实体必须全字段可空吗?答:按业务区分:可缺省的字段标
?,必填字段保持非空;可空性会参与 Room 的写入校验。 - 实体能包含计算属性吗?答:可以,没有后端字段的属性(val 计算)不会被持久化,但需避免在属性里触发 IO。
07.1.1.8.1-009 transient 字段怎么排除持久化?
一句话结论
不希望落库的字段用 @Ignore(Kotlin 场景)或 Java 的 transient 标注,Room 扫描时会跳过。
概念解释
Room 只持久化被识别为持久化成员的字段,临时状态、UI 标记、计算缓存应显式排除,否则会在表结构里多出无用列。Kotlin 中 @Ignore 标在属性上;Java 实体配合 transient 关键字。
原理流程
扫描成员 → 命中 @Ignore/transient → 不生成列 → 不参与读写映射
代码或图示
@Entity
data class Task(
@PrimaryKey val id: Long,
val title: String,
@Ignore val expanded: Boolean = false
)
常见误区
- 用普通属性却忘了排除,Room 自动加列,迁移脚本被迫跟进。
@Ignore标在构造参数上导致 Room 无法构造实体实例。
追问
- 忽略字段在实体继承体系中如何处理?答:父类忽略字段不会被子类继承映射;跨层级忽略规则需在编译报错时逐个核对。
- 运行期临时对象放哪?答:放在 ViewModel/StateHolder 或独立的 UI 状态类,不要混进 Room 实体。
07.1.1.8.1-010 @Ignore 与 @Transient 的区别?
一句话结论
@Ignore 是 Room 注解,明确告诉 Room 跳过该成员;@Transient 是 Kotlin/Java 语言层面的序列化排除标记,Room 也会识别,但语义面向通用序列化。
概念解释
@Ignore 只服务 Room 映射,实体被 JSON 序列化时该字段仍会参与;@Transient 同时影响 Kotlin 序列化、Java 序列化等通用机制。项目里实体若只被 Room 使用,两者效果接近;混用序列化框架时要确认字段在 JSON 侧是否需要保留。
原理流程
Room 扫描:@Ignore 与 @Transient 成员均跳过
JSON 序列化:@Transient 被跳过,@Ignore 字段可能保留
代码或图示
@Entity
data class Book(
@PrimaryKey val id: Long,
@Transient val localMark: String = ""
)
常见误区
- 以为
@Ignore字段也不会被网络层序列化,导致把敏感临时字段发给后端。 - 混淆后迁移旧表:忽略字段历史上曾落库,旧列残留需在迁移脚本里清理。
追问
- Kotlin
@Transient与 Javatransient等价吗?答:语义相近,都是语言层持久化排除;跨语言互操作时以 Room 编译期识别结果为准。 - 忽略字段能否出现在 DAO 查询结果 POJO 里?答:POJO 只做结果承载,未映射字段保持默认值即可。
07.1.1.8.1-011 字段为 null 时 SQLite 如何存储?可空性怎么约束?
一句话结论
Kotlin 可空类型映射为可空列,写入 null 时 SQLite 存 NULL;非空类型在编译/写入阶段约束非空,NULL 写入会冲突报错。
概念解释
SQLite 本身列默认非严格强制非空,但 Room 按 Kotlin 类型生成表约束:非空属性对应 NOT NULL 列。外键关联、唯一索引中的 NULL 有特殊语义,查询时 IS NULL 与 = NULL 不能混用。
原理流程
实体属性类型 → 生成列可空性 → 写入 null 时按约束校验
代码或图示
@Entity
data class User(
@PrimaryKey val id: Long,
val nickname: String? // 可空列
)
常见误区
- 非空字段在迁移脚本里没给默认值,老库 NOT NULL 列插入失败。
- 用
WHERE col = NULL查询空值,正确写法是col IS NULL。
追问
- 可空字段建议加默认值吗?答:建议在 Kotlin 侧给默认值,减少构造与迁移分支;数据库侧默认值在迁移脚本中显式写入。
- NULL 参与唯一索引的规则?答:SQLite 认为多个 NULL 互不相等,唯一索引允许并存多条 NULL。
07.1.1.8.1-012 一个实体可以对应多张表吗?
一句话结论
不能。一个 @Entity 实例对应一张表;需要多表时拆成多个实体,再通过 DAO 查询或 @Relation 关联。
概念解释
Room 的表结构元数据与实体一一绑定,主键、列、索引都属于单表。业务上一张宽表概念若拆成主子两表,应分别定义实体,避免在一个实体里塞跨表字段。
原理流程
概念宽表 → 拆主实体 + 子实体 → DAO JOIN 或 Relation 组装
代码或图示
@Entity data class Order(@PrimaryKey val id: Long, val buyer: String)
@Entity data class OrderLine(@PrimaryKey val id: Long, val orderId: Long, val sku: String)
常见误区
- 用一个实体描述多表 JOIN 结果,再把它当成可写入实体注册进数据库。
- 查询结果 POJO 与写入实体混用,误把结果类加
@Entity。
追问
- 多表 JOIN 结果怎么承载?答:定义普通 POJO(不带
@Entity),DAO@Query直接映射;需要关系展开用@Relation。 - 实体能对应视图吗?答:可以用
@DatabaseView定义只读视图,查询映射到普通类。
07.1.1.8.1-013 索引覆盖哪些查询场景?索引过多有什么代价?
一句话结论
索引加速 WHERE 过滤、JOIN 连接、ORDER BY/GROUP BY;但每个索引都增加写入与存储成本,应按高频查询选择性建立。
概念解释
索引是冗余的数据结构,写入时要同步维护;低基数列(如性别、状态)区分度差,索引收益低。评估索引看查询频次、返回行占比与写入频率:读多写少的列优先建索引,写多读少的克制使用。
原理流程
查询条件命中索引 → 索引定位 rowid → 回表取行
写入时:先写表,再逐索引更新
代码或图示
-- 高频:按用户分组查最近订单
CREATE INDEX INDEX_ORDER_USER_TIME ON orders(user_id, created_at DESC);
常见误区
- 给所有列加索引,列表插入/更新变慢,包体与索引维护成本上升。
- 复合索引只建了右列,查询条件用左列时索引失效。
追问
- 如何判断索引是否被使用?答:用
EXPLAIN QUERY PLAN查看是否走索引;Room 调试日志可打印最终 SQL。 - 覆盖索引是什么?答:查询所需列全部包含在索引中,无需回表;宽表高频小查询可考虑。
07.1.1.8.1-014 复合索引与单列索引如何选择?
一句话结论
多条件共同出现的查询用复合索引,按最左前缀原则排列;单列独立查询才拆成单列索引。
概念解释
复合索引 (a, b, c) 可服务 a、a,b、a,b,c 条件,但不能只服务 b 或 c。列顺序把区分度高、最常出现在条件中的列放左侧;等值条件在前,范围条件在后。
原理流程
索引列顺序 = 等值高频列 → 区分度列 → 范围列
查询按最左前缀匹配
代码或图示
@Entity(indices = [Index(value = ["userId", "status", "createdAt"])])
data class Order(...)
常见误区
- 范围条件列放在等值列前面,后续等值条件用不上索引。
- 把时间戳放第一列,按用户查询时索引全部失效。
追问
- 复合索引能替代单列索引吗?答:若某列总是与前列一起查询,可以;独立按该列查询时仍需单列索引。
- 索引列顺序与 ORDER BY 有关吗?答:有关,排序方向与列顺序一致时索引可直接产出有序结果。
07.1.1.8.1-015 索引在迁移后为什么可能失效?
一句话结论
Migration 脚本只改表结构、漏建或漏改索引时,老库升级后实体上声明的索引并不存在,查询退回全表扫描。
概念解释
Room 为新安装设备生成完整索引;升级路径执行手写 Migration,脚本里必须逐条 CREATE INDEX。列重命名、表重建后旧索引名冲突或残留,也会让新索引未按预期生效。
原理流程
新安装:实体索引直接生效
老升级:Migration DDL → 漏 CREATE INDEX → 索引缺失
代码或图示
val MIGRATION_2_3 = object : Migration(2, 3) {
override fun migrate(db: SupportSQLiteDatabase) {
db.execSQL("ALTER TABLE Order ADD COLUMN status TEXT NOT NULL DEFAULT 'open'")
db.execSQL("CREATE INDEX INDEX_ORDER_USER_TIME ON Order(userId, createdAt)")
}
}
常见误区
- 只核对表列不核对索引,测试在新安装设备上通过,老升级路径出问题。
- 重复创建同名索引导致迁移抛异常。
追问
- 怎么验证老库索引齐全?答:迁移测试执行后查询
sqlite_master或 PRAGMA 索引列表,与实体声明比对。 - AutoMigration 能自动迁移索引吗?答:默认能识别新增索引并生成迁移;复杂变更仍需手动注解或手写脚本,具体行为以版本文档为准(待确认)。
07.1.1.8.1-016 @ColumnInfo(typeAffinity) 对布尔、枚举怎么映射?
一句话结论
布尔可直接映射为 INTEGER(0/1);枚举推荐用 TypeConverter 或存成 TEXT,typeAffinity 只决定 SQLite 侧归类。
概念解释
Room 对 Kotlin/Java 基本类型有内置映射:Boolean → INTEGER。枚举不是基本类型,内置不直接持久化,需要 TypeConverter 转成序号或字符串,或在实体里只存字符串字段再映射回枚举。
原理流程
枚举字段 → TypeConverter 转 String/Int → 存入 TEXT/INTEGER 列
读出时反向转换回枚举
代码或图示
enum class OrderStatus(val code: String) { OPEN("open"), DONE("done");
companion object { fun from(code: String) = entries.first { it.code == code } }
}
class Converters {
@TypeConverter fun statusToText(s: OrderStatus): String = s.code
@TypeConverter fun textToStatus(text: String): OrderStatus = OrderStatus.from(text)
}
常见误区
- 存枚举序号,枚举顺序调整后老数据语义错位。
- 期望
typeAffinity自动完成枚举转换,实际它只改存储归类。
追问
- 枚举存字符串还是序号?答:字符串可读、抗重排,占空间略大;序号紧凑但顺序敏感;按场景权衡。
- 布尔在 SQL 里怎么写条件?答:
WHERE active = 1或active = true,SQLite 接受布尔字面量。
07.1.1.8.1-017 TypeConverter 的工作机制是什么?
一句话结论
TypeConverter 是成对标注 @TypeConverter 的双向转换方法:写入前把复杂类型转成 SQLite 支持的存储类型,读出后反向转换。
概念解释
Room 内置映射覆盖基本类型与字符串,List、Map、自定义枚举、日期范围等类型需要转换器。转换器在数据库类上用 @TypeConverters(Converters::class) 注册,编译期生成的代码在读写时调用对应方法。
原理流程
写入:复杂类型 → 转换器方法 → 原生类型列
读出:原生类型列 → 反向转换器 → 复杂类型实例
代码或图示
class Converters {
@TypeConverter fun fromLong(value: Long): Instant = Instant.ofEpochMilli(value)
@TypeConverter fun toLong(instant: Instant): Long = instant.toEpochMilli()
}
@Database(entities = [Task::class], version = 1)
@TypeConverters(Converters::class)
abstract class AppDatabase : RoomDatabase()
常见误区
- 转换器只写了一个方向,编译期或运行期报缺失转换。
- 转换器里做网络/IO 或抛未捕获异常,读写路径被打断。
追问
- 转换器方法必须是静态或顶层吗?答:普通类实例方法也可,Room 会实例化;无状态转换器用伴生/顶层更轻量。
- 一个类型能注册多个转换器吗?答:同一类型保留一个明确的转换器,重复注册会产生歧义编译错误。
07.1.1.8.1-018 如何用 TypeConverter 存 List/Map/JSON?
一句话结论
在转换器里把 List/Map 序列化为 JSON 字符串存入 TEXT 列,读出时反序列化;注意序列化库依赖与空集合处理。
概念解释
SQLite 没有集合列,集合整体落库需要序列化载体。JSON 字符串可读性好、排查方便;集合元素若后续要独立查询,应拆成子表而不是塞一列 JSON。
原理流程
List<String> → JSON 序列化 → TEXT 列
查询条件:整体包含判断靠应用层,不便于 SQL 过滤
代码或图示
class ListConverters(private val json: Json) {
@TypeConverter fun listToJson(list: List<String>): String =
json.encodeToString(serializer(), list)
@TypeConverter fun jsonToList(raw: String): List<String> =
json.decodeFromString(serializer(), raw)
}
常见误区
- 序列化器在转换器里每次新建,引入多余对象开销。
- 空集合与 null 混淆,读出空 JSON 字符串反序列化失败。
追问
- JSON 列能建索引按元素查询吗?答:SQLite 可用 JSON 函数做提取与索引,但跨版本兼容性与查询复杂度要评估;高频过滤优先拆表。
- 大集合存一列有什么风险?答:单行体积过大,读写与缓存压力上升,列表滑动时性能下降。
07.1.1.8.1-019 TypeConverter 注册在哪里?全局还是实体级?
一句话结论
可在 @Database 上全局注册,也可在单个实体上注册;全局生效于所有实体,实体级只作用于该表。
概念解释
数据库级 @TypeConverters 影响整个工程的实体映射;实体级 @Entity(@TypeConverters(...)) 用于局部特殊类型。多模块共享转换器应放在数据层公共模块,避免各模块重复实现。
原理流程
@Database 注册 → 所有实体复用
@Entity 注册 → 仅当前实体可用
代码或图示
@Entity(@TypeConverters(LocalConverters::class))
data class LocalNote(...)
常见误区
- 同一类型在两处注册了行为不同的转换器,映射结果不确定。
- 转换器类依赖外部注入(如 JSON 组件),而 Room 按无参方式实例化导致缺依赖。
追问
- 转换器能跨模块复用吗?答:把转换器类放公共依赖模块,各数据库类引用;避免业务模块反向依赖数据实现模块。
- 局部转换器与全局冲突时优先级?答:实体级声明优先于数据库级,具体以编译期生成代码为准(待确认)。
07.1.1.8.1-020 TypeConverter 抛异常会发生什么?
一句话结论
转换异常会从读写路径抛出,导致查询/插入失败;转换器必须处理非法数据并返回安全默认值,避免崩溃扩散到界面。
概念解释
历史数据可能因版本演进格式变化(枚举改名、JSON 结构变更),转换器反序列化失败时若直接抛异常,整个 Flow 或 DAO 调用链报错。生产代码应在转换器内捕获解析错误,回退默认值并记录日志。
原理流程
旧格式数据 → 转换器解析失败 → 捕获 → 默认值 + 日志
未捕获:异常沿 Flow/回调上抛
代码或图示
@TypeConverter
fun textToStatus(raw: String): OrderStatus =
runCatching { OrderStatus.from(raw) }.getOrDefault(OrderStatus.OPEN)
常见误区
- 转换器里直接
!!或裸抛,脏数据让首页白屏。 - 把解析异常吞成 null,掩盖数据问题且难以回溯。
追问
- 脏数据如何排查定位?答:转换器记录原始值与堆栈,配合调试库把异常上报;修复后做历史数据扫描脚本。
- 转换器能返回可空结果吗?答:可以,但要与实体可空类型一致,避免空值包装类型不匹配。
07.1.1.8.1-021 @Embedded 嵌入对象如何建表?字段重名怎么处理?
一句话结论
@Embedded 把对象的字段平铺到当前表,子对象属性成为同级列;重名时用 @ColumnInfo 或 prefix 区分列名。
概念解释
嵌入用于聚合一组内聚字段(地址、时间范围、坐标),在表内不产生独立子表。嵌入对象字段与外层字段重名时,Room 编译期报歧义错误,需要显式指定列名前缀或改名。
原理流程
外层字段 + @Embedded 子对象字段 → 平铺为同表列
重名 → prefix 或 name 消歧
代码或图示
@Entity
data class Address(
val city: String,
val street: String
)
@Entity
data class User(
@PrimaryKey val id: Long,
@Embedded(prefix = "addr_") val address: Address
)
常见误区
- 嵌入对象里再嵌对象,层级过深导致列名难维护。
- 嵌入字段重名未处理,编译期直接失败。
追问
- 嵌入对象能在多实体间复用吗?答:可以,复用同一嵌入类;各实体列名前缀按需要设置。
- 嵌入与
@Relation的区别?答:@Embedded同表平铺,@Relation跨表关联,分属两张或多张表。
07.1.1.8.1-022 @Embedded 与嵌套对象的层级限制?
一句话结论
嵌入支持一层主要用法,多层嵌套需要逐层标注并接受列名膨胀;Room 不递归自动展开未标注的复杂对象。
概念解释
嵌套数据想落库就要在每一层显式声明持久化映射,未标注的复杂类型必须靠 TypeConverter。层级深的模型说明表设计过宽,应考虑拆主子表。
原理流程
需要落库的嵌套 → 每层 @Embedded 平铺
不需要落库的复杂类型 → TypeConverter 或忽略
代码或图示
data class TimeRange(
@Embedded val start: TimePoint,
@Embedded val end: TimePoint
)
常见误区
- 一个实体嵌入五六个子对象,表列数几十列,维护与迁移成本失控。
- 期望 Room 自动递归展开嵌套对象。
追问
- 嵌入对象可为空吗?答:嵌入整体可空时,子列可空;读出时子对象整体重建,部分列为空需业务判断。
- 层级深的聚合如何拆?答:按业务边界拆主表、子表,用
@Relation组装,而不是无限平铺。
07.1.1.8.1-023 枚举持久化有哪几种方案?各自代价?
一句话结论
三种方案:存序号、存字符串、独立字典表;字符串可读性与抗重排最好,序号最紧凑,字典表支持动态枚举与多语言文案。
概念解释
序号依赖枚举声明顺序,重排即错位;字符串占空间但直观,版本演进可新增值;字典表把枚举值拆成子表,额外 JOIN 与维护成本,适合枚举需要运营配置的场景。
原理流程
枚举 → 序号(INT) / 字符串(TEXT) / 字典表(FK)
读取时按方案还原枚举实例
代码或图示
// 推荐:字符串 + 回退默认值
@TypeConverter fun statusToText(s: OrderStatus) = s.code
常见误区
- 存序号又随意调整枚举顺序,老数据变成另一个状态。
- 新增枚举值后旧版本客户端不识别,缺少兜底默认值。
追问
- 枚举字段如何加唯一或索引?答:在存储列上建索引;枚举本身不直接出现在 SQL 条件中。
- 多状态组合怎么存?答:位图(位掩码 INTEGER)或标签子表;组合状态频繁变化时子表更清晰。
07.1.1.8.1-024 日期时间在 Room 里推荐存什么类型?
一句话结论
统一存 epoch 毫秒/秒数(Long)或 ISO-8601 字符串;推荐 Long 存 UTC 时间戳,避免时区与格式解析问题。
概念解释
SQLite 没有原生日期类型,字符串排序虽可用但依赖格式一致;Long 时间戳比较、范围查询与排序最简单。展示层再按本地时区格式化,实体层不存时区相关显示值。
原理流程
UI 显示 → 本地时区格式化
持久化:UTC epoch Long,跨时区一致
代码或图示
@Entity
data class Event(
@PrimaryKey val id: Long,
val startEpochMs: Long,
val endEpochMs: Long
)
常见误区
- 存本地时区字符串,跨设备或夏令时切换后比较出错。
- 同时存时间戳与格式化文本,两份数据可能不一致。
追问
- 秒与毫秒怎么选?答:按服务端口径统一;混用会出现千倍偏差,项目内约定一种精度。
- 日期范围查询怎么写?答:
WHERE startEpochMs BETWEEN :from AND :to,走时间戳索引。
07.1.1.8.1-025 一对多为什么不能用实体字段直接持有集合?
一句话结论
SQLite 是关系模型,一张表的行无法在列里直接存多行子记录;集合必须拆子表,通过外键关联后用 @Relation 组装。
概念解释
Room 实体字段映射为单列,List<Child> 不是合法列类型。直接持有集合会被 TypeConverter 整体序列化,丢失按子记录查询、更新、删除的能力。关系建模先拆主子表,DAO 查询时再组装成嵌套结构。
原理流程
主表行 ←外键→ 子表多行
DAO:父实体 + @Relation 子集合 返回数据结构
代码或图示
@Entity data class Author(@PrimaryKey val id: Long, val name: String)
@Entity data class Book(@PrimaryKey val id: Long, val authorId: Long, val title: String)
常见误区
- 在父实体里写
val books: List<Book>当普通字段,被转换器整体 JSON 化。 - 子表没有外键列,关系靠应用层拼接,孤儿数据难以清理。
追问
- 子表删除后父对象如何刷新?答:DAO 返回 Flow,子表变更触发父查询重新发射。
- 一对多关系数据结构怎么定义?答:父类持有
@Relation val books: List<Book>,作为查询结果 POJO。
07.1.1.8.1-026 @Relation 的基本用法与生成的查询?
一句话结论
在结果类字段上标 @Relation,指定 parentColumn 与 entityColumn,Room 编译期为关系生成子查询,把父行对应的子记录集合挂到父对象上。
概念解释
parentColumn 是父表连接列,entityColumn 是子表外键列。Room 通常先查父表,再按父表主键集合批量查子表,在内存中分组组装,避免在 SQL 里直接 JOIN 出笛卡尔积。
原理流程
查父表 → 收集 parentColumn 取值 → 批量查子表 WHERE entityColumn IN (...)
→ 内存分组挂到父对象的 Relation 字段
代码或图示
data class AuthorWithBooks(
@Embedded val author: Author,
@Relation(parentColumn = "id", entityColumn = "authorId")
val books: List<Book>
)
常见误区
- 连接列名与实际外键列不一致,子集合查为空。
- 把
@Relation字段标成可空但查询期望必有数据,语义混淆。
追问
- Relation 能指定子表排序吗?答:子查询排序受 Room 实现约束;需要稳定排序时在结果层排序,或在子表查询注解中处理(具体支持以版本为准,待确认)。
- Relation 字段需要构造参数注入吗?答:结果 POJO 由 Room 生成代码装配,字段可读写即可。
07.1.1.8.1-027 @Relation 与 @Transaction 为什么常一起用?
一句话结论
关系查询由多次查询组成,@Transaction 把父查询与子查询包在一个事务里,保证读到一致快照,避免子查询期间数据被写入导致集合与父行不匹配。
概念解释
不带事务时,父表与子表分属两次独立读取,中途发生并发写入可能让父行对应的子集合处于中间状态。DAO 方法标注 @Transaction 后,Room 在同一数据库事务内执行整套关系查询。
原理流程
BEGIN TRANSACTION
→ 查父表 → 查子表 → 组装
COMMIT
代码或图示
@Transaction
@Query("SELECT * FROM Author")
fun authorsWithBooks(): Flow<List<AuthorWithBooks>>
常见误区
- 只写 Relation 不加事务,多端写入场景出现父子数据短暂不一致。
- 事务方法里执行阻塞重计算,拉长事务持有时间。
追问
- 事务方法能返回 Flow 吗?答:可以;事务在收集/查询执行期间保证一致性,Flow 后续重新发射按新查询处理。
- 嵌套 Relation 也要事务吗?答:多层关系同样建议在 DAO 方法上标注
@Transaction。
07.1.1.8.1-028 @Relation 的 parentColumn/entityColumn 如何对应外键?
一句话结论
parentColumn 对应父表主键或连接列,entityColumn 对应子表外键列;两者值相等才匹配为一对父子记录。
概念解释
Relation 只描述查询时的连接条件,不强制建立数据库外键约束。需要数据库级级联、孤儿约束时,另在子实体上声明 @ForeignKey;两者列保持一致。
原理流程
父行.parentColumn = 子行.entityColumn → 归入同一父对象
代码或图示
@Relation(
parentColumn = "authorId",
entityColumn = "bookId"
)
常见误区
- 把父表业务唯一键当成连接列,而子表外键存的是自增主键,对不上。
- 列名拼写不一致,编译期不报错,运行期子集合为空。
追问
- Relation 连接列必须是主键吗?答:不必须,但通常用主键;非主键连接要确认索引与唯一性。
- 外键列与 Relation 列不一致会怎样?答:关系查询按 Relation 列匹配,外键约束按 FK 列检查,可能出现约束通过但关系组装为空。
07.1.1.8.1-029 多对多关系怎么用 @Junction 建模?
一句话结论
多对多通过中间表(关联实体)连接,@Relation 用 @Junction 指定中间表与两侧连接列,完成双向关联查询。
概念解释
例如学生与课程:student_course 中间表存 studentId 与 courseId。@Junction 声明关联实体及两侧匹配列,Room 生成穿过中间表的子查询。中间表本身要注册为实体。
原理流程
A 表 ← junction.aId 连接 → junction.bId → B 表
Relation @Junction 描述中间表连接路径
代码或图示
@Entity(primaryKeys = ["studentId", "courseId"])
data class Enrollment(val studentId: Long, val courseId: Long)
data class CourseWithStudents(
@Embedded val course: Course,
@Relation(
parentColumn = "courseId",
entityColumn = "studentId",
associateBy = Junction(Enrollment::class,
parentColumn = "courseId", entityColumn = "studentId")
)
val students: List<Student>
)
常见误区
- 中间表实体漏注册到数据库
entities列表。 - Junction 两侧列名写反,查询结果为空或错配。
追问
- 多对多中间表能带额外字段吗?答:能,中间表可存报名时间、状态等附加列,按复合主键管理。
- 多对多与两个一对多等价吗?答:结构上等价;中间表是关系建模的标准落地点。
07.1.1.8.1-030 @Relation 返回 List 时是否会 N+1 查询?
一句话结论
Room 的 Relation 实现按父表批量查子表,通常不是逐条父记录发 SQL 的 N+1;但结果类嵌套层级过深或结果集过大时,内存分组与查询次数仍需评估。
概念解释
典型流程是一次父查询加一次子表批量查询,再在内存分组;比手写循环内逐条查子表要少很多 SQL。真正的 N+1 出现在应用层遍历父列表再逐条调用子 DAO 的写法上。
原理流程
父查询 1 次 → 子表 IN 批量查询 1 次 → 内存分组
反例:for (parent) { childDao.byParent(parent.id) } → N+1
代码或图示
// 正确:Room 批量组装
@Transaction @Query("SELECT * FROM Author")
fun authors(): Flow<List<AuthorWithBooks>>
// 错误:应用层逐条查
fun bad(): List<AuthorWithBooks> =
authors.map { a -> AuthorWithBooks(a, bookDao.byAuthor(a.id)) }
常见误区
- 误以为 Relation 每条父记录查一次子表。
- 大列表 Relation 一次性把全部父子记录读进内存,界面只展示部分却承担全量开销。
追问
- 大集合 Relation 如何优化?答:配合分页只取所需父页;子集合过大时按子表分页或延迟加载。
- 如何确认 SQL 次数?答:打开 Room 查询日志或用数据库探查工具统计语句条数。
07.1.1.8.1-031 嵌套关系(一对多再一对多)如何表达?
一句话结论
在结果 POJO 里层级嵌套 @Relation:父对象持有含子 Relation 的中间结果类,DAO 方法加 @Transaction 保证多层一致。
概念解释
例如部门 → 员工 → 待办事项,需要两层关联。第二层 Relation 挂在中间结果类上,Room 生成对应层级的子查询;层级越深,组装内存与查询次数越高,应控制嵌套深度。
原理流程
DepartmentWithEmployees
└ employees: List<EmployeeWithTodos>
└ todos: List<Todo>
代码或图示
data class EmployeeWithTodos(
@Embedded val employee: Employee,
@Relation(parentColumn = "id", entityColumn = "employeeId")
val todos: List<Todo>
)
data class DeptWithEmps(
@Embedded val dept: Department,
@Relation(parentColumn = "id", entityColumn = "deptId")
val employees: List<EmployeeWithTodos>
)
常见误区
- 嵌套两层以上仍一次性全量加载,内存占用随层级乘法放大。
- 中间结果类漏标
@Relation,第二层集合为空。
追问
- 多层 Relation 性能瓶颈在哪?答:组装阶段内存分组与对象分配;大数量级应改为按需查询或拆界面数据加载。
- 嵌套结果能直接写回数据库吗?答:结果 POJO 不注册为实体;写入分别走各表 DAO。
07.1.1.8.1-032 关系查询的代价:JOIN 与两次查询如何取舍?
一句话结论
SQL JOIN 在数据库侧连接,返回宽行;Relation 拆成父子两次查询再内存组装。单表分页、轻量关联用 JOIN,嵌套集合、避免笛卡尔积用 Relation。
概念解释
JOIN 多表后行数相乘,一对多场景父行被重复复制;Relation 先取父集合再批量取子集合,结果结构天然嵌套。数据量大、只需要部分父记录时,先分页父表再关联子表更可控。
原理流程
JOIN:数据库连接 → 宽结果集(父行重复)
Relation:两次查询 → 内存分组(嵌套结构)
代码或图示
-- JOIN 适合取扁平字段
SELECT a.name, b.title FROM Author a JOIN Book b ON b.authorId = a.id
常见误区
- 一对多用 JOIN 后在应用层去重,重复传输与对象分配浪费。
- 为嵌套结构写大段 JOIN,SQL 难维护且笛卡尔积风险高。
追问
- 什么时候必须 JOIN?答:需要跨表聚合统计、按子表字段过滤父表时,JOIN 或子查询更直接。
- Relation 能做子表过滤吗?答:基础 Relation 条件受限;需要过滤的子集合建议独立 DAO 查询组装。
07.1.1.8.1-033 @Relation 能否带 WHERE 条件过滤子表?
一句话结论
基础 @Relation 只按连接列匹配,不直接支持 WHERE 过滤;需要条件子集合时用自定义 DAO 查询、子查询或结果层过滤。
概念解释
Relation 注解参数围绕连接列与中间表,过滤条件不属于其声明范围。若只取子表某状态记录,常见做法是 DAO 分别查父表与过滤后的子表,在 Repository 组装;或在子表结果类上配合查询条件。
原理流程
方案 A:独立 DAO 按条件查子表 → Repository 按父 ID 分组
方案 B:SQL 子查询过滤父表 → 再 Relation 取全量子集
代码或图示
@Query("SELECT * FROM Book WHERE authorId = :authorId AND status = :status")
fun activeBooks(authorId: Long, status: String): List<Book>
常见误区
- 在
@Relation上加 WHERE 字符串,注解不接受该参数,编译失败。 - 条件过滤下推到子表后仍把全部子记录读入内存再过滤。
追问
- 子表排序与分页能在 Relation 内完成吗?答:基础能力有限;深度需求用独立子表查询配合 Paging。
- 官方对条件 Relation 的支持版本?答:以 Room 版本 release notes 为准(待确认),不要假设存在未文档化参数。
07.1.1.8.1-034 外键约束(@ForeignKey)与级联删除怎么配?
一句话结论
子实体上声明 @ForeignKey 指定父实体与连接列,onDelete 可选 CASCADE 实现父记录删除时子记录级联清除。
概念解释
外键在数据库层保证引用完整性:子表外键值必须存在于父表,或为 NULL。CASCADE 级联删除减少孤儿数据;更新父键时 onUpdate 也可配置级联。外键默认在 SQLite 中可关闭,Room 按配置生成约束。
原理流程
删父行 → 外键触发 ON DELETE CASCADE → 关联子行一并删除
代码或图示
@Entity(
foreignKeys = [ForeignKey(
entity = Author::class,
parentColumns = ["id"],
childColumns = ["authorId"],
onDelete = ForeignKey.CASCADE
)],
indices = [Index(value = ["authorId"])]
)
data class Book(@PrimaryKey val id: Long, val authorId: Long, val title: String)
常见误区
- 加了外键却没给外键列建索引,级联与检查时全表扫描。
- 历史脏数据违反外键约束,建表/迁移时外键启用失败。
追问
- 外键级联删除能被应用层拦截吗?答:约束在数据库侧执行;需要审计/软删除时不用硬级联,改业务层标记删除。
- 外键与 Relation 必须同时配置吗?答:不是;Relation 负责查询组装,FK 负责约束,可按需组合。
07.1.1.8.1-035 实体之间的外键与 @Relation 有什么区别?
一句话结论
外键是数据库层的引用约束与级联规则;@Relation 是查询期把关联记录组装成嵌套对象的装配机制,两者职责不同、可独立存在。
概念解释
FK 影响写入约束、删除/更新行为,由 SQLite 强制执行;Relation 只影响 DAO 返回结构,不改变表约束。项目里常见组合:FK 保证数据完整性,Relation 供界面取嵌套结构。
原理流程
写入路径:FK 校验引用合法性
读取路径:Relation 批量装配嵌套对象
代码或图示
@Entity(foreignKeys = [/* FK */])
data class Book(...)
data class AuthorWithBooks(
@Relation(parentColumn = "id", entityColumn = "authorId")
val books: List<Book>
)
常见误区
- 以为加了 Relation 就有外键约束,孤儿数据照常残留。
- 以为配了外键查询就自动返回嵌套集合,仍需 DAO Relation/组装。
追问
- 只有 FK 没有 Relation,读取怎么做?答:Repository 分别查父表、子表,按外键列分组组装。
- 只有 Relation 没有 FK,风险是什么?答:子表可插入指向不存在父行的记录,需要应用层兜底校验。
07.1.1.8.1-036 DAO 接口或抽象类如何被 Room 识别?
一句话结论
DAO 用 @Dao 标注,在数据库类的 abstract fun xxxDao(): XxxDao 中暴露;Room 编译期为接口/抽象类生成实现代码。
概念解释
@Dao 可以是接口也可以是抽象类:接口由 Room 生成全部方法实现;抽象类可带构造参数与共享辅助方法。数据库类通过抽象方法返回 DAO 实例,Room 按数据库实例持有对应 DAO。
原理流程
@Dao 接口 → 编译期生成 _Impl 实现类
→ RoomDatabase 抽象方法暴露 → 运行期返回单例 DAO
代码或图示
@Dao
interface NoteDao {
@Query("SELECT * FROM Note")
fun all(): Flow<List<Note>>
}
@Database(entities = [Note::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
abstract fun noteDao(): NoteDao
}
常见误区
- DAO 没在数据库类里声明抽象方法,外部拿不到实例。
- 抽象类 DAO 带无参构造之外的参数,Room 无法实例化。
追问
- DAO 能被多个数据库共享吗?答:可以定义公共接口,但每个数据库生成各自实现;实体与表名必须一致。
- DAO 方法可以是 open 普通方法吗?答:注解方法由生成代码实现;普通辅助方法写在抽象类里供复用。
07.1.1.8.1-037 DAO 返回 List 与 Flow<List> 有什么区别?
一句话结论
List<T> 是一次性快照查询;Flow<List<T>> 是可观察查询,相关表数据变更后自动重新发射最新结果。
概念解释
普通返回值在调用时执行一次 SQL 并返回当前快照;Flow 查询在收集期间注册观察者,Room 跟踪查询涉及的表,表写入后触发重新查询。Flow 适合界面数据展示,一次性导出/批量处理用 List。
原理流程
List:执行 SQL → 返回快照 → 结束
Flow:收集 → 注册表观察者 → 表变更 → 重新查询 → 发射新列表
代码或图示
@Query("SELECT * FROM Note WHERE userId = :uid")
fun observeByUser(uid: Long): Flow<List<Note>>
@Query("SELECT * FROM Note")
fun snapshotAll(): List<Note>
常见误区
- 把 Flow 当一次性 List 取第一个值,浪费观察者注册机制。
- 长生命周期收集 Flow 未在合适作用域取消,导致数据库持续被监听。
追问
- Flow 查询在什么调度器执行?答:Room 协程查询在后台线程执行;Flow 上游可在 IO 调度器收集,具体线程模型按 Room 版本与协程集成(待确认)。
- 一次写入会触发哪些 Flow?答:查询涉及的表被标记失效,相关观察查询重新执行;不相关表不受影响。
07.1.1.8.1-038 LiveData 返回类型在 Room 中的作用与限制?
一句话结论
Room 支持返回 LiveData<List<T>>,把数据库观察绑定到 Android 生命周期;新项目推荐用 Flow 配合 liveData 协程构造器或 asLiveData 转换。
概念解释
LiveData 随 Activity/Fragment 生命周期激活与停止观察,避免后台更新界面;Room 为 LiveData 生成观察者实现。限制是 LiveData 面向 Android 架构组件,脱离 Android 层复用性差,协程/Flow 生态下逐步被替代。
原理流程
表变更 → Room 观察者 → LiveData setValue → 活跃观察者收到新值
代码或图示
@Query("SELECT * FROM Note")
fun liveNotes(): LiveData<List<Note>>
// Flow 转 LiveData
fun notesFlow(): Flow<List<Note>> = dao.observeByUser(uid)
val notes: LiveData<List<Note>> = notesFlow().asLiveData()
常见误区
- 在非 Android 模块直接依赖 LiveData,污染数据层纯 Kotlin 代码。
- 以为 LiveData 只在界面可见时执行 SQL,实际观察注册与停止时机需按生命周期理解。
追问
- LiveData 与 Flow 观察语义差异?答:LiveData 黏附最近值并按生命周期分发;Flow 是冷流,收集时才订阅,可组合操作符更丰富。
- 老项目迁移顺序?答:数据层保留 Flow,界面层按需
asLiveData,新页面直接用 Flow + 生命周期收集。
07.1.1.8.1-039 PagingSource 在 Room 分页中的角色?
一句话结论
Room 可直接把 DAO 查询声明为 PagingSource<Key, Value>,配合 Paging 库按页从数据库加载数据,支持增量加载与观察刷新。
概念解释
PagingSource 描述如何从数据源取一页数据与上一页/下一页键;Room 生成的实现按 LIMIT/OFFSET 或键范围查询。数据库作为单一数据源时,Paging 直接挂在 Room DAO 上,远程数据再通过 RemoteMediator 补全。
原理流程
Paging 列表 → 向 PagingSource 请求页 → Room SQL 分页查询
→ 返回 LoadResult.Page → 列表展示
代码或图示
@Query("SELECT * FROM Note ORDER BY createdAt DESC")
fun pagedNotes(): PagingSource<Int, Note>
常见误区
- 分页查询没有稳定排序键,翻页时数据插入/删除导致重复或跳页。
- 把全量 List 交给 Paging 包装,失去分页加载意义。
追问
- 键分页与 OFFSET 分页怎么选?答:稳定时间戳/ID 键分页抗插入扰动;OFFSET 简单但大偏移性能差。
- Room PagingSource 与 RemoteMediator 如何配合?答:本地分页源提供展示数据,RemoteMediator 在边界触发远程拉取并写回本地。
07.1.1.8.1-040 Cursor 返回类型适合什么场景?
一句话结论
DAO 返回 Cursor 适合需要逐行遍历、避免一次性实例化全部对象的大数据量导出或自定义读取场景;常规业务优先用实体/Flow 映射。
概念解释
Cursor 是底层行游标,按列索引取值,不经过 Room 对象映射。返回 Cursor 时调用方负责关闭,内存占用可控但类型安全与可读性差。Room 其他返回类型在生成代码里完成列到对象的映射。
原理流程
SQL 结果集 → Cursor 逐行遍历 → 手动取列 → 关闭游标
代码或图示
@Query("SELECT id, title FROM Note")
fun rawCursor(): Cursor
常见误区
- Cursor 未关闭导致泄漏;在协程/回调里忘记
use管理。 - 用 Cursor 做常规界面列表,放弃 Room 类型映射与观察能力。
追问
- Cursor 与 RawQuery 关系?答:
@RawQuery也可返回 Cursor;两者都是底层读取通道,业务层应封装隔离。 - 大表导出怎么做?答:分批查询 + Cursor/分页读取,逐批写出,避免一次性加载全表。
07.1.1.8.1-041 suspend 与非 suspend DAO 方法的线程模型?
一句话结论
suspend DAO 方法由 Room 在协程上下文执行,可安全在 IO 调度器调用;非 suspend 同步方法默认禁止主线程调用,需自行切线程或用返回 Flow/LiveData 的观察方法。
概念解释
Room 对 suspend 方法挂起执行查询,不阻塞调用线程;同步方法直接执行 SQL,主线程调用默认抛 IllegalStateException。返回 Flow/LiveData 的方法本身不阻塞,观察在后台线程触发。
原理流程
suspend:协程调度器 → 挂起执行 SQL → 恢复返回
同步:调用线程直接执行 → 主线程拦截报错
代码或图示
@Insert
suspend fun insert(note: Note)
@Query("SELECT * FROM Note WHERE id = :id")
suspend fun findById(id: Long): Note?
常见误区
- 在主线程调用同步查询触发崩溃;放开
allowMainThreadQueries后埋下 ANR 隐患。 - suspend 方法仍被包在
runBlocking里阻塞主线程。
追问
- Room 是否自带线程池?答:同步方法在调用线程执行;协程查询由 Room 调度到后台,具体实现版本细节待确认。
- 事务内多个 suspend 方法如何保证原子?答:用
@Transaction标注的 suspend 方法,或数据库withTransaction包裹整段操作。
07.1.1.8.1-042 Flow 查询什么时候重新发射?表数据变更如何感知?
一句话结论
Room 跟踪观察查询涉及的表,这些表发生 INSERT/UPDATE/DELETE 后使查询失效,重新执行 SQL 并向 Flow 发射新结果。
概念解释
观察查询在收集期登记表与查询的失效订阅;写入事务提交后,受影响表对应的观察器被通知。即使是间接关联的子表变更,只要查询 SQL 涉及该表,就会触发重查。
原理流程
写入提交 → 标记受影响表 → 失效相关观察查询
→ 重新执行 SQL → Flow 发射新列表
代码或图示
// 子表写入后,组装作者+书籍的 Flow 也会重查
@Transaction
@Query("SELECT * FROM Author")
fun authorsWithBooks(): Flow<List<AuthorWithBooks>>
常见误区
- 以为只有返回 List 的观察方法才刷新,Relation 结果类同样受表变更驱动。
- 在 Flow 中间链路上做重计算,每次表变更都重复执行。
追问
- 未被查询 SQL 涉及的表变更会触发吗?答:不会;Room 按 SQL 解析出的表名集合匹配。
- 批量写入会触发多次重查吗?答:同一事务内多次写入,提交后统一失效一次;跨事务连续写入则多次发射。
07.1.1.8.1-043 DAO 返回单对象与可空性如何约定?
一句话结论
查询可能无结果时返回可空类型 T?;保证必有结果的查询才返回非空 T,编译期与调用方按可空性区分处理。
概念解释
SELECT ... LIMIT 1 在无匹配行时结果为空,Room 映射为 null;调用方需显式判空。非空返回只适用于主键直查且业务保证记录存在的场景,运行期查不到仍可能得到 null 引发 NPE。
原理流程
SQL 结果集 0 行 → 返回 null
结果集 1 行 → 映射为对象;多行且返回单对象按实现取首行或报错(待确认)
代码或图示
@Query("SELECT * FROM Note WHERE id = :id")
suspend fun findById(id: Long): Note?
@Query("SELECT COUNT(*) FROM Note")
suspend fun count(): Int
常见误区
- 可空查询写成非空返回,界面解引用时崩溃。
- 期望单对象查询在多行时报错,实际行为依赖 Room 实现版本。
追问
- 单对象 Flow 怎么写?答:
Flow<T?>,无结果发射 null;需要默认值在收集层?: 默认。 - 聚合计数返回可空吗?答:
COUNT(*)恒为数值,非空;SUM等在无行时可能为 null。
07.1.1.8.1-044 @Query 编译期校验检查哪些内容?
一句话结论
编译期检查 SQL 语法、列名与实体字段映射、参数绑定是否存在、返回类型能否映射到结果结构;不校验运行期数据与性能。
概念解释
Room 把 SQL 解析后与表结构元数据比对:引用的列、表必须存在;:param 必须能对应方法参数;返回 POJO 的字段要能从结果列填充。校验不通过在编译期报生成代码错误,而不是运行期崩。
原理流程
注解 SQL → 解析 AST → 比对实体列/参数 → 校验结果映射
→ 通过则生成实现,失败则编译报错
代码或图示
@Query("SELECT id, title FROM Note WHERE userId = :uid")
fun byUser(uid: Long): List<Note>
常见误区
- SQL 引用了被删除/改名的列,编译期才暴露,比运行期错误更早但定位需要看生成代码报错。
- 结果 POJO 字段缺列或类型不匹配,报映射错误。
追问
- 编译期能校验 SQL 性能吗?答:不能;执行计划与索引命中要靠
EXPLAIN QUERY PLAN人工评估。 - 原生函数名是否校验?答:SQLite 内置函数通常放行;自定义函数需运行期注册。
07.1.1.8.1-045 @RawQuery 与 @Query 的取舍?
一句话结论
@Query 用注解内静态 SQL,编译期校验;@RawQuery 接受运行期拼接的 SupportSQLiteQuery,灵活但放弃编译期 SQL 校验。
概念解释
动态排序、动态过滤列、运行期拼装表名等场景注解 SQL 写不出来,用 RawQuery 传入构造好的查询。代价是 SQL 正确性、列映射只能运行期保证,需要自行做参数绑定与注入防护。
原理流程
@Query:编译期固定 SQL + 参数绑定
@RawQuery:运行期构造 SupportSQLiteQuery → 执行 → 映射结果
代码或图示
@RawQuery
fun raw(query: SupportSQLiteQuery): List<Note>
// 构造时绑定参数,避免字符串拼接
val args = arrayOf(userId)
val sql = SimpleSQLiteQuery("SELECT * FROM Note WHERE userId = ?", args)
常见误区
- 把用户输入直接拼进 RawQuery 字符串,引入 SQL 注入风险。
- 动态 SQL 列名未白名单校验,既可能出错也存在安全隐患。
追问
- RawQuery 能返回 Flow 观察查询吗?答:可返回观察类型,但表失效识别依赖查询中表名,动态 SQL 解析能力受限(待确认)。
- 动态查询常见场景有哪些?答:多条件筛选、动态排序、报表导出;固定路径仍优先
@Query。
07.1.1.8.1-046 @RawQuery 如何校验 SQL 与绑定参数?
一句话结论
用 SimpleSQLiteQuery 传 SQL 与绑定参数数组,必要时通过 @RawQuery(observedEntities = [...]) 声明观察表;参数一律走 ? 占位绑定,不拼字符串。
概念解释
RawQuery 没有编译期列名校验,应在构造侧做白名单:排序字段、过滤列只允许枚举值;值参数全部占位绑定。observedEntities 告诉 Room 这份动态查询观察哪些实体,使 Flow 能在变更时刷新。
原理流程
列名/排序字段 → 白名单校验
值 → ? 占位 + 绑定数组
observedEntities → 注册表失效订阅
代码或图示
@RawQuery(observedEntities = [Note::class])
fun observeRaw(query: SupportSQLiteQuery): Flow<List<Note>>
val orderBy = if (sortByTime) "createdAt" else "title" // 白名单取值
val q = SimpleSQLiteQuery("SELECT * FROM Note ORDER BY $orderBy", arrayOf())
常见误区
- 漏写
observedEntities,Flow 不随数据变更刷新。 - 值参数拼接进 SQL 字符串,特殊字符破坏语句。
追问
- RawQuery 结果 POJO 映射何时校验?答:运行期按结果列名匹配 POJO 字段,缺列才报错。
- 动态表名可行吗?答:表名不能绑定参数,只能白名单枚举后拼入,并自行承担校验责任。
07.1.1.8.1-047 @Transaction 注解在 DAO 层做什么?
一句话结论
@Transaction 把 DAO 方法包裹在数据库事务中:多条写入要么全部成功要么回滚,观察查询也能读到一致快照。
概念解释
普通单条 SQL 自身原子;批量插入、先查后写、Relation 多层查询需要事务保证一致性。注解方法由 Room 生成事务边界代码,抛异常时回滚整段操作。事务内避免长耗时计算与主线程阻塞。
原理流程
BEGIN → DAO 方法体(多次查询/写入)→ 提交;异常 → 回滚
代码或图示
@Transaction
suspend fun replaceTags(noteId: Long, tags: List<Tag>) {
tagDao.deleteByNote(noteId)
tagDao.insertAll(tags.map { Tag(noteId = noteId, label = it) })
}
常见误区
- 多条写入分散在多个 Repository 方法中,没有同一事务包裹,中途失败留下半成品数据。
- 事务内做网络请求,事务长时间持有连接。
追问
- 事务方法能调用其他 DAO 吗?答:可以,同一数据库事务内执行;跨数据库实例不共享事务。
- Kotlin 协程事务怎么写?答:
@Transaction标注 suspend 方法,或数据库扩展withTransaction { }显式包裹。
07.1.1.8.1-048 嵌套结果 POJO 加 @Embedded 如何承载聚合查询结果?
一句话结论
查询结果用普通 POJO 承载,@Embedded 平铺嵌套字段,@Relation 挂子集合;POJO 不注册为实体,只做查询映射。
概念解释
宽查询结果可拆成几个内聚子对象嵌入结果类,列名通过前缀消歧。聚合统计字段(计数、求和)直接作为 POJO 属性,SQL 别名与属性名对应。
原理流程
SELECT 别名列 → 按名匹配 POJO 属性 → 嵌入对象平铺填充 → Relation 组装集合
代码或图示
data class NoteStats(
@Embedded val meta: NoteMeta,
val count: Int,
val latestAt: Long
)
data class NoteMeta(val title: String, val category: String)
常见误区
- 把结果 POJO 误加
@Entity注册进数据库,多出无用表。 - SQL 别名与 POJO 属性名大小写/下划线不一致,映射为空。
追问
- 结果 POJO 可以用 data class 吗?答:可以,提供可读写构造参数即可;Room 生成代码按属性填充。
- 聚合列可空性怎么定?答:
COUNT非空,SUM/AVG可能为 null,属性标可空。
07.1.1.8.1-049 @Insert 的 OnConflictStrategy 有哪几种?
一句话结论
冲突策略包括 ABORT(中止回滚,默认)、REPLACE(替换冲突行)、IGNORE(跳过冲突行)、ROLLBACK(回滚事务)、FAIL(中止当前操作)。
概念解释
主键或唯一索引冲突时按策略处理:ABORT 抛异常由上层捕获;REPLACE 删除旧行插入新行;IGNORE 保留旧行不插入。策略选择影响级联与旧数据是否保留,不能只看“能不能插入成功”。
原理流程
插入冲突 → 唯一约束检查 → 按 OnConflictStrategy 执行
代码或图示
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun upsert(note: Note)
常见误区
- 默认 ABORT 却未捕获异常,批量插入一条冲突导致整批失败。
- 混淆 ROLLBACK 与 ABORT:ROLLBACK 回滚整个事务,ABORT 只中止当前语句。
追问
- REPLACE 会触发外键级联吗?答:会,删除旧行可能触发子表
CASCADE删除。 - 批量插入部分失败如何定位?答:逐条记录策略或捕获异常后批量重试;IGNORE 静默跳过会掩盖脏数据。
07.1.1.8.1-050 REPLACE 冲突策略为什么可能触发级联删除?
一句话结论
REPLACE 在冲突时先删除旧行再插入新行,删除旧行会触发外键 ON DELETE CASCADE,连带删掉关联子表数据。
概念解释
SQLite 的 REPLACE 语义等价于先 DELETE 冲突旧记录。若旧行被子表外键引用且配置了级联删除,子表记录随之清除;即便新行随后插入,被级联清掉的子数据也不会自动恢复。
原理流程
冲突旧行 → DELETE 旧行 → FK CASCADE 删子表 → INSERT 新行
子表旧数据已丢失
代码或图示
// 高风险:父记录 REPLACE 时子表被级联清空
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun saveAuthor(author: Author)
常见误区
- 用 REPLACE 做“更新”,误以为只覆盖字段,实际经历了删除重建。
- 子表外键级联删除与 REPLACE 叠加,调试时子数据莫名消失。
追问
- 安全的更新怎么做?答:用
@Update按主键更新,或 Upsert(存在则更新字段),避免先删后插。 - 想保留子关联应选什么策略?答:IGNORE 保留旧行,或显式先查再更新;评估级联规则后再决定。
07.1.1.8.1-051 @Update 与 @Delete 按什么匹配记录?
一句话结论
按主键(或复合主键)匹配要更新/删除的行,实体其他字段提供新值;不匹配主键列就无法定位目标记录。
概念解释
@Update 用主键找到行并写入实体携带的非主键字段;@Delete 按主键删除对应行。复合主键按整组字段匹配。方法可传单个实体或集合,返回受影响行数。
原理流程
实体主键 → WHERE 主键 = ? → UPDATE/DELETE 该行
代码或图示
@Update
suspend fun update(note: Note)
@Delete
suspend fun delete(note: Note)
@Query("DELETE FROM Note WHERE id = :id")
suspend fun deleteById(id: Long)
常见误区
- 更新时实体只填了部分字段,未填字段被写成默认值或 null。
- 主键字段被修改后再
@Update,按新主键找不到旧行。
追问
- 只想更新部分字段怎么做?答:用
@Query写UPDATE ... SET col = :value WHERE id = :id,避免整对象覆盖。 - 删除返回值代表什么?答:受影响行数;0 表示主键未匹配到记录。
07.1.1.8.1-052 Upsert 在 Room 中如何实现?版本要求?
一句话结论
Room 提供 @Upsert 注解:存在则按主键更新,不存在则插入;基于 SQLite INSERT ... ON CONFLICT 语义,具体支持版本以 Room 发布说明为准(待确认)。
概念解释
Upsert 把“先查再决定插入还是更新”合并为单条数据库语句,避免并发下先查后写的竞态。实体字段决定更新时写入的列;冲突目标是主键/唯一约束。
原理流程
INSERT 候选行 → 冲突命中 → 更新已有行字段;无冲突 → 插入新行
代码或图示
@Upsert
suspend fun upsert(note: Note)
常见误区
- 以为 Upsert 会合并部分字段,实际更新以实体携带的字段为准。
- 低版本 Room 不支持
@Upsert,需手写INSERT OR REPLACE或先查后写;版本兼容点待确认。
追问
- Upsert 与 REPLACE 区别?答:Upsert 命中冲突走更新路径,不删除旧行,避免 REPLACE 的级联删除副作用。
- 批量 Upsert 性能?答:单语句批量绑定优于逐条先查后写;大批量仍建议事务包裹分批。
07.1.1.8.1-053 @Query 中如何使用 IN 绑定集合参数?
一句话结论
方法参数传集合,SQL 用 (:list) 占位,Room 把集合展开为绑定参数列表;空集合需在 SQL 中单独处理。
概念解释
WHERE id IN (:ids) 编译期把集合参数转为 IN (?, ?, ?) 绑定序列。空集合时 SQL 语义为 IN () 非法,需在 Kotlin 侧短路返回或用条件查询处理。
原理流程
List<Long> ids → 展开为绑定参数 → IN (?, ?, ?)
空集合:短路返回空列表
代码或图示
@Query("SELECT * FROM Note WHERE id IN (:ids)")
suspend fun byIds(ids: List<Long>): List<Note>
suspend fun safeByIds(ids: List<Long>) =
if (ids.isEmpty()) emptyList() else byIds(ids)
常见误区
- 直接传空集合执行 SQL,绑定为空导致语句错误。
- 集合过大时
IN占位参数数量超 SQLite 限制,查询性能下降。
追问
- 集合参数能在 LIKE 中展开吗?答:IN 用于等值匹配;LIKE 多值需拼接或多次查询。
- 大集合分页处理?答:分批查询后合并,避免单条 SQL 绑定参数过多。
07.1.1.8.1-054 原生 SQL 函数在 Room 中可用吗?
一句话结论
SQLite 内置的日期、字符串、聚合、数学函数可直接在 @Query 中使用;自定义函数需在打开数据库前注册到 SQLite 连接。
概念解释
Room 底层是 SQLite,SQL 方言遵循 SQLite 语法:date/time 函数、length/substr/trim、count/sum/avg/max/min 等可用。MySQL 特有函数(如 IFNULL 对应 COALESCE、日期格式化函数)不能照搬。
原理流程
@Query SQL → SQLite 执行内置函数
自定义函数 → SupportSQLiteOpenHelper 注册回调后可用
代码或图示
@Query("SELECT COUNT(*), MAX(createdAt) FROM Note WHERE userId = :uid")
suspend fun summary(uid: Long): NoteSummary
常见误区
- 把 MySQL/PostgreSQL 函数名写进 Room SQL,运行期报无此函数。
- 在 SQL 里做复杂业务计算,本应放到应用层组合,SQL 可读性变差。
追问
- 日期函数与时间戳列如何配合?答:存 epoch 毫秒时比较用数值;存 ISO 文本才用日期函数解析,二选一保持一致。
- 如何注册自定义函数?答:通过打开 Helper 工厂/回调在 SQLite 连接上注册,跨版本 API 细节待确认。
07.1.1.8.1-055 DAO 里能否写默认方法或 Kotlin 扩展?
一句话结论
接口 DAO 可带 Kotlin 默认方法/Java default 方法组合多个注解查询;抽象类 DAO 可写共享辅助方法;扩展函数放在 DAO 接口外做组合封装。
概念解释
DAO 接口内默认方法调用本接口其他注解方法,适合把“查列表 + 转换”封装在数据层;抽象类适合持有公共依赖。跨 DAO 组合逻辑更适合放在 Repository,避免 DAO 之间互相依赖。
原理流程
注解方法(生成实现)+ 默认方法(手写组合)
Repository 调用 DAO 暴露的组合方法
代码或图示
@Dao
interface NoteDao {
@Query("SELECT * FROM Note")
suspend fun all(): List<Note>
suspend fun activeAll(): List<Note> = all().filter { !it.trashed }
}
常见误区
- 默认方法里做线程切换/网络调用,混淆 DAO 数据访问职责。
- DAO 默认方法互相调用形成循环组合,测试难以替换。
追问
- DAO 能注入构造依赖吗?答:抽象类 DAO 可构造注入,但 Room 实例化方式有限;外部依赖更适合由 Repository 持有。
- 扩展函数放哪里?答:公共组合逻辑放数据层 Kotlin 文件,保持 DAO 接口薄。
07.1.1.8.1-056 查询结果映射到 POJO 与映射到实体有什么区别?
一句话结论
映射到实体要求字段与表列完整对应,可直接被 DAO 写入方法使用;映射到普通 POJO 只承载查询投影字段,不可作为可写入实体。
概念解释
实体是表结构镜像,注册在数据库 entities 中;POJO 是结果投影,字段可少于表列、可含聚合别名。把聚合查询结果塞进实体会出现未映射列与可空性不匹配。
原理流程
SELECT 投影列 → 匹配 POJO 属性(可子集)
实体映射 → 期望与表列一致,供 Insert/Update 使用
代码或图示
data class NoteTitleOnly(val id: Long, val title: String) // 投影 POJO
@Query("SELECT id, title FROM Note")
suspend fun titles(): List<NoteTitleOnly>
常见误区
- 用实体接收只选了两列的查询,其余列拿到默认值后误当完整数据写回。
- 把投影 POJO 加
@Entity注册,生成多余表。
追问
- POJO 需要无参构造吗?答:Room 生成代码按构造参数/属性填充,Kotlin data class 构造参数即可;具体映射规则以版本为准。
- 实体能做投影接收吗?答:能编译/运行但语义危险,缺列字段为空默认值,应避免。
07.1.1.8.1-057 如何在 DAO 中做计数、求和等聚合查询?
一句话结论
在 @Query 中写聚合 SQL,结果映射到标量返回值或只含聚合列的 POJO;分组聚合配合 GROUP BY 与结果类。
概念解释
COUNT(*) 返回行数,SUM/AVG/MAX/MIN 返回聚合值;分组查询每行一组,结果类携带分组键与聚合值。聚合列可空性按函数区分:COUNT 非空,SUM/AVG 可能为 null。
原理流程
SELECT 分组键, 聚合(列) → GROUP BY 分组键
→ 映射为 POJO 列表
代码或图示
data class CategoryCount(val category: String, val count: Int)
@Query("SELECT category, COUNT(*) AS count FROM Note GROUP BY category")
suspend fun countByCategory(): List<CategoryCount>
常见误区
- 聚合返回值标非空,但
SUM无行时为 null 导致 NPE。 - 分组列与 SELECT 列不一致,结果语义错乱。
追问
- 聚合能返回 Flow 观察吗?答:可以,表变更后聚合查询重新发射;注意大表每次重算成本。
- 条件聚合怎么写?答:
COUNT(CASE WHEN ... THEN 1 END)或SUM(CASE WHEN ... THEN 1 ELSE 0 END)。
07.1.1.8.1-058 不使用 Paging 库时分页查询怎么写?
一句话结论
用 LIMIT :pageSize OFFSET :offset 或键范围 WHERE id > :after LIMIT :pageSize,DAO 返回当前页列表;排序必须稳定。
概念解释
OFFSET 分页简单但大偏移要跳过大量行;键分页用上一页最后一条的 ID/时间戳作为条件,性能更稳。未引入 Paging 库时,Repository 维护页码或游标,处理刷新与追加加载。
原理流程
OFFSET:跳过 offset 行取 pageSize 行
键分页:WHERE key > lastKey ORDER BY key LIMIT pageSize
代码或图示
@Query("SELECT * FROM Note ORDER BY createdAt DESC, id DESC LIMIT :size OFFSET :offset")
suspend fun page(offset: Int, size: Int): List<Note>
@Query("SELECT * FROM Note WHERE createdAt < :before ORDER BY createdAt DESC LIMIT :size")
suspend fun pageAfter(before: Long, size: Int): List<Note>
常见误区
- 分页期间数据增删,OFFSET 页出现重复或漏行。
- 排序键不唯一(同时间戳),翻页边界不稳定。
追问
- 页缓存与刷新怎么配合?答:首页刷新重查第一页,追加加载下一页;本地数据库 + 网络同步时注意覆盖顺序。
- 什么时候引入 Paging 库?答:列表场景需要加载状态、分隔符、远程 mediator 时,迁移到 PagingSource 更完整。
07.1.1.8.1-059 @Query 的 :param 与 :paramList 绑定规则?
一句话结论
单值参数用 :param 绑定;集合参数用 (:paramList) 展开为 IN 列表;参数名与方法参数名一一对应,编译期检查存在性。
概念解释
Room 把 :name 解析为方法参数引用,类型匹配列亲和性。集合参数语法上要加括号 (:list),Room 展开成占位符序列。参数不能用字符串拼接替代绑定。
原理流程
:param → 单绑定值
:paramList → 集合展开 IN (?, ?, ?)
代码或图示
@Query("SELECT * FROM Note WHERE userId = :uid AND status IN (:statuses)")
suspend fun filter(uid: Long, statuses: List<String>): List<Note>
常见误区
- 集合参数漏写括号,SQL 语法错误。
- 参数名拼写不一致,编译期报无法解析参数。
追问
- 命名参数与位置占位符混用?答:注解 SQL 以命名绑定为准;RawQuery 用
?位置绑定。 - 可空参数如何绑定?答:可空值绑定为 NULL,SQL 条件需用
IS :param或IS NULL兼容写法。
07.1.1.8.1-060 数据库版本号如何确定?改了实体但没升版本会怎样?
一句话结论
@Database(version = N) 标识当前表结构版本;实体结构变更后必须升版本并提供迁移,否则老库打开时版本不匹配且无迁移路径,触发崩溃或破坏性重建。
概念解释
Room 打开数据库时比对库内版本与代码版本:一致直接打开;更高版本(回退)或更低版本但缺 Migration 走兜底策略。只改实体不升版本,新装设备按新结构建表,老库仍是旧结构,查询新列失败。
原理流程
打开 → 读 PRAGMA user_version → 与 version 比对
→ 有 Migration 链则升级;无则按 fallback 策略处理
代码或图示
@Database(entities = [Note::class], version = 2)
abstract class AppDatabase : RoomDatabase()
常见误区
- 加了列/索引却忘升版本,老用户升级后报“no such column”。
- 版本号倒退:代码版本低于已安装库版本,缺少降级处理。
追问
- 版本号只能递增吗?答:线上发布后只能递增;降级属于回滚场景,需专门策略。
- 如何确认结构变更需要升版本?答:实体字段、索引、外键、嵌入/关系映射影响表结构的改动都算。
07.1.1.8.1-061 Migration 类如何编写与注册?
一句话结论
继承 Migration(oldVersion, newVersion),在 migrate(db) 里执行 DDL;在 databaseBuilder 上用 addMigrations(...) 注册。
概念解释
Migration 脚本从旧版本表结构升级到新版本:加列、加索引、建表、回填数据。脚本只做结构与数据迁移,不调用业务层代码。注册后 Room 按库内版本顺序选择对应 Migration 链。
原理流程
Migration(1, 2) { db.execSQL(...) }
builder.addMigrations(MIGRATION_1_2)
代码或图示
val MIGRATION_1_2 = object : Migration(1, 2) {
override fun migrate(db: SupportSQLiteDatabase) {
db.execSQL("ALTER TABLE Note ADD COLUMN color TEXT NOT NULL DEFAULT ''")
}
}
Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
.addMigrations(MIGRATION_1_2)
.build()
常见误区
- 迁移脚本只加列不加索引/默认值,老数据新列行为不确定。
- 脚本引用业务类做数据转换,升级阶段业务依赖未就绪导致失败。
追问
- 迁移在什么线程执行?答:打开数据库期间执行,通常阻塞首次打开;重迁移需评估启动耗时。
- 脚本失败怎么回滚?答:SQLite DDL 部分语句隐式提交,跨脚本失败需整体设计补偿;详细事务行为按 SQLite 版本确认(待确认)。
07.1.1.8.1-062 Migration 链 MIGRATION_1_2、MIGRATION_2_3 如何衔接?
一句话结论
每个 Migration 负责相邻版本一跳,Room 从库内版本沿链逐级执行到当前版本;缺中间跳就需要补对应 Migration 或走兜底。
概念解释
版本 1 用户升级到 3,依次执行 1→2、2→3;脚本之间表结构状态衔接,2 的脚本不能假设 3 的列已存在。提供完整链条比写一个大跨度迁移更易测试与回滚定位。
原理流程
user_version=1 → MIGRATION_1_2 → 结构 2 → MIGRATION_2_3 → 结构 3
代码或图示
.addMigrations(MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4)
常见误区
- 只写最新到当前的迁移,跳过中间版本,老版本用户无路径可升。
- 后续脚本直接引用前一脚本尚未创建的列。
追问
- 可以写 1→3 大跨度迁移吗?答:可以补全链路或提供大跨度脚本;但要覆盖所有中间状态,测试矩阵更重。
- 多个 Migration 执行顺序如何保证?答:Room 按库内版本到目标版本选择相邻跳,注册顺序不决定执行顺序。
07.1.1.8.1-063 AutoMigration 与手写 Migration 的取舍?
一句话结论
简单结构变更(加列、加表、加索引)优先 AutoMigration 由 Room 生成脚本;改名、删列、复杂回填用手写 Migration 或两者结合。
概念解释
AutoMigration 对比新旧 schema JSON 自动生成 DDL,减少漏写脚本;复杂语义变更(列重命名而非删除新增、数据转换)需要注解提示或手写脚本。生成结果仍需迁移测试验证。
原理流程
新旧 schema JSON diff → AutoMigration 生成 DDL
语义歧义 → @RenameColumn 等注解提示 / 手写 Migration
代码或图示
@Database(
entities = [Note::class],
version = 3,
autoMigrations = [
AutoMigration(from = 2, to = 3)
]
)
abstract class AppDatabase : RoomDatabase()
常见误区
- 把删列理解成改名,AutoMigration 按删除+新增处理,历史数据丢失。
- 未开
exportSchema,AutoMigration 缺少 schema 对比依据。
追问
- AutoMigration 支持哪些变更?答:建表、删表、加列、加索引等常规 diff;受限场景以官方文档为准(待确认)。
- 混合使用怎么配置?答:同一版本跳可挂 AutoMigration,复杂部分手写 Migration,避免重复注册同一跳。
07.1.1.8.1-064 AutoMigration 的 @DeleteColumn/@RenameColumn 注解怎么用?
一句话结论
@RenameColumn 告诉 AutoMigration 旧列改名为新列而非删除新增;@DeleteColumn 标记被移除的列,辅助 diff 正确生成脚本。
概念解释
列改名在 schema diff 里看起来像“删旧列 + 加新列”,不加注解会按重建处理导致数据丢失。@RenameColumn 指定 tableName、fromColumnName、toColumnName;@DeleteColumn 标记删除列并在 AutoMigration 注解内引用。
原理流程
diff 检测到旧列消失、新列出现
→ @RenameColumn 提示 ALTER RENAME;否则视为删除+新增
代码或图示
@AutoMigration(
from = 3, to = 4,
spec = AppDatabase.RenameNick::class
)
interface RenameNick {
@RenameColumn(tableName = "User",
fromColumnName = "nick", toColumnName = "nickname")
val rename: Unit
}
常见误区
- 改名漏标注解,老用户该列数据被清空。
- 注解表名/列名与实体不一致,AutoMigration 生成失败。
追问
- 表改名怎么处理?答:
@RenameTable类似机制;具体注解名与参数以 Room 版本文档为准(待确认)。 - AutoMigration 失败如何排查?答:查看生成的迁移脚本与 schema JSON diff,对照实体变更定位歧义点。
07.1.1.8.1-065 fallbackToDestructiveMigration 各重载有什么区别?
一句话结论
兜底策略在找不到迁移路径时销毁重建数据库:无参清空全库;按版本区间重载只在版本落在指定区间时破坏性重建;生产环境默认不应开启。
概念解释
fallbackToDestructiveMigration() 对所有缺迁移路径生效;fallbackToDestructiveMigrationFrom(vararg versions) 只从指定旧版本重建;fallbackToDestructiveMigrationOnDowngrade() 仅降级时重建。重建后本地数据全部丢失。
原理流程
缺 Migration 路径 → 命中兜底策略 → DROP 全部表 → 按当前版本重建
代码或图示
.builder(...)
.fallbackToDestructiveMigrationFrom(1, 2) // 仅 1、2 版本兜底重建
.build()
常见误区
- 生产包开启无参兜底,老用户升级即清空本地缓存/草稿数据。
- 把兜底当成“补迁移”的替代方案,长期不写正式迁移脚本。
追问
- 破坏性重建会触发数据库回调吗?答:会走创建回调;备份恢复逻辑需在重建后重新初始化。
- 离线草稿能接受重建吗?答:未同步数据会丢失;涉及用户数据的表应走正式 Migration。
07.1.1.8.1-066 exportSchema 与 schema JSON 文件有什么用?
一句话结论
exportSchema = true 让 Room 在编译期导出每版数据库结构 JSON,供迁移测试、AutoMigration diff 与结构审查使用。
概念解释
schema JSON 记录表、列、索引、外键、版本等元数据;迁移测试对比升级前后结构与目标 schema JSON 是否一致。AutoMigration 也依赖历史 schema 文件做版本间 diff。导出目录通过注解处理器配置指定。
原理流程
编译期 → 生成 schemas/<version>.json
→ 迁移测试读取 JSON 比对结构
代码或图示
@Database(entities = [Note::class], version = 2, exportSchema = true)
abstract class AppDatabase : RoomDatabase()
常见误区
- 关闭 exportSchema,AutoMigration 与结构比对失去依据。
- schema JSON 被误当成运行期资源,实际是编译产物与测试基线。
追问
- schema 文件要纳入版本管理吗?答:通常提交到仓库供测试与 diff;具体目录约定按工程配置。
- 改结构后旧 JSON 会被覆盖吗?答:按版本号分文件保存,历史版本 JSON 保留。
07.1.1.8.1-067 迁移失败(异常/版本缺失)时 Room 的行为?
一句话结论
Migration 抛异常会中断打开并向上抛出;版本缺失且未配兜底策略时打开失败;配了破坏性兜底则重建数据库。
概念解释
迁移脚本执行 DDL/回填失败,事务中止,数据库停在旧结构状态;未注册对应 Migration 且无 fallback,Room 抛 “A migration couldn't be found” 类异常。线上表现为首次打开崩溃或数据重建,需在发布前用迁移测试覆盖。
原理流程
打开 → 找 Migration → 执行 → 异常/缺失
→ 抛异常;有兜底 → 销毁重建
代码或图示
常见错误:IllegalStateException: Migration didn't properly handle ...
或: Cannot find migration path from version X to Y
常见误区
- 只在新安装设备测试,遗漏老版本升级路径。
- 迁移异常被兜底重建掩盖,线上数据静默丢失。
追问
- 如何捕获打开失败?答:数据库单例构建处捕获异常,记录堆栈;不可重建的用户数据走提示与恢复流程。
- 迁移能重试吗?答:失败后下次打开仍从旧版本重跑脚本,脚本必须幂等。
07.1.1.8.1-068 迁移中常见的 DDL 限制有哪些?
一句话结论
SQLite 不直接支持改列类型、重命名列外的多数结构调整;改列约束/类型通常走“建新表 → 拷贝数据 → 删旧表 → 改名”的重建流程。
概念解释
ALTER TABLE 能力有限:加列、重命名表/列、加部分索引可行;删列、改列类型、改非空约束、调整列顺序需重建表。回填数据在新表上完成后再切换,避免长时间锁表。
原理流程
1. 建新表(新结构)
2. INSERT INTO 新表 SELECT 转换后数据 FROM 旧表
3. DROP 旧表 → ALTER 新表 RENAME 旧表名
代码或图示
db.execSQL("CREATE TABLE Note_new (id INTEGER PRIMARY KEY, title TEXT NOT NULL DEFAULT '')")
db.execSQL("INSERT INTO Note_new(id, title) SELECT id, COALESCE(title, '') FROM Note")
db.execSQL("DROP TABLE Note")
db.execSQL("ALTER TABLE Note_new RENAME TO Note")
常见误区
- 试图
ALTER TABLE ... MODIFY COLUMN,SQLite 不支持该语法。 - 重建表时漏复制索引、外键与触发器。
追问
- 大表重建耗时如何控制?答:分批拷贝、评估迁移窗口;必要时后台分批回填,避免首启长时间阻塞。
- 删列在高版本 SQLite 支持吗?答:新版 SQLite 支持 DROP COLUMN 部分场景,Room 脚本是否封装以版本为准(待确认)。
07.1.1.8.1-069 如何在测试中验证迁移正确性?
一句话结论
用 Room 迁移测试工具:构造旧版本数据库、执行 Migration 链、断言升级后结构与当前 schema JSON 一致、关键数据保留。
概念解释
测试从导出的旧 schema 建库,插入样本数据,跑迁移到最新版本,再校验表结构、索引、外键与数据内容。AutoMigration 与手写脚本都应覆盖;缺迁移路径场景也需测试兜底行为是否符合预期。
原理流程
旧 schema 建库 → 插样本 → runMigrations → 比对 schema JSON + 断言数据
代码或图示
@get:Rule val helper = MigrationTestHelper(
instrumentation = this,
databaseClass = AppDatabase::class.java
)
@Test fun migrate1To2() {
helper.createDatabase("app.db", 1).use { /* 插入旧数据 */ }
helper.runMigrationsAndValidate("app.db", 1, 2, MIGRATION_1_2)
}
常见误区
- 只验证能打开,不核对数据是否保留、索引是否齐全。
- 迁移测试依赖真机/模拟器环境,未纳入 CI 定期运行。
追问
- 测试需要 schema JSON 吗?答:需要,
exportSchema导出的历史版本 JSON 是结构比对基线。 - 降级迁移怎么测?答:按兜底策略场景建库验证;正式降级路径如有脚本同样补测试。
07.1.1.8.1-070 预填充数据库怎么用?
一句话结论
createFromAsset 或 createFromFile 在首次建库时从打包好的只读数据库文件复制初始化数据,适合内置字典、离线基础数据。
概念解释
预填充文件是一个已按目标版本建好的 SQLite 数据库;首次打开时 Room 把它复制到应用数据库目录。预填充库版本必须与代码版本匹配,否则仍需 Migration 衔接;后续数据变更走正常迁移流程。
原理流程
首次打开 → 目标库不存在 → 复制 asset/file 预填充库 → 按版本校验 → 打开读写
代码或图示
Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
.createFromAsset("database/prefilled.db")
.build()
常见误区
- 预填充库版本低于代码版本且未配迁移,首启即走兜底或报错。
- 把需要随版本更新的业务数据打进 asset,包体膨胀且更新不及时。
追问
- 预填充库能加密吗?答:可以配合加密工厂;复制与密钥初始化顺序需验证。
- 预填充数据后续怎么刷新?答:作为本地初始数据,运行期由同步任务更新;版本升级随 Migration 调整结构。
07.1.1.8.1-071 RoomDatabase 单例如何构建?为什么要全局复用?
一句话结论
数据库实例持有连接、配置与 DAO 工厂,应在进程内构建一次并复用;重复 builder 会产生独立数据库连接与资源开销。
概念解释
Room.databaseBuilder 构建的 RoomDatabase 是重对象:打开文件、初始化 Helper、注册观察者。通常由 DI 容器或 Application 级单例持有,DAO 从同一实例获取。多进程场景下每个进程各自持有一份实例,文件级锁协调写入。
原理流程
Application/DI 初始化 → 构建数据库单例 → 各 Repository 取 DAO
避免:每个页面 new 一次 builder
代码或图示
@Volatile private var instance: AppDatabase? = null
fun get(context: Context): AppDatabase =
instance ?: synchronized(this) {
instance ?: Room.databaseBuilder(
context.applicationContext, AppDatabase::class.java, "app.db"
).build().also { instance = it }
}
常见误区
- 传 Activity Context 构建数据库,导致上下文泄漏;应使用
applicationContext。 - 单例未加同步,并发首启创建多个实例。
追问
- 数据库实例能在进程销毁后保留吗?答:进程重建后重新构建实例,内存中的 Flow 状态不保留。
- 测试如何替换数据库?答:DI 注入内存数据库
Room.inMemoryDatabaseBuilder,测试结束关闭。
07.1.1.8.1-072 databaseBuilder 的 openHelperFactory 与 Callback 有什么用?
一句话结论
openHelperFactory 替换底层打开工厂(加密等场景);Callback 在数据库首次创建、升级、打开时回调,用于初始化与数据校验。
概念解释
Factory 决定如何创建 SupportSQLiteOpenHelper,SQLCipher 等加密实现通过自定义工厂接入。Callback.onCreate/onOpen/onUpgrade 给应用层留钩子:首次创建后写入初始数据、打开后做一致性检查、升级后补数据。
原理流程
Builder → Factory 创建 Helper → 打开流程触发 Callback 回调
代码或图示
.builder(...)
.addCallback(object : RoomDatabase.Callback() {
override fun onCreate(db: SupportSQLiteDatabase) { /* 初始数据 */ }
override fun onOpen(db: SupportSQLiteDatabase) { /* 校验/日志 */ }
})
.build()
常见误区
- 在
onCreate里访问 DAO/Repository,数据库尚未完全就绪;应直接执行 SQL 或延后初始化。 - 把业务初始化放进
onOpen且每次打开都执行重复写操作。
追问
- Callback 与 Migration 执行顺序?答:
onUpgrade在迁移流程中触发;onCreate仅首次建库;具体时序以 Room 实现为准(待确认)。 - Factory 与预填充能否叠加?答:可以,加密工厂配合预填充文件需保证文件已用对应加密方式处理。
07.1.1.8.1-073 预填充数据库升级后如何与迁移衔接?
一句话结论
预填充文件本身要有明确版本号;首启时 Room 比对该版本与代码版本,按 Migration 链升级,缺路径同样走兜底策略。
概念解释
asset 里的预填充库不是“免迁移”:它是某个历史版本结构的快照。代码版本高于文件版本时,复制后执行迁移链;文件版本低于最低支持版本时,需补迁移或重新生成匹配版本的预填充文件。
原理流程
复制预填充库 → 读取其 user_version
→ 低于当前版本:执行 Migration 链 → 打开读写
代码或图示
.createFromAsset("database/prefilled_v1.db")
.addMigrations(MIGRATION_1_2, MIGRATION_2_3)
常见误区
- 预填充文件版本长期停留在旧版,升级链越拉越长。
- 更换 asset 文件后未同步版本号与迁移脚本,首启结构校验失败。
追问
- 预填充库结构如何检查?答:用 SQLite 工具打开核对表、列、索引与版本号,再打包进 asset。
- 能否每次发版重打预填充文件?答:适合基础字典类数据;业务数据不应靠 asset 下发。
07.1.1.8.1-074 SQLCipher 加密如何接入 Room?
一句话结论
通过自定义 SupportSQLiteOpenHelper.Factory 接入 SQLCipher,在打开数据库时提供密钥,底层页面落盘为加密数据库文件。
概念解释
Room 不内置加密;加密方案在 Helper 工厂层替换 SQLite 打开实现。密钥来源(Keystore 派生、用户口令)与数据库文件分离管理;接入后 SQL 语句与 DAO 代码基本不变,差异在打开工厂与密钥生命周期。
原理流程
构建加密 Factory → 提供密钥 → 打开加密数据库
→ Room DAO 照常读写,磁盘文件为密文
代码或图示
// 具体工厂类与密钥 API 以 SQLCipher Android 依赖版本为准(待确认)
Room.databaseBuilder(context, AppDatabase::class.java, "secure.db")
.openHelperFactory(cipherFactory)
.build()
常见误区
- 密钥硬编码在代码里,反编译即可提取;密钥应经 Keystore 派生或用户口令派生。
- 加密库版本与 ABI 不匹配,打包后部分设备加载失败。
追问
- 加密对查询性能影响?答:加解密在页面读写层产生开销,大批量读写需压测;索引仍在加密库内生效。
- 换密钥/口令怎么处理?答:需要重加密流程,SQLCipher 提供密钥重设能力,具体 API 按依赖版本确认。
07.1.1.8.1-075 加密数据库与备份、迁移有哪些注意事项?
一句话结论
备份必须在解密后或随密钥一起保护;迁移脚本在加密库内照常执行,但密钥丢失则数据不可恢复;跨设备恢复要同步密钥派生材料。
概念解释
数据库文件密文脱离密钥无意义;系统备份若包含数据库文件,必须确保密钥不被一并明文备份。迁移 DDL 在加密连接内执行,与明文库流程一致;导出明文备份需在受控环境完成并及时清理临时文件。
原理流程
加密库 → 备份文件(密文)+ 密钥材料(独立保护)
迁移:加密连接内执行 DDL
代码或图示
加密库文件(密文) ←→ 密钥材料(独立托管)
迁移 DDL 在加密连接内执行;导出明文需受控环境并清理临时文件
常见误区
- 把数据库文件与密钥同目录打包,加密形同虚设。
- 迁移脚本导出明文到外部存储,未按分区存储与加密要求清理。
追问
- 卸载重装后加密数据能恢复吗?答:密钥派生材料若丢失则无法解密;可恢复性取决于密钥托管设计。
- 迁移测试在加密库上怎么做?答:测试环境用固定测试密钥,验证结构与数据保留。
07.1.1.8.1-076 Room 与多进程:并发写有什么风险?
一句话结论
多进程同时打开同一数据库时,SQLite 文件锁协调并发访问,但仍可能出现锁等待、写入竞争与连接状态不一致;通常建议数据库只在主进程访问。
概念解释
SQLite 支持多进程文件级锁,但 Room 实例与观察者按进程隔离。跨进程同时写入可能触发 SQLITE_BUSY;部分缓存、连接池状态不跨进程共享。独立进程(如推送、下载)需要数据时,优先走主进程暴露的接口或 ContentProvider/IPC,而不是各自直开库。
原理流程
进程 A 打开库 ← 文件锁 → 进程 B 打开库
并发写:锁竞争 → BUSY 等待/报错
代码或图示
进程 A ──文件锁── SQLite 文件 ──文件锁── 进程 B
写操作串行排队;跨进程变更需 IPC 通知,Room 观察者不跨进程
常见误区
- 多进程各自构建数据库实例,写入顺序与失效通知互不可见。
- 把大表数据库放在子进程直连,主界面观察不到子进程写入的变更。
追问
- 必须多进程访问怎么办?答:单写者模型,所有写操作收敛到一个进程;读可按需多进程,或用 IPC 同步变更。
- 多进程下 Room 观察者能跨进程通知吗?答:不能直接;变更需通过广播/事件总线等机制跨进程分发。
07.1.1.8.1-077 主线程查询如何被拦截?allowMainThreadQueries 的代价是什么?
一句话结论
Room 默认检测主线程同步访问并抛异常;allowMainThreadQueries() 关闭拦截,代价是查询阻塞主线程,直接威胁界面流畅度与 ANR。
概念解释
默认拦截防止开发者在 UI 线程跑 SQL;放开后 Room 不再检查,但磁盘 IO 与查询耗时仍在调用线程。少量配置表读取可能侥幸不卡,列表查询、迁移期打开数据库在主线程都会造成掉帧甚至 ANR。
原理流程
同步方法执行 → 检测调用线程为主线程 → 默认抛异常
allowMainThreadQueries:跳过检测,直接在主线程执行 SQL
代码或图示
// 不推荐:仅用于排查遗留问题,不应进入生产
.builder(...).allowMainThreadQueries().build()
常见误区
- 用放开主线程限制解决“崩溃”,而不是把查询移到协程/后台线程。
- 以为 Room 会自动切线程,同步方法仍在调用线程执行。
追问
- Flow/LiveData 观察方法受主线程限制吗?答:观察方法不在主线程执行 SQL;收集线程与查询线程按协程/组件机制管理。
- 历史代码怎么整改?答:DAO 方法改 suspend 或返回 Flow,Repository 在 IO 调度器调用,逐步移除该开关。
07.1.1.8.1-078 Room 底层连接池与事务隔离级别是怎样的?
一句话结论
Room 底层基于 SQLite 连接管理,事务遵循 SQLite 的隔离语义(默认串行化读写、读不阻塞写的 WAL 模式除外);连接复用由 Room/SQLite 层管理,应用层不直接控制连接池参数。
概念解释
SQLite 事务隔离与文件锁、日志模式(journal/WAL)相关:WAL 模式下读与写可并发,写仍串行。Room 不暴露独立的连接池大小配置;多连接场景下的事务一致性需按 SQLite 文档理解,版本细节待确认。
原理流程
事务开始 → 取连接 → 读写 → 提交/回滚
WAL:读快照不阻塞写;写操作串行排队
代码或图示
BEGIN → 取连接 → 读写 → COMMIT/ROLLBACK
WAL:读快照与写并发;写操作串行;BUSY 需重试
常见误区
- 套用 MySQL 的隔离级别概念(RR/RC)解释 SQLite,语义并不一一对应。
- 长事务持有连接,其他写入排队等待。
追问
- WAL 模式如何开启?答:通过数据库配置/PRAGMA 设置;Room 默认行为与可配置项按版本确认(待确认)。
- 读写冲突怎么表现?答:
SQLITE_BUSY类错误,需重试或缩短事务。
07.1.1.8.1-079 大表迁移或数据回填如何控制耗时?
一句话结论
把重迁移拆成结构变更与数据回填两步:首启只做必要 DDL,大批量数据转换分批在后台任务中完成,避免首启长时间阻塞。
概念解释
迁移脚本在数据库打开阶段执行,长事务与全表扫描会拉长首启。可行做法:先加列/建表并给默认值,历史数据由 WorkManager/后台协程分批回填;回填进度落库标记,中断后可续跑。
原理流程
首启 Migration:轻量 DDL + 默认值
后台任务:分批 SELECT 范围 → 转换 → UPDATE → 记录游标
代码或图示
// 迁移脚本只加列
db.execSQL("ALTER TABLE Note ADD COLUMN searchText TEXT NOT NULL DEFAULT ''")
// 后台分批回填
@Query("SELECT * FROM Note WHERE id > :cursor ORDER BY id LIMIT :size")
suspend fun page(cursor: Long, size: Int): List<Note>
常见误区
- 在迁移脚本里全表遍历做字符串转换,老设备首启 ANR。
- 回填任务不可中断重试,杀进程后从头再来。
追问
- 回填期间旧格式数据怎么展示?答:查询兼容新旧格式,未回填记录按旧逻辑读取,回填后切新逻辑。
- 如何监控回填进度?答:记录最后处理 ID 与批次计数,配合日志/上报观察完成率。
07.1.1.8.1-080 实体字段改名后,schema diff 如何识别为重命名还是删除加新增?
一句话结论
纯 schema diff 无法语义判断改名:旧列消失、新列出现默认按删除+新增处理;必须用 AutoMigration 重命名注解或手写 Migration 保留数据。
概念解释
结构对比只看列集合,不理解业务语义。没有注解提示时,自动迁移把旧列数据丢弃、新列置默认值。手写脚本则用 ALTER TABLE RENAME COLUMN 或重建表方式完成改名,历史数据保留。
原理流程
diff:旧列 A 移除 + 新列 B 出现
注解/手写:RENAME A → B,数据随列迁移
代码或图示
// 手写迁移:重命名列(SQLite 支持 RENAME COLUMN 的版本前提下)
db.execSQL("ALTER TABLE Note RENAME COLUMN oldTitle TO title")
常见误区
- 以为编译期 Room 能识别“这两个字段是同一个东西”。
- 改名后只改实体属性名,迁移脚本按新列建表,老用户数据丢失。
追问
- 跨大版本改名怎么测试?答:迁移测试断言旧列数据出现在新列中,而不仅是表结构存在。
- 重建表方式改名注意什么?答:索引、外键、默认值随新表重建,拷贝时做类型转换。
07.1.1.8.1-081 Room 生成代码放在哪?KSP 与 kapt 产物有什么差异?
一句话结论
Room 在注解处理期生成 DAO 实现、数据库子类与映射代码;KSP 与 kapt 都可作为处理入口,KSP 编译更快、产物形态按 KSP 生成规则组织,具体目录与类名以构建产物为准(待确认)。
概念解释
kapt 走 Java 注解处理,KSP 是 Kotlin 原生处理;Room 对两者都提供支持。生成类通常位于构建目录的 generated source 下,类名带 _Impl 等后缀。切换 KSP/kapt 时需核对插件版本与 Room 兼容矩阵。
原理流程
注解处理 → 生成 DAO 实现/DB 子类 → 编译进 APK
kapt:经 Java 处理通道;KSP:Kotlin 原生通道
代码或图示
注解处理期生成:XxxDao_Impl、AppDatabase_Impl
kapt:Java 注解处理通道;KSP:Kotlin 原生通道(版本兼容矩阵待确认)
常见误区
- 同时启用 kapt 与 KSP 处理 Room,重复生成或版本冲突。
- 把生成代码当源码修改,下次构建被覆盖。
追问
- 如何确认 Room 用的是哪个处理器?答:查看模块构建脚本的插件与注解处理器依赖;版本兼容矩阵查官方发布说明(待确认)。
- 生成代码量影响编译速度吗?答:实体/DAO 越多生成代码越多;KSP 通常改善增量编译表现。
07.1.1.8.1-082 编译期 “Cannot find column” 类错误如何排查?
一句话结论
先核对 SQL 引用列名与实体 @ColumnInfo 列名是否一致,再检查实体是否注册、类型转换器是否缺失;报错类名指向对应 DAO/实体定位。
概念解释
找不到列常见原因:属性名与列名不一致、改了列名没同步 SQL、嵌入对象前缀导致列名变化、列被 @Ignore 排除。Room 报错信息通常给出 DAO 方法与缺失列名,按 SQL 语句逐列对照实体元数据即可定位。
原理流程
报错列名 → 找 SQL 方法 → 对照实体 @ColumnInfo/嵌入前缀
→ 修正列名或补列/转换器
代码或图示
报错列名 → 定位 DAO 方法 SQL → 对照 @ColumnInfo/嵌入前缀/转换器
修正:列名对齐、补列、补 TypeConverter
常见误区
- 改了 Kotlin 属性名却依赖默认列名映射,SQL 仍按旧列名引用。
- 嵌入子对象字段与外层字段重名,列名被前缀改写后 SQL 没跟上。
追问
- 列存在但报类型不匹配怎么办?答:检查 TypeConverter 是否注册、可空性与亲和性是否一致。
- 生成代码报错怎么看?答:打开编译产物中生成的 DAO 实现,对照 SQL 绑定与结果映射。
07.1.1.8.1-083 实体新增必填列对老版本数据库如何兼容?
一句话结论
老库升级时新必填列必须在 Migration 中提供默认值或回填,否则非空约束插入失败;新安装设备由建表语句直接带默认值。
概念解释
NOT NULL 列在老表上没有历史值,加列时不给默认值违反约束。迁移脚本 ADD COLUMN ... NOT NULL DEFAULT '...';需要从旧列转换的值,在脚本或后台回填中生成。纯可空列兼容压力最小,但业务上要接受空值判断。
原理流程
老表加必填列 → 脚本给 DEFAULT → 历史行填充默认值
后续后台回填业务值
代码或图示
db.execSQL("ALTER TABLE Note ADD COLUMN priority INTEGER NOT NULL DEFAULT 0")
常见误区
- 新列声明非空却在迁移脚本漏 DEFAULT,升级时抛约束异常。
- 默认值与业务预期不符,历史数据被错误归类。
追问
- 能否不加默认值、先可空再回填后收紧约束?答:可以,分两步迁移;收紧约束需重建表,成本更高。
- 新增必填列对老版本 APK 有影响吗?答:旧 APK 不识别新列,但数据库文件仍由新版 APK 维护;回滚安装需评估兼容。
07.1.1.8.1-084 索引在 AutoMigration 中如何保留?
一句话结论
AutoMigration 对比 schema JSON 生成索引变更:新增索引自动建,删除索引自动删;改名或重建表时索引需随结构迁移核对,避免老库残留失效索引。
概念解释
索引是 schema diff 的一部分,实体上新增 indices 会出现在迁移脚本中。表重建类变更后,旧索引可能残留或新索引未建;迁移测试除结构比对外,应查询索引清单核对。
原理流程
schema JSON diff → 索引 ADD/DROP 语句
老库升级 → 索引集合与新版本对齐
代码或图示
schema JSON diff → ADD/DROP INDEX
迁移后核对:sqlite_master 中索引清单与新版本一致
常见误区
- 只比对表列,忽略索引缺失导致查询性能退化。
- 同名索引在重建表后重复创建,迁移脚本报错。
追问
- 如何列出老库索引?答:查询
sqlite_master中type='index'条目,或 PRAGMA 索引清单。 - AutoMigration 不识别的索引变更怎么办?答:该跳改手写 Migration 补索引 DDL。
07.1.1.8.1-085 分区存储下数据库备份导出有什么路径约束?
一句话结论
应用私有目录内的数据库文件不对外可见;导出备份需通过媒体集合或应用专属外部目录完成,遵循 Android 14 分区存储与权限约束,不能再随意写公共目录。
概念解释
Room 默认数据库文件在应用私有数据目录,其他应用不可访问。主动导出时,按版本使用系统提供的共享通道(如 SAF 选择器、MediaStore)写入受控位置;私有外部目录仍只本应用可见。备份文件是否加密、是否含用户敏感数据需单独评估。
原理流程
私有库文件 → 受控导出(SAF/MediaStore/私有外部目录)
→ 不绕过分区存储直接写公共路径
代码或图示
私有库文件 → SAF 选择器 / MediaStore / 私有外部目录
禁止直写公共目录;导出文件按敏感数据要求加密与清理
常见误区
- 沿用旧写法直接写
Environment.getExternalStorageDirectory(),新版设备受限或失败。 - 导出未加密的用户数据备份到不安全位置。
追问
- 数据库文件能直接复制备份吗?答:需在无写入事务时复制,或用 SQLite 备份 API;直接拷贝活动库可能得到不一致快照。
- 备份恢复路径怎么设计?答:导入文件先校验完整性与版本,再走打开/迁移流程。
07.1.1.8.1-086 Room 实体与网络 DTO 为什么要分层?
一句话结论
实体描述本地表结构,DTO 描述接口契约;两者字段语义、可空性、嵌套结构不同,分层可隔离网络变更对数据库模型的影响。
概念解释
接口字段会随后端演进改名、嵌套、增删;直接用 DTO 当实体,网络小改动就牵动表结构与迁移。Repository 在两层之间做映射:DTO → 实体入库,实体 → UI 模型展示。实体不应出现在网络层接口签名中。
原理流程
API DTO → 映射层 → Room 实体 → 本地库
本地实体 → UI 模型 → 界面
代码或图示
data class NoteDto(val id: Long, val title: String, val body: String)
data class NoteEntity(val id: Long, val title: String, val content: String)
fun NoteDto.toEntity() = NoteEntity(id, title, content = body)
常见误区
- 同一套类同时加
@Entity和序列化注解,网络改字段被迫做数据库迁移。 - 映射逻辑散落在界面层,数据层与网络层互相渗透。
追问
- 三层模型(DTO/Entity/UI)是否过度?答:简单项目可合并两层;字段语义分歧大的中型以上项目分层更稳。
- 映射代码放哪?答:数据层扩展函数(
toEntity/toDomain),便于单测覆盖。
07.1.1.8.1-087 删除全部记录与重置自增主键怎么处理?
一句话结论
DELETE 清行不重置自增序列;需要重置主键序号时,清表后重置 SQLite 序列(如 sqlite_sequence)或按表重建方式处理。
概念解释
SQLite 自增主键依赖行号/序列表,DELETE FROM table 后新行仍延续之前的最大值。测试重置、缓存重建场景若要求序号回到起点,需额外操作;生产环境通常不重置自增 ID,避免引用混乱。
原理流程
DELETE 清行 → 序列不回退
重置:DELETE FROM sqlite_sequence WHERE name = '表名'(具体机制按 SQLite 版本确认)
代码或图示
@Query("DELETE FROM Note")
suspend fun clear()
@Query("DELETE FROM sqlite_sequence WHERE name = 'Note'")
suspend fun resetSequence()
常见误区
- 清表后以为主键重新从 1 开始,测试断言序号失败。
- 业务表重置序列导致与外部引用的 ID 冲突。
追问
- 清空大表用 DELETE 还是 DROP 重建?答:DELETE 逐行记录日志、事务长;缓存重建场景可评估 TRUNCATE 等价的重建方式。
- 外键引用表清空顺序?答:先子表后父表,避免外键约束阻断。
07.1.1.8.1-088 如何查看 Room 生成的 SQL 与运行日志?
一句话结论
调试期可通过 Room 查询日志/数据库探查工具查看最终 SQL 与参数;生成代码在构建产物中,DAO 实现里可读到绑定语句。
概念解释
排查“查询为什么慢/返回空”时,先拿到实际执行的 SQL:参数绑定值、表名、条件是否符合预期。Android 数据库探查工具可连接设备查看库内容与执行计划;EXPLAIN QUERY PLAN 用于索引分析。
原理流程
DAO 方法 → 生成代码绑定 SQL → 执行
日志/工具:查看 SQL、参数、结果集与执行计划
代码或图示
DAO 实现类(生成代码)→ 绑定 SQL 与参数
探查工具 / EXPLAIN QUERY PLAN → 核对条件、索引命中与结果集
常见误区
- 只看 Kotlin 调用,不核对最终 SQL 里条件列与绑定值。
- 线上打开详细日志,泄露数据或增加开销。
追问
- 如何打印查询语句?答:按 Room 版本使用调试日志开关;具体 API 与可配置项待确认。
- 执行计划怎么读?答:
SCAN为全表扫描,SEARCH走索引;重点看大表条件是否命中索引。
07.1.1.8.1-089 实体类用 Kotlin data class 与普通 class 怎么取舍?
一句话结论
大多数实体用 data class:值语义、便于复制与比较;需要继承、复杂构造逻辑或非空校验时用普通 class。
概念解释
data class 自动生成 equals/hashCode/copy/toString,适合不可变数据载体;Room 按属性映射,不依赖 data class 特性。普通 class 适合带校验逻辑、继承体系或需要封装可变状态的场景,但要保证属性可读写。
原理流程
简单值载体 → data class + val 属性
带行为/继承 → 普通 class
代码或图示
data class Profile(val id: Long, val name: String) {
val displayName: String get() = name.trim()
}
常见误区
- data class 里混入
var可变字段并在多处修改,破坏值语义。 - 普通 class 写了私有只读属性,Room 无法填充。
追问
- data class 能带默认参数吗?答:可以,默认值用于构造与迁移映射;注意 Room 实例化是否需要无参或全参构造(待确认)。
- 实体参与集合去重靠什么?答:主键判断唯一性;
equals按全部字段比较,集合行为需区分。
07.1.1.8.1-090 一个 DAO 接口可以被多个数据库复用吗?
一句话结论
可以定义公共 DAO 接口,但每个数据库类各自生成实现;复用前提是表名、列名与实体在各库一致,跨库字段差异会破坏映射。
概念解释
DAO 注解 SQL 绑定到具体表结构;把接口放到公共模块供多个 RoomDatabase 使用,适合多环境(开发/演示)或结构相同的分库。若某库表结构不同,应拆分各自 DAO,避免一套 SQL 适配两套结构。
原理流程
公共 @Dao 接口 → 每个 @Database 生成各自实现
表结构一致 → 可复用;不一致 → 拆 DAO
代码或图示
// 公共模块定义
@Dao interface NoteDao { /* 注解方法 */ }
// 各 @Database 分别生成实现;表结构必须一致
常见误区
- 公共 DAO 引用了仅部分库存在的列,其他库编译期映射失败。
- 以为 DAO 实例可跨数据库实例共享。
追问
- 多模块 DAO 放哪一层?答:数据层公共模块,实体与表结构约定在同一层。
- 分库后跨库查询怎么做?答:应用层分别查询再组装,SQLite 不直接跨库连接(附加库除外)。
07.1.1.8.1-091 @Database 的 entities 列表漏登记实体有什么后果?
一句话结论
实体未注册进数据库类,对应表不会被创建,相关 DAO 查询在运行期报“no such table”;编译期可能不拦截,错误推迟到运行时。
概念解释
entities 列表决定建表集合与 schema 元数据。漏登记时 DAO 存在但表不存在,观察查询与写入均失败。新增实体后必须同步更新数据库类列表与版本号、迁移脚本。
原理流程
@Database(entities = [A::class, B::class])
漏 C → 无 C 表 → DAO 操作 C 运行期报错
代码或图示
@Database(entities = [Note::class, Tag::class], version = 1)
abstract class AppDatabase : RoomDatabase()
// 漏登记 Tag → 运行期 no such table: Tag
常见误区
- 新实体只写了 DAO,忘记加入
entities。 - 多模块实体由各模块模块类提供,聚合时遗漏。
追问
- 漏登记能在编译期发现吗?答:部分映射校验可能提示;运行期建表缺失是最终表现,需靠启动测试覆盖。
- 注册实体但无 DAO 会怎样?答:表会创建,仅无访问入口。
07.1.1.8.1-092 Room 支持数据库视图(@DatabaseView)吗?
一句话结论
支持 @DatabaseView 定义只读 SQL 视图,注册到数据库类后可在 DAO 中查询,适合固定聚合投影与跨表只读组合。
概念解释
视图是预定义查询的命名结果,底层不存数据;实体映射到表,视图映射到只读投影。复杂 JOIN/聚合固定不变时用视图简化 DAO SQL;视图随基表变更,结构演进同样需要迁移考虑。
原理流程
@DatabaseView("SELECT ...") → 注册进 entities/views
→ DAO 从视图查询,不可直接写入
代码或图示
@DatabaseView("SELECT id, title, createdAt FROM Note WHERE trashed = 0")
data class ActiveNoteView(val id: Long, val title: String, val createdAt: Long)
@Database(entities = [Note::class], views = [ActiveNoteView::class], version = 1)
abstract class AppDatabase : RoomDatabase()
常见误区
- 把视图当实体做
@Insert,视图不支持直接写入。 - 基表列改名后视图 SQL 未同步,查询失败。
追问
- 视图有索引吗?答:视图本身不存数据,索引建立在基表上;视图查询性能依赖基表索引。
- 视图需要迁移吗?答:视图定义随版本变更,升级路径需
DROP VIEW后重建,纳入 Migration。
07.1.1.8.1-093 FTS 虚拟表在 Room 中如何声明?
一句话结论
Room 支持声明 FTS 虚拟表实体(@Entity 配合 FTS 选项),用于全文检索;表结构与普通表不同,查询用 MATCH 语法。
概念解释
FTS 表为分词检索建倒排索引,适合长文本搜索;实体需要配置 FTS 版本与内容关联方式。FTS 表占用额外存储,与主表通过主键关联,搜索结果再回表取完整记录。具体注解参数与 FTS 版本支持以 Room 版本为准(待确认)。
原理流程
主表 Note ← 主键关联 → FTS 全文表
MATCH 检索 → 命中主键 → 回表展示
代码或图示
// FTS 实体配置(版本支持与参数待确认)
@Entity(/* FTS 选项 */)
data class NoteFts(val text: String)
// MATCH 检索命中主键后回主表取完整记录
常见误区
- 把 FTS 表当普通关系表建外键/索引,语义不匹配。
- 文本更新后 FTS 索引未同步更新,搜索结果滞后。
追问
- 中文分词怎么办?答:默认分词对中文友好度有限,需评估分词方案;具体支持能力待确认。
- FTS 表数据如何重建?答:内容变更后重建索引;迁移场景评估索引重建耗时。
07.1.1.8.1-094 字符排序规则(COLLATE)对中文查询有什么影响?
一句话结论
默认 BINARY 按 Unicode 码位排序,中文按字符编码顺序排列而非拼音;需要拼音/本地化排序时需指定排序规则或在应用层排序。
概念解释
NOCASE 只处理 ASCII 大小写;SQLite 内置排序规则对中文拼音排序支持有限。中文姓名、城市等按拼音检索展示的场景,数据库排序可能不符合预期,通常在查询结果层用本地化比较器排序,或冗余排序字段。
原理流程
ORDER BY 列 COLLATE 规则 → 比较函数决定顺序
中文:BINARY 码位序 ≠ 拼音序
代码或图示
-- BINARY 按 Unicode 码位排序,不等于拼音序
SELECT name FROM Contact ORDER BY name COLLATE BINARY
-- 拼音排序建议:应用层比较器或冗余拼音字段
常见误区
- 假设 SQLite 默认按拼音排序,列表顺序与界面预期不符。
- 每次查询在内存做拼音排序,大数据量下增加开销。
追问
- 冗余拼音字段可行吗?答:可行,存拼音首字母/全拼用于索引排序;生成与维护成本需评估。
- 排序规则能在建表后改吗?答:列级规则随表定义;查询级
COLLATE可在 ORDER BY 临时指定。
07.1.1.8.1-095 大批量插入如何提速?
一句话结论
批量写入放在单个事务内、使用绑定参数、分批提交;必要时临时关闭外键检查/索引维护,写完再恢复,减少逐条事务与索引开销。
概念解释
逐条插入每条自带事务与日志刷新,大批量下 IO 放大明显。DAO 提供集合参数的 @Insert,Room 批量绑定;事务包裹一批(如每 500-1000 条),避免单事务过大。索引在写入时同步维护,写入密集期可评估取舍。
原理流程
分批:BEGIN → 批量绑定插入 → COMMIT → 下一批
对比:逐条自动提交,每条一次事务
代码或图示
@Insert
suspend fun insertAll(items: List<Note>)
@Transaction
suspend fun bulkSave(items: List<Note>) {
items.chunked(500).forEach { insertAll(it) }
}
常见误区
- 万条记录逐条 suspend 插入,事务与日志开销叠加。
- 单事务包全部数据,回滚段与内存压力过大。
追问
- 外键检查拖慢批量导入怎么办?答:受控场景可临时关闭外键检查再恢复;顺序与完整性需自行保证。
- 插入时索引怎么平衡?答:写入极密集时可先关索引、批量导入后重建;常规业务保留索引即可。
07.1.1.8.1-096 只读 DAO 与写入 DAO 拆分有什么工程意义?
一句话结论
按查询/写入职责拆分 DAO 接口,使数据层依赖方向清晰:界面与只读场景只依赖读接口,写入能力收敛到对应用例,便于测试与权限边界控制。
概念解释
单一大 DAO 把所有表操作混在一起,调用方容易绕过业务规则直接写库。拆分后读 DAO 提供观察/查询方法,写 DAO 暴露插入更新删除;Repository 在中间承载规则,单元测试可分别替换两侧。
原理流程
ReadDao:查询/观察
WriteDao:写入/删除
Repository 组合两者,对外暴露用例方法
代码或图示
interface ReadNoteDao { fun observe(): Flow<List<Note>> }
interface WriteNoteDao { suspend fun upsert(note: Note) }
// Repository 组合两者,对外暴露用例方法
常见误区
- 拆分后写逻辑仍散落在各调用方,DAO 只是形式上分开。
- 读接口返回可变实体,调用方误改后绕过写 DAO。
追问
- 多表跨 DAO 事务怎么保证?答:事务边界放在 Repository 用例方法或
@Transaction组合方法内。 - 接口拆分与模块边界关系?答:只读接口可下沉到更底层模块,写入实现留在上层用例层。
07.1.1.8.1-097 Room 对外键循环引用怎么处理?
一句话结论
表之间形成 A 引用 B、B 又引用 A 的循环外键时,建表与插入顺序受限;应评估是否消除循环,或通过中间表/软引用打破闭环。
概念解释
外键要求被引用行先存在,循环依赖下两个表都无法先完成独立插入。常见解法:把其中一侧改为非约束引用(应用层保证)、用关联中间表、或软删除标记。数据模型层面循环往往说明聚合边界划分不清。
原理流程
A.fk → B;B.fk → A:插入先后矛盾
解法:去约束 / 中间表 / 调整聚合归属
代码或图示
A.fk → B 且 B.fk → A:插入先后矛盾
解法:一侧改非约束引用 / 中间表 / 调整聚合归属
常见误区
- 两表都建强外键,初始化与迁移时违反约束失败。
- 为方便写入临时去掉外键,留下孤儿数据无人清理。
追问
- 循环引用在对象模型里常见吗?答:领域对象双向导航常见;持久化时只保留一侧强引用,另一侧按需查询组装。
- 打破循环后一致性怎么保证?答:Repository 用例方法控制写入顺序与校验,必要时定时扫描孤儿记录。
07.1.1.8.1-098 数据库降级(版本回退)时 Room 怎么应对?
一句话结论
Room 不提供自动降级迁移;代码版本低于已安装库版本时,按降级兜底策略处理,默认行为可能抛异常或破坏性重建,需在发布前评估回滚场景。
概念解释
线上发版后回滚安装(如热修复包)会遇到老代码打开新结构库。可配置 fallbackToDestructiveMigrationOnDowngrade 降级重建;涉及用户数据时这不可接受,应在版本设计上避免不可逆结构变更,或提供降级数据兼容方案。
原理流程
库版本 N > 代码版本 M → 降级路径
无策略:打开失败;配兜底:重建空库
代码或图示
库版本 N > 代码版本 M
无策略:打开失败;fallbackToDestructiveMigrationOnDowngrade:重建空库
常见误区
- 假设用户永远只升级,不评估回滚安装的结构兼容。
- 降级重建后未同步提示用户数据已重置。
追问
- 如何做兼容降级?答:新列保持可空/默认值,老代码不识别也能运行;破坏性结构变更避免在快速迭代期上线。
- 降级测试怎么做?答:构造高版本库,装低版本包验证打开行为与数据表现。
07.1.1.8.1-099 如何评估 Room 表设计是否合理?
一句话结论
从字段必要性、范式与冗余、索引覆盖、写入频率、查询模式五个维度评估:列服务于明确查询,索引命中高频条件,写入代价与读取收益平衡。
概念解释
宽表把所有字段塞一张表会增加迁移与一致性成本;过度拆表又增加 JOIN 与组装开销。评审时对照主要查询路径:过滤/排序/连接列是否有索引,聚合是否可下推,哪些字段不需要落库。范式用于减少更新异常,适度冗余服务于读性能。
原理流程
列出查询场景 → 反推表/列/索引
评审:冗余是否可接受、写入代价、迁移演进成本
代码或图示
查询场景清单 → 反推表/列/索引
评审:冗余取舍、写入代价、索引命中、迁移演进成本
常见误区
- 先建宽表再补查询,索引后补导致初期全表扫描。
- 为“以后可能用到”预留大量未使用列。
追问
- 冗余字段怎么决策?答:高频读取、计算代价高、一致性要求可接受时冗余;标注数据来源与刷新路径。
- 表结构评审看哪些产物?答:schema JSON、DAO 查询清单、索引清单与典型执行计划。
07.1.1.8.1-100 从裸 SQLite 迁移到 Room 有哪些历史包袱要清理?
一句话结论
迁移到 Room 时需要收敛手写 SQL、统一实体/DAO 模型、补版本与迁移基线,并清理散落的 SQLiteOpenHelper、原生游标与重复连接管理。
概念解释
旧项目常见多处直开数据库、字符串拼接 SQL、游标手动关闭、表结构散落在代码里。Room 化过程:先固化现有表结构与版本,逐步把查询迁到 DAO,清理原生 Helper;实体与 DTO/UI 模型分层后,再补索引、观察流与迁移测试。
原理流程
固化旧 schema → 实体/DAO 落地 → 替换裸 SQLite 调用
→ 清理 Helper/游标/拼接 SQL → 补迁移测试与索引
代码或图示
固化旧 schema → 实体/DAO 落地 → 替换裸 Helper 调用
清理:游标手动关闭、字符串拼接 SQL、重复连接管理
常见误区
- 新旧两套数据访问并存,同一表两套写入路径,一致性难维护。
- 直接把原生 SQL 原样塞进
@RawQuery,未利用编译期校验与类型映射。
追问
- 迁移期间如何降低风险?答:按模块/表逐步切换,保留兼容期;DAO 先读后写,验证查询结果一致再切写入。
- 旧库版本基线怎么定?答:以现有数据库结构导出为首版 schema JSON,后续变更从该版本号递增。
参考来源
- Android 官方:Room 持久化库 — 实体、DAO、数据库类的基本用法与架构约束。
- Android 官方:定义数据实体与关系 —
@Embedded、@Relation、@Junction与外键建模。 - Android 官方:迁移数据库版本 — Migration、AutoMigration、兜底策略与 schema 导出。
- Room 参考包 — 注解与 DAO 返回类型的 API 清单。
- SQLCipher Android — 数据库加密接入参考;具体集成 API 以依赖版本文档为准。
待整理清单
- [ ] 核对当前工程使用的 Room 2.6/2.7 具体小版本,确认
@Upsert、AutoMigration 注解与 FTS 支持边界。 - [ ] 确认 KSP 与 kapt 在本工程的注解处理器配置及生成代码目录。
- [ ] 补充 WAL 模式、连接池参数在所用 Room 版本上的可配置项。
- [ ] 整理中文分词与 FTS 检索在实际业务中的选型结论。
- [ ] 补充本项目各表的 schema JSON 基线与迁移测试用例清单。