## Android 离线同步问题

Android 离线同步 一旦出问题，现场通常不会只报一个错，而是先从 很多团队已经不缺网络请求封装，真正难的是断网、重试、补偿和多端写入冲突怎么稳住数据一致性。 这种工程背景里放大成连锁反应。我先看的不是‘哪里报错’，而是 Android 离线同步 在 Android网络编程 里究竟卡在入口、状态迁移，还是回调落库这三段链路中的哪一段。这类故障最烦的地方在于它经常伪装成偶发成功，但真正的根因往往就藏在 本地待同步队列没有幂等键、前后台同时触发同步导致重复提交 这一类边界条件里。

## 方案先给到

这类文章最怕写成过程回忆录，我更倾向于直接给出能落地的最短修复路径：先观测、再收敛、最后补回归。如果一次同时改调度、配置和状态机，副作用会叠在一起，所以最好按照‘先补证据，再改行为，最后压回归’的顺序推进。我会先补 为同步任务建立队列深度与失败原因监控，再收紧 把本地事务提交和远端 ack 映射成明确状态机，最后把 对高风险写操作补充冲突合并与人工兜底 补齐。这个顺序的好处是改动小、回归快、证据也更容易收口。

## Android 离线同步关键实现

下面这组片段按 Android 离线同步 的真实处理顺序展开：先贴核心实现，再给排查命令，最后补一段修复辅助代码。我故意把示例压成能直接复制的大小，目标不是讲概念，而是让 Android网络编程 场景能马上动手验证。

1. 关键实现

@Entity(tableName = "pending_sync")
data class PendingSyncEntity(
    @PrimaryKey val id: String,
    val payload: String,
    val state: String,
    val updatedAt: Long
)

class SyncWorker(
    appContext: Context,
    params: WorkerParameters
) : CoroutineWorker(appContext, params) {
    override suspend fun doWork(): Result {
        return Result.retry()
    }
}

2. 先跑这些命令

adb shell dumpsys jobscheduler | findstr SyncWorker
adb shell am broadcast -a androidx.work.diagnostics.REQUEST_DIAGNOSTICS -p com.example.app

3. 修复辅助代码

data class WangluobianchengCheckResult(
    val key: String,
    val ok: Boolean,
    val detail: String
)

fun verifyWangluobianchengState(key: String, expected: String, actual: String): WangluobianchengCheckResult {
    val ok = expected == actual
    return WangluobianchengCheckResult(key, ok, if (ok) "matched" else "$expected != $actual")
}

## 这些边界先看

一次只动一个风险点，改完立刻回归。补丁叠得太厚，最后往往只剩‘好像好了’这种没法验收的结论。线上偶发成功不能算修好，只要还有一小批失败样本解释不通，就继续往下挖，不要提前收口。如果这篇文章是给团队复用的，最值钱的不是大道理，而是‘出现什么信号就别继续查 A，直接切去查 B’这种分叉提示。

## Android 离线同步报错与排查

1. 状态不一致

如果现场出现旧数据覆盖新数据、页面恢复后状态倒退，先用 WorkManager Inspector 对齐时间线，再核对本地状态迁移是不是原子提交。把请求发出、回包落库、UI 消费三段时间顺序排清楚，根因通常会自己浮出来。

adb shell dumpsys jobscheduler | findstr SyncWorker
adb shell am broadcast -a androidx.work.diagnostics.REQUEST_DIAGNOSTICS -p com.example.app

2. 多入口重复跑

如果后台恢复、重试或多入口并发后任务跑了两次，优先补幂等键、唯一调度名和入口锁，再回头核对 把本地事务提交和远端 ack 映射成明确状态机 有没有被真正收紧。别只看业务日志，还要确认调度层是不是只进了一次。

fun wangluobianchengWorkName(id: String): String {
    return "wangluobiancheng-$id"
}

fun shouldSkipWangluobiancheng(running: Boolean, hasPending: Boolean): Boolean {
    return running || hasPending
}

## Android 离线同步可运行片段

最后留一个最小可运行片段，重点不是完整业务，而是让 Android 离线同步 能在本地快速复现、快速验证。这段最适合直接扔进 demo、测试工程或排障脚本库里，后面团队再回头看 Android网络编程 的问题时能直接复用。真正有价值的最小样例，必须保留最短入口、最少依赖和明确输出，这样复现、修复、回归三步才能连起来。

1. 先定义状态对象

data class WangluobianchengState(
    val id: String,
    val status: String,
    val updatedAt: Long,
    val source: String
)

2. 启动验证入口

fun runWangluobianchengDemo() {
    val state = WangluobianchengState("42", "pending", System.currentTimeMillis(), "wangluobiancheng")
    println(state)
}

3. 本地验证命令

adb shell dumpsys jobscheduler | findstr SyncWorker
adb shell am broadcast -a androidx.work.diagnostics.REQUEST_DIAGNOSTICS -p com.example.app
adb logcat -d | findstr /I "Exception timeout retry"