HarmonyOS 离线缓存恢复实战：缓存、队列、冲突与重试

HarmonyOS 离线缓存恢复实战：缓存、队列、冲突与重试

移动应用不能假设网络永远可用。用户在地铁里收藏路线、离线编辑草稿、修改设置、提交反馈，可能都发生在弱网或无网环境。如果应用只在接口成功后更新页面，离线时就完全不可用；如果只写本地不管同步，联网后又会出现数据冲突。离线缓存恢复要解决的是：断网时可用，联网后可追，冲突时可解释，失败后能重试。

本文围绕四个环节：

1. 本地缓存保存可读数据，不让页面空白。
2. 待同步队列记录离线操作，不丢用户动作。
3. 冲突解决器比较版本，不盲目覆盖云端。
4. 重试调度控制节奏，不无限请求接口。

1. 离线优先不是只缓存接口结果

只把接口响应保存下来，最多解决“没网能看旧数据”。真正的离线优先还要处理用户操作：新增、修改、删除都要进入待同步队列，等网络恢复后按顺序重放。

离线缓存的目标不是让所有功能都离线可用，而是把关键用户动作保存下来，并在恢复网络后有序处理。

2. 数据持久化资料边界和工程目录

HarmonyOS 提供 Preferences、RDB、文件等本地持久化能力。离线缓存通常会组合使用：小配置放 Preferences，结构化缓存和队列放 RDB，附件文件单独管理。

建议目录：

entry/src/main/ets/
  common/offline/LocalCache.ets
  common/offline/PendingQueue.ets
  common/offline/ConflictResolver.ets
  common/offline/RetryScheduler.ets
  common/offline/SyncReport.ets
  pages/route/RouteDraftPage.ets

页面只关心“当前可展示数据”和“同步状态”，不直接操作队列。

3. LocalCache 保存页面可读数据

本地缓存要有更新时间和来源。页面看到缓存数据时，可以提示“离线内容，稍后同步”。

export interface CachedRouteDraft {
  id: string
  title: string
  content: string
  updatedAt: number
  source: 'local' | 'remote'
}

export class LocalCache {
  private readonly drafts = new Map<string, CachedRouteDraft>()

  saveDraft(draft: CachedRouteDraft): void {
    this.drafts.set(draft.id, { ...draft, updatedAt: Date.now() })
  }

  getDraft(id: string): CachedRouteDraft | undefined {
    const draft = this.drafts.get(id)
    return draft ? { ...draft } : undefined
  }
}

示例用内存表达规则，真实项目应落到 RDB。关键是缓存对象要包含 updatedAt 和 source，方便后续冲突判断。

4. PendingQueue 记录离线操作

用户离线编辑不是直接覆盖缓存就结束，还要生成一条待同步操作。操作需要有唯一 ID、类型、业务对象、重试次数和状态。

export type OfflineActionType = 'CREATE' | 'UPDATE' | 'DELETE'
export type QueueState = 'PENDING' | 'SYNCING' | 'DONE' | 'FAILED'

export interface PendingAction {
  actionId: string
  type: OfflineActionType
  entityId: string
  payload: Record<string, Object>
  state: QueueState
  retryCount: number
  createdAt: number
}

export class PendingQueue {
  private readonly actions: PendingAction[] = []

  enqueue(type: OfflineActionType, entityId: string, payload: Record<string, Object>): PendingAction {
    const action: PendingAction = {
      actionId: `op_${Date.now()}_${Math.floor(Math.random() * 10000)}`,
      type,
      entityId,
      payload,
      state: 'PENDING',
      retryCount: 0,
      createdAt: Date.now()
    }
    this.actions.push(action)
    return action
  }

  nextPending(): PendingAction | undefined {
    return this.actions.find(action => action.state === 'PENDING')
  }
}

待同步队列让离线操作有证据。网络恢复后，系统知道应该同步什么，而不是只知道“本地数据变了”。

5. ConflictResolver 比较版本

冲突不是错误，而是离线应用必须面对的状态。比如用户在手机离线修改草稿，同时平板在线修改了同一条。恢复网络后需要比较版本，并选择策略。

export interface VersionedRecord {
  id: string
  content: string
  version: number
  updatedAt: number
}

export type ConflictStrategy = 'LOCAL_FIRST' | 'REMOTE_FIRST' | 'MANUAL_MERGE'

export class ConflictResolver {
  resolve(local: VersionedRecord, remote: VersionedRecord): ConflictStrategy {
    if (local.version === remote.version) {
      return 'LOCAL_FIRST'
    }
    if (remote.updatedAt > local.updatedAt && local.content !== remote.content) {
      return 'MANUAL_MERGE'
    }
    return local.updatedAt >= remote.updatedAt ? 'LOCAL_FIRST' : 'REMOTE_FIRST'
  }
}

自动合并适合简单字段，文本、路线、订单备注这类内容建议进入人工确认页，避免静默覆盖。

6. RetryScheduler 控制重试节奏

同步失败不能立刻无限重试。重试要有最大次数和退避间隔，同时给用户一个“稍后自动同步”的提示。

export class RetryScheduler {
  getNextDelayMs(retryCount: number): number {
    const base = 3000
    const max = 5 * 60 * 1000
    return Math.min(base * Math.pow(2, retryCount), max)
  }

  canRetry(action: PendingAction): boolean {
    return action.retryCount < 5 && action.state !== 'DONE'
  }
}

退避重试能减少弱网下的耗电和接口压力。失败次数达到上限后，应进入可见的失败状态。

7. 同步执行器要按顺序处理

队列重放要按创建时间处理，避免先更新后创建、先删除后修改这类顺序错误。

export interface SyncClient {
  push(action: PendingAction): Promise<'ok' | 'conflict' | 'failed'>
}

export class OfflineSyncRunner {
  constructor(private readonly queue: PendingQueue, private readonly client: SyncClient) {}

  async syncOnce(): Promise<string> {
    const action = this.queue.nextPending()
    if (!action) {
      return '没有待同步操作'
    }
    action.state = 'SYNCING'
    const result = await this.client.push(action)
    if (result === 'ok') {
      action.state = 'DONE'
      return `同步成功：${action.actionId}`
    }
    action.retryCount += 1
    action.state = result === 'conflict' ? 'FAILED' : 'PENDING'
    return `同步未完成：${result}`
  }
}

这里把冲突和普通失败区分开。冲突需要用户或业务规则处理，普通失败可以继续重试。

8. 页面要展示离线状态和失败原因

用户需要知道当前数据是否已经同步。不要只在后台默默重试，否则用户会误以为内容已经保存到云端。

export interface OfflineViewState {
  banner: string
  canEdit: boolean
  actionText: string
}

export function buildOfflineView(isOnline: boolean, pendingCount: number, failedCount: number): OfflineViewState {
  if (!isOnline) {
    return { banner: `离线模式，已有 ${pendingCount} 个操作待同步`, canEdit: true, actionText: '本地保存' }
  }
  if (failedCount > 0) {
    return { banner: `${failedCount} 个操作同步失败，请查看原因`, canEdit: true, actionText: '重试同步' }
  }
  if (pendingCount > 0) {
    return { banner: `正在同步 ${pendingCount} 个操作`, canEdit: true, actionText: '同步中' }
  }
  return { banner: '数据已同步', canEdit: true, actionText: '保存' }
}

离线提示不是打扰用户，而是建立预期。用户知道“本地已保存，稍后同步”，就不会误会数据丢失。

9. 离线缓存验收动作

可以加入队列一致性断言：

export function assertQueueAction(action: PendingAction): void {
  if (!action.actionId || !action.entityId) {
    throw new Error('离线操作必须包含 actionId 和 entityId')
  }
  if (action.retryCount < 0 || action.retryCount > 5) {
    throw new Error('重试次数超出允许范围')
  }
}

这个断言能防止队列写入脏数据，尤其适合离线编辑入口。

10. 离线同步异常排查表

离线问题的排查顺序要从用户动作开始，而不是从接口日志开始。先确认本地是否生成操作号，再看队列是否持久化，然后才看网络恢复后的接口结果。否则很容易把“动作根本没入队”误判成“同步接口失败”。

如果用户反馈“我明明保存了”，开发要能回答三个问题：本地缓存有没有这条数据，队列里有没有这次操作，云端返回了什么结果。三者缺一项，离线恢复链路就不完整。

离线缓存恢复复现场景：给读者一组可执行核验

离线队列要验证断网、重启、恢复网络和冲突处理。否则只证明缓存存在，没有证明业务能恢复。

interface OfflineReplayCase {
  queueId: any
  offlineAt: any
  replayedCount: any
  conflictPolicy: any
}

const replay81: OfflineReplayCase = {
  queueId: 'sample',
  offlineAt: 'sample',
  replayedCount: 'sample',
  conflictPolicy: 'sample',
}

function assertReplay81(item: OfflineReplayCase): void {
  if (item.replayedCount < 0) throw new Error('离线重放数量异常')
}

这组核验把断网期间的队列和恢复后的重放结果放到一条记录里，便于确认离线链路完整。

11. 小结：离线恢复要让用户动作不丢

离线缓存的核心不是把页面缓存下来，而是保护用户动作。页面可读数据进入 LocalCache，离线操作进入 PendingQueue，冲突由 ConflictResolver 解释，失败由 RetryScheduler 控制节奏。只要这条链路闭合，弱网、断网、重启和冲突都不会让用户觉得数据凭空消失。