WorkManager 可靠性实战：唯一任务、重试与幂等设计

这篇文章以“离线订单同步”为例。从一个能运行的 Worker 开始，逐步补齐工程中最容易遗漏的可靠性设计。

从使用者痛点来看，任务丢失或重复执行导致数据异常

- 应用被程序回收后未完成的同步请求会消失。话说回来，- 使用者连续点击“提交”按钮。会产生多个相同的同步请求，导致服务器出现重复订单。- 网络瞬时中断后若没有合适的重试策略。任务会直接标记失败，需要人工干预。

问题

WorkManager 适合需要保证最终执行、允许程序选择时机的可延迟后台任务。任务提交后即使应用退出或设备重启，调度信息仍会保留。

至于典型场景包括，

• 将本地待上传数据同步到服务器；
• 定期清理过期文件；
• 在联网后补传埋点或诊断日志；
• 下载后执行解压、校验等连续步骤。

它不适合精确到秒的闹钟，也不适合需要持续与使用者交互的长时间操作。前者应考虑 AlarmManager后者通常需要前台服务。WorkManager 保证的是满足条件后获得执行机会，不保证某个精确时刻立即运行。不过，

从 CoroutineWorker 开始

class OrderSyncWorker(
appContext: Context,workerParams: WorkerParameters。private val repository: OrderRepository
) : CoroutineWorker {
override suspend fun doWork: Result {
val orderId = inputData.getString
: return Result.failure
return try {
repository.syncOrder
Result.success
} catch {
Result.retry
} catch {
Result.failure
}
}
companion object {
const val KEY_ORDER_ID = "order_id"
}
}

构造参数中只传轻量标识，不要把完整订单序列化进 Data。说起来，Data 有大小限制。而且任务真正执行时提交时的数据快照可能已经过期。说起来，更稳妥的做法是传入主键。Worker 再从 Room 读取最新记录。

如果项目使用 Hilt，可以配合 @HiltWorker 和 HiltWorkerFactory 注入仓库。无论采用哪种方式，都应避免在 Worker 中临时拼装一套网络层和数据库。 因为这会绕开应用统一的超时、鉴权和日志策略。

User Pain Point: 参数泄露与数据不一致

- 将完整对象放进 Data 会触发序列化异常并导致调度失败。- 如果在 Worker 内部重新创建网络客户端。而不是使用全局单例，会导致请求头部缺失鉴权信息，引发 401 错误。

用约束表达执行前提

同步订单至少需要网络。如果上传内容较大，还可以要求非低电量状态：

val constraints = Constraints.Builder
.setRequiredNetworkType
.setRequiresBatteryNotLow
.build
val request = OneTimeWorkRequestBuilder
.setInputData)
.setConstraints
.build

约束是调度条件，不是业务校验。网络条件满足时仍可能遇到 DNS 错误、连接超时或服务端限流，所以 doWork 内依然要处理失败。相反，也不要设置不必要的约束，例如小体积 JSON 同步通常无需强制未计量网络。否则任务可能长期等待 Wi‑Fi。不过，

User Pain Point: 约束设置过严导致任务卡死

•  开发者把“仅在充电且 Wi‑Fi”作为唯一约束来同步一次性日志。结果使用者在没有充电状态下长时间看不到日志上报。
•  根据业务紧急程度分层约束——高优先级数据使用 .setRequiredNetworkType,低优先级可接受任意网络。

唯一任务避免重复排队

使用者连续点击提交、页面重建或应用启动补偿都可能触发调度。如果每次都调用 enqueue,同一订单会进入多份工作请求。

fun enqueueOrderSync {
val request = OneTimeWorkRequestBuilder
.setInputData)
.setConstraints
.setBackoffCriteria(
BackoffPolicy.EXPONENTIAL,10L。TimeUnit.SECONDS
)
.addTag
.addTag
.build
WorkManager.getInstance.enqueueUniqueWork(
"order-sync:$orderId",ExistingWorkPolicy.KEEP,// KEEP / REPLACE / APPEND 根据业务决定
request
)
}

KEEP 表示已有未完成任务时忽略新请求，适合“同一对象最终同步一次”的场景。其实，REPLACE 会取消旧任务并创建新任务。适合参数变化后只关心最新结果的场景。怎么说呢，APPEND 用于必须顺序执行的任务链。但如果前置任务失败，后续工作也可能无法运行，选择时要结合业务语义。

User Pain Point: 即使使用唯一工作名。也仍然会出现服务器端重复写入，因为 Worker 在发送请求后进程被杀，在恢复后 提交。这就要求业务层具备幂等能力。

幂等是最终一致性的主要

User Pain Point: 缺乏幂等键导致同一订单在网络抖动期间被多次创建，同步成功次数不可预测。

interface OrderApi {
@POST
suspend fun syncOrder(
@Header operationId: String,@Body request: SyncOrderRequest
): SyncOrderResponse
}

The server stores idempotency key toger with processing result. Subsequent calls with same key return stored result instead of creating a duplicate order.

database.withTransaction {
val order = orderDao.findById?: return@withTransaction
val response = api.syncOrder)
orderDao.markSynced
}

If local record changes while uploading,keep new “pending” flag and do not overwrite it with an old response. This prevents stale data from corrupting final state.

User Pain Point: 区分可重试与永久失败困难

...