## Android 离线同步问题

Android 离线同步 这类问题通常直接表现为状态错乱、结果回滚、重复执行或界面没刷新。先不要写长背景，先锁复现条件、触发入口和错误信号。如果你在 Android网络编程 场景里遇到同类故障，优先看线程切换、生命周期边界、幂等键和状态落库是否一致。排查顺序建议固定成“先看输入，再看状态迁移，最后看异步回调”，这样能更快把噪音排掉，避免一开始就陷进大范围搜索。真正拖慢排障的通常不是代码太少，而是现场信号分散：日志打一套、监控打一套、数据库状态又是另一套，必须先把它们对齐。

## 方案先给到

先做三件事：补 为同步任务建立队列深度与失败原因监控、收紧 把本地事务提交和远端 ack 映射成明确状态机、最后补上 对高风险写操作补充冲突合并与人工兜底。这样改动最短，也最容易回归。实现上优先保留现有链路，只替换高风险节点，不把文章写成过程回忆录。如果一次要改配置、状态机和调度策略，建议先把观测补齐再改行为，不然修复和副作用会一起出现，回归结论很难站稳。方案设计时最好明确“谁负责产生状态、谁负责消费状态、谁负责兜底重试”，避免同一份数据在多层都能写，最后谁都说不清。

## 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. 修复辅助代码

fun guardState(expected: String, actual: String) {
    check(expected == actual) { "state mismatch: $expected != $actual" }
}

fun logCost(tag: String, costMs: Long) {
    if (costMs > 200) println("$tag slow=$costMs")
}

## 这些边界先看

先盯这三类坑：本地待同步队列没有幂等键；前后台同时触发同步导致重复提交；服务端回包成功但本地状态没有原子更新。这类问题大多不是 API 不通，而是边界没收住。每次只改一个风险点，改完立刻回归，避免多个补丁叠在一起后无法定位副作用。线上高频误判是把偶发成功当成修复成功。只要还有少量失败样本没解释清楚，就不要急着关单。

另外别忽略 WorkManager Inspector、Room Database Inspector、adb shell dumpsys jobscheduler 这类现成观测手段，很多时候不是没有证据，而是证据没被串成一条线。坑点能提前列出来，团队后续接手时会少绕很多弯。如果文章要给团队复用，最好顺手写出“什么信号出现时不要继续怀疑 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. 任务重复执行

如果后台恢复、重试或多入口同时触发后任务跑了两次，优先补幂等键、唯一 work name 或单航班锁。别只看业务日志，还要看调度层是否真的只进了一次入口。

fun uniqueWorkName(id: String) = "sync-$id"

fun shouldSkip(running: Boolean): Boolean {
    return running
}

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

最后留一个最小可运行片段，目标不是讲原理，而是让 Android 离线同步 能马上在本地起一个验证样例。如果你在团队里做知识沉淀，这一段最适合直接放进 demo、测试工程或排障脚本仓库，后续复盘时能反复复用。最小样例的价值在于它能把讨论从抽象描述拉回到可执行输入输出，复现、修复、回归都更省时间。写 runnable 片段时尽量保留最少依赖、最短入口和可观察输出，不要把真正的验证步骤藏进省略号或口头说明里。只要本地能稳定复现一次，再把修复版跑通一次，这篇文章就从“看起来像经验”变成了“可以拿去复用的处理模板”。

1. 最小数据结构

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

2. 最小执行入口

fun runDemo() {
    val state = SyncState("42", "pending", System.currentTimeMillis())
    println(state)
}

3. 本地验证命令

./gradlew testDebugUnitTest
adb logcat -d | findstr /I "Exception state retry"