Room DAO 层编写：任务持久化核心操作

DAO（Data Access Object）是 Room 持久化层与业务逻辑层之间的桥梁，它通过编译时生成的实现类将 Kotlin/Java 方法调用映射为 SQL 语句。本章按课程需求实现五个核心方法：插入任务、按状态查询任务、更新任务状态、删除任务、获取待恢复任务列表。下面先从接口定义出发，再逐一讲解每个方法的原理、注解用法、返回值类型，最后给出完整的 DAO 接口代码和调用示例。

DAO 方法一览

实现流程

1. 定义任务实体 TaskEntity（已在第 3 章完成）。
2. 创建 DAO 接口 TaskDao，标记 @Dao 注解。
3. 在 AppDatabase 的抽象方法中暴露 taskDao()。
4. 在 Repository 或 ViewModel 中调用 DAO 方法。

完整 DAO 接口代码

@Dao
interface TaskDao {

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertTask(task: TaskEntity): Long

    @Query("""
        SELECT * FROM task 
        WHERE status = :status 
        ORDER BY created_at DESC
    """)
    fun queryTasksByStatus(status: String): LiveData<List<TaskEntity>>

    @Query("UPDATE task SET status = :newStatus WHERE id = :taskId")
    suspend fun updateTaskStatus(taskId: Long, newStatus: String): Int

    @Query("DELETE FROM task WHERE id = :taskId")
    suspend fun deleteTask(taskId: Long): Int

    @Query("""
        SELECT * FROM task 
        WHERE status IN ('QUEUED', 'RETRYING') 
        ORDER BY priority DESC, created_at ASC
    """)
    suspend fun getPendingTasks(): List<TaskEntity>
}

关键注解与实现原理

• @Insert：Room 自动生成 INSERT 语句。当 onConflict = REPLACE 时，如果主键冲突则替换整行（适用于幂等插入）。返回值 Long 为插入行的 rowId。
• @Query：用于执行自定义 SQL。编译时校验语法，参数通过 :paramName 绑定。返回 LiveData 时，Room 会在数据表变化时自动通知观察者——这是实现任务恢复响应式更新的基础。
• 挂起函数：DAO 方法声明为 suspend，确保在协程作用域内执行，避免阻塞主线程。
• 排序策略：getPendingTasks 按优先级降序、创建时间升序排序，让高优先级任务优先恢复。

调试与常见错误

性能与稳定性优化

• 批量插入：如需一次插入多个任务，使用 @Insert 接受 List<TaskEntity>，Room 会自动生成事务执行批量插入，效率远高于循环单条插入。
• 索引优化：在 status 和 priority 列上创建联合索引，可大幅提升 getPendingTasks 查询性能：

@Entity(
    tableName = "task",
    indices = [
        Index(value = ["status", "priority"])
    ]
)
data class TaskEntity(...)

• 事务保证：若需要在一个原子操作中更新状态并插入日志，使用 @Transaction 注解标记 DAO 方法，Room 会将其包裹在数据库事务中。
• 避免大对象查询：当待恢复任务列表中包含大量 Blob 字段（如序列化的 WorkSpec）时，考虑使用只返回 ID 和状态的轻量查询，再按需加载完整对象。

DAO 层架构示意

下图展示了 Room DAO 在整体持久化架构中的位置，以及本课程实现的五个方法如何参与任务恢复流程：