数据访问对象 (DAO) 进阶：挂起函数与 Flow 返回值、事务、批量操作

Room 的 DAO 层是离线数据绑定的核心枢纽。基础阶段的 @Insert、@Update、@Delete 和 @Query 只支持同步返回。进入进阶阶段后，你需要利用挂起函数、Flow 返回值、事务与批量操作来构建响应式、高性能且线程安全的离线数据管道。本章将逐一拆解这些机制的实现原理、调用合约及常见陷阱。

进阶 DAO 特性概览

1. 挂起函数 (suspend fun)

在 DAO 中声明 suspend 函数后，Room 会自动将数据库操作切换到后台线程执行。调用方必须在协程作用域（如 viewModelScope）内调用。

@Dao
interface UserDao {
    @Insert
    suspend fun insertUser(user: User): Long

    @Update
    suspend fun updateUser(user: User)

    @Query("SELECT * FROM users WHERE id = :id")
    suspend fun getUserById(id: Long): User?
}

2. Flow 返回值：实时数据流

当查询方法返回值类型为 Flow<T> 时，Room 会在底层注册一个观察者，一旦所涉及的表发生任何增、删、改，Flow 就会自动发射新数据。该机制与 Jetpack Compose 的 collectAsState() 天然契合，无需手动刷新。

@Dao
interface UserDao {
    @Query("SELECT * FROM users ORDER BY name ASC")
    fun getAllUsersFlow(): Flow<List<User>>

    @Query("SELECT * FROM users WHERE id = :id")
    fun getUserFlow(id: Long): Flow<User?>
}

3. 事务 (@Transaction)

当一个 DAO 方法需要执行多条 SQL 语句并保证原子性时，使用 @Transaction 注解。Room 会在进入方法前开启数据库事务，方法正常结束则提交，异常则回滚。

@Dao
interface OrderDao {
    @Transaction
    suspend fun createOrderWithItems(order: Order, items: List<OrderItem>) {
        val orderId = insertOrder(order)
        items.forEach { it.orderId = orderId }
        insertItems(items)
    }

    @Insert
    suspend fun insertOrder(order: Order): Long

    @Insert
    suspend fun insertItems(items: List<OrderItem>)
}

4. 批量操作

批量插入、更新、删除应使用集合参数，Room 会将其展开为一条预编译语句的多条参数绑定，极大减少 SQLite 的解析和日志写入开销。

@Dao
interface ProductDao {
    // 批量插入，替换冲突的行
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertAll(products: List<Product>)

    // 批量更新
    @Update
    suspend fun updateAll(products: List<Product>)

    // 批量删除（按主键列表）
    @Query("DELETE FROM products WHERE id IN (:ids)")
    suspend fun deleteByIds(ids: List<Int>)
}

5. 常见错误与调试

• 挂起函数在非协程上下文调用： 直接从主线程调用 suspend DAO 函数，IDE 会编译报错（挂起函数只能在协程内调用）。如果误用了 runBlocking 会导致 ANR。
• @Transaction 修饰非 suspend 函数： Room 允许在普通函数上使用 @Transaction，但此时调用者需要自行管理线程（建议统一使用 suspend 避免混用）。
• Flow 在横竖屏切换时重新发射： Flow 本身不保存状态，配合 stateIn 或 shareIn（作用域 WhileSubscribed）可避免每次屏幕旋转重复触发数据库查询。
• 批量操作返回的 List<Long> 并非所有插入的行 ID： Room 批量插入返回的 List<Long> 可能包含重复或无效值，应避免依赖返回值顺序。

6. 性能优化要点

1. 批量时始终开启事务： 举例：1000 条插入，无事务时约需 3000ms，加事务后压缩到 50ms。
2. 使用 allowMainThreadQueries() 不可取： 调试阶段可能临时允许，但生产环境一定走挂起函数或 Flow，避免阻塞 UI 线程。
3. 避免对 Flow 使用 distinctUntilChanged： Room 的 Flow 已经内置了表级变化去重，再添加 distinctUntilChanged 只在需要对象属性级过滤时才有意义。
4. 分页查询搭配 Paging 3： 大量数据列表应使用 @Query 返回 PagingSource，而非一次性加载全部行。