2. Room工作原理深度拆解：SQLite封装、DAO、实体、数据库升级

Room是Android官方提供的持久化库，本质是对底层SQLite的轻量封装。理解Room的核心组件——数据库（Database）、DAO（数据访问对象）、实体（Entity）以及数据库升级机制，是正确使用Room的前提。本章从源码执行链路出发，逐层拆解Room如何将Kotlin/Java注解编译为SQLite操作，并指导你在实际项目中避开常见陷阱。

2.1 Room核心概念与职责划分

2.2 工作流程拆解：从注解到SQL执行

Room使用Java注解处理器在编译阶段自动生成中间代码。以下是一个典型DAO查询方法的完整执行链路：

// 编译后生成的 UserDao_Impl 片段（为清晰做了简化）
@Override
public User getUserById(final long userId) {
    final String _sql = "SELECT * FROM user WHERE id = ?";
    final RoomSQLiteQuery _query = RoomSQLiteQuery.acquire(_sql, 1);
    _query.bindLong(1, userId);
    __db.assertNotSuspendingTransaction();
    final Cursor _cursor = DBUtil.query(__db, _query, false, null);
    try {
        final User _result;
        if (_cursor.moveToFirst()) {
            _result = __entityConversionResult.getUserFromCursor(_cursor);
        } else {
            _result = null;
        }
        return _result;
    } finally {
        _cursor.close();
        _query.release();
    }
}

2.3 实体（Entity）映射规则与避坑

实体类通过 @Entity 注解映射为数据库表。每个字段默认成为一列，字段名即列名。可通过 @ColumnInfo(name = "full_name") 自定义列名。

常见陷阱：

• 基本类型 vs 包装类型：int 默认值为0，Integer 可为null。若数据库允许NULL，应使用包装类型。
• 主键不可变：@PrimaryKey 字段推荐使用 long 或 String 且设置为不可变（val）。
• 嵌入式对象：@Embedded 可将嵌套对象的字段展开到同一张表，避免关联查询。

@Entity(tableName = "user")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    @ColumnInfo(name = "full_name")
    val name: String?,
    val age: Int,
    // 嵌入 Address 对象的字段：street, city
    @Embedded
    val address: Address
)

2.4 DAO 设计模式与性能关键点

2.5 数据库升级（Migration）机制

当实体定义变更（新增/删除/重命名列、修改约束），必须提高数据库版本号，并提供 Migration 对象告知Room如何迁移数据。Room不支持自动迁移，开发者需手动编写SQL。

// 从版本1升级到版本2：新增列 age
val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE user ADD COLUMN age INTEGER NOT NULL DEFAULT 0")
    }
}

// 从版本2升级到版本3：重命名列 name -> full_name
val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE user RENAME COLUMN name TO full_name")
    }
}

// 构建时传入迁移列表
Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
    .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
    .build()

2.6 Room 工作流程全链路 SVG 图

2.7 实践清单：Room使用的10条黄金规则

1. 始终使用 @PrimaryKey 且字段不可变：防止Room意外修改主键导致数据不一致。
2. DAO方法返回 LiveData 或 Flow：利用Room的自动观察能力，避免手动刷新。
3. 避免在DAO中写复杂JOIN：拆分为多次查询并用 @Transaction 保证原子性。
4. 数据库升级必须提供 Migration：绝不要设置 fallbackToDestructiveMigration() 在生产环境。
5. 使用 @ColumnInfo 显式命名列：避免因字段重命名导致混淆。
6. 优先使用 List<Entity> 而非 Cursor：提升类型安全和性能。
7. 大数据量操作放在后台线程：Room数据库操作默认在主线程抛出异常（除非调用 allowMainThreadQueries()）。
8. 合理使用 @Embedded 和 @Relation：减少嵌套查询并保持数据结构清晰。
9. 利用 @Transaction 将多个DAO调用组合为事务：保证数据一致性。
10. 数据库版本号严格递增：每次发布新版本如修改表结构，必须加1且不可回退。