第3章 Room数据库实体设计：TaskEntity定义

3.1 实体设计原理

Room 实体（Entity）是数据持久化的核心单元，每个实体类对应数据库中的一张表。TaskEntity 在本课程中承担着持久化 WorkManager 任务状态与数据的职责——当应用进程被系统杀死或任务意外中断时，Room 负责将未完成的任务实体完整恢复出来，交由 WorkManager 重新调度。

实体设计的三个关键原则：

• 字段即列：每个公开字段或带 getter/setter 的属性自动映射为表的列。
• 主键驱动：每个实体必须声明至少一个主键，用于唯一标识一行记录。
• 索引加速：为频繁查询的字段（如 status、createTime）建立索引，避免全表扫描。

3.2 TaskEntity 字段设计

根据任务持久化恢复的需求，每个 TaskEntity 包含 5 个核心字段。下表列出字段的 Kotlin 类型、数据库列名、注解及用途：

3.3 主键与索引策略

主键： id 字段使用 @PrimaryKey(autoGenerate=true)，由 Room 在插入时自动生成自增值。自增主键能保证写入顺序与物理存储顺序一致，减少 B+ 树页分裂，提升写入性能。

复合索引： 在 status 和 createTime 上建立联合索引，加速按状态过滤并按时间排序的查询——这是任务恢复时最频繁的操作模式。

// 在 TaskEntity 类上的 @Entity 注解中声明索引
@Entity(
    tableName = "task",
    indices = [
        Index(value = ["status", "createTime"], name = "idx_status_create_time"),
        Index(value = ["workId"], name = "idx_work_id", unique = true)  // workId 全局唯一
    ]
)
data class TaskEntity(
    // ……
)

3.4 类型转换器实现

Room 默认只能存储基本数据类型（Int、Long、String、Boolean 等）。为了持久化 TaskStatus 枚举，必须编写 TypeConverter 完成枚举与 String 的双向转换。

3.4.1 枚举定义

enum class TaskStatus {
    PENDING,      // 等待执行
    RUNNING,      // 正在执行
    SUCCESS,      // 执行成功
    FAILED,       // 执行失败
    CANCELLED     // 已取消
}

3.4.2 TypeConverter 实现

import androidx.room.TypeConverter

class TaskConverters {

    @TypeConverter
    fun fromTaskStatus(status: TaskStatus): String {
        return status.name
    }

    @TypeConverter
    fun toTaskStatus(value: String): TaskStatus {
        return TaskStatus.valueOf(value)
    }
}

3.4.3 注册到 RoomDatabase

@Database(
    entities = [TaskEntity::class],
    version = 1,
    exportSchema = false
)
@TypeConverters(TaskConverters::class)
abstract class AppDatabase : RoomDatabase() {
    abstract fun taskDao(): TaskDao
}

3.5 完整 TaskEntity 代码

合并上述所有设计要点，得到完整的实体类：

import androidx.room.ColumnInfo
import androidx.room.Entity
import androidx.room.Index
import androidx.room.PrimaryKey

@Entity(
    tableName = "task",
    indices = [
        Index(value = ["status", "create_time"], name = "idx_status_create_time"),
        Index(value = ["work_id"], name = "idx_work_id", unique = true)
    ]
)
data class TaskEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,

    @ColumnInfo(name = "work_id")
    val workId: String,

    @ColumnInfo(name = "input_data")
    val inputData: String,

    @ColumnInfo(name = "status")
    val status: TaskStatus,

    @ColumnInfo(name = "create_time")
    val createTime: Long
)

3.6 调试与常见错误

3.7 性能与稳定性优化建议

1. 复合索引粒度控制： status + createTime 索引只覆盖“按状态过滤并按时间排序”这一种查询模式。如果后续增加按 inputData 模糊搜索的需求，应单独建立 FTS 全文索引，而不是在现有复合索引上追加列。
2. 避免大对象阻塞主线程： inputData 虽然设计为 String，但如果序列化后超过 1MB，会显著拖慢插入和读取。建议在业务层限制输入数据的最大大小（例如 512KB），超过阈值的任务改用文件存储路径替代。
3. 预创建 WAL 模式： 在 Room.databaseBuilder 中启用 WAL 模式，可大幅提升并发读写性能，尤其适合 WorkManager 后台多任务同时更新状态的场景。

// 在构建 Database 时开启 WAL 模式
val db = Room.databaseBuilder(
    context,
    AppDatabase::class.java,
    "task_work_db"
)
    .setJournalMode(RoomDatabase.JournalMode.WRITE_AHEAD_LOGGING)
    .build()