第3章 Room实体设计：队列任务表字段设计、状态枚举、索引、唯一约束、时间戳

3.1 设计原理与目标

在持久化队列案例中，Room实体是整个系统的数据基石。设计核心目标如下：

• 任务可追溯：每一条待处理或已处理任务都需被唯一标识。
• 状态可控：通过枚举精确描述任务在队列生命周期的各个阶段。
• 查询高效：通过索引与唯一约束，避免全表扫描、防止重复入队。
• 时间可审计：自动记录任务的创建与更新时间，方便性能分析与故障排查。

3.2 字段定义与数据类型选择

下表展示了队列任务表 (queue_task) 的所有字段及其设计意图：

3.3 状态枚举 (TaskStatus) 定义

枚举定义了任务在队列中的状态流转，每个状态值都对应一个整型持久化值：

enum class TaskStatus {
    PENDING(0),      // 等待处理
    PROCESSING(1),   // 正在执行（WorkManager Worker 持有）
    COMPLETED(2),    // 执行成功
    FAILED(3),       // 执行失败（达到最大重试次数后）
    CANCELLED(4),    // 被用户或系统取消
    SCHEDULED(5);    // 延迟执行（schedule_at 未来时间）

    @androidx.room.TypeConverter
    companion object {
        @JvmStatic
        @androidx.room.TypeConverter
        fun fromInt(value: Int): TaskStatus {
            return entries.firstOrNull { it.value == value } ?: PENDING
        }

        @JvmStatic
        @androidx.room.TypeConverter
        fun toInt(status: TaskStatus): Int = status.value
    }
}

3.4 索引与唯一约束

索引直接影响查询性能，唯一约束用于防止业务数据重复。以下是关键的索引策略：

• 复合索引 (status, priority)：配合取任务查询 (SELECT ... WHERE status = PENDING ORDER BY priority DESC)，避免全表扫描。
• 唯一约束 (task_type, payload)：保证相同业务类型的负载唯一，避免重复入队。
• 单列索引 (schedule_at)：加速延迟任务的筛选。

使用 @Entity 注解的 indices 属性声明：

@Entity(
    tableName = "queue_task",
    indices = [
        Index(value = ["status", "priority"]),
        Index(value = ["schedule_at"]),
        Index(value = ["task_type", "payload"], unique = true)
    ]
)
data class QueueTask(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0L,
    @ColumnInfo(name = "task_type")
    val taskType: String,
    val payload: String,
    val priority: Int = 0,
    @ColumnInfo(name = "status")
    val status: TaskStatus = TaskStatus.PENDING,
    @ColumnInfo(name = "retry_count")
    val retryCount: Int = 0,
    @ColumnInfo(name = "max_retries")
    val maxRetries: Int = 3,
    @ColumnInfo(name = "schedule_at")
    val scheduleAt: Long = System.currentTimeMillis(),
    @ColumnInfo(name = "created_at")
    val createdAt: Long = System.currentTimeMillis(),
    @ColumnInfo(name = "updated_at")
    val updatedAt: Long = System.currentTimeMillis()
)

3.5 自动化时间戳 (@UpdateTimestamp / @CreatedTimestamp)

Room 支持自动写入和更新 created_at 和 updated_at。在 @Dao 中声明自动更新方法：

@Dao
interface QueueTaskDao {
    @Insert(onConflict = OnConflictStrategy.ABORT)
    suspend fun insert(task: QueueTask): Long

    @Update
    suspend fun update(task: QueueTask)

    @Query("""
        SELECT * FROM queue_task 
        WHERE status = :status 
        ORDER BY priority DESC, created_at ASC
        LIMIT 1
    """)
    suspend fun getNextTask(status: TaskStatus): QueueTask?

    @Query("UPDATE queue_task SET status = :status, updated_at = :timestamp WHERE id = :id")
    suspend fun updateStatus(id: Long, status: TaskStatus, timestamp: Long = System.currentTimeMillis())

    @Query("DELETE FROM queue_task WHERE status = :status AND updated_at < :threshold")
    suspend fun deleteOldCompleted(status: TaskStatus, threshold: Long)
}

3.6 完整的 Room Entity 代码结构

package com.example.queuecase.data.local.entity

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

@Entity(
    tableName = "queue_task",
    indices = [
        Index(value = ["status", "priority"]),
        Index(value = ["schedule_at"]),
        Index(value = ["task_type", "payload"], unique = true)
    ]
)
data class QueueTask(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0L,
    @ColumnInfo(name = "task_type")
    val taskType: String,
    val payload: String,
    val priority: Int = 0,
    @ColumnInfo(name = "status")
    val status: TaskStatus = TaskStatus.PENDING,
    @ColumnInfo(name = "retry_count")
    val retryCount: Int = 0,
    @ColumnInfo(name = "max_retries")
    val maxRetries: Int = 3,
    @ColumnInfo(name = "schedule_at")
    val scheduleAt: Long = System.currentTimeMillis(),
    @ColumnInfo(name = "created_at")
    val createdAt: Long = System.currentTimeMillis(),
    @ColumnInfo(name = "updated_at")
    val updatedAt: Long = System.currentTimeMillis()
)

3.7 常见错误与优化指南

3.8 性能与存储优化

• payload 压缩：如果 payload 体积较大（> 1KB），存入前使用 GZIPOutputStream 压缩，读取时解压，减少磁盘 I/O。
• 分区表：对于超大规模队列（百万级），可按 status 分区，删除 COMPLETED/FAILED 历史记录时只操作单分区。
• 只创建必要索引：索引不足则查询慢，索引过多则写入慢。本实体三个索引是针对高频查询点（取任务、延迟任务、去重入队）的精简方案。

3.9 实体关系与状态机流程总图

下图展示了 queue_task 实体如何通过索引、唯一约束和时间戳，支撑起一个健壮的队列状态机：