鸿蒙架构进阶 02：离线优先架构与本地队列同步实战

雷霆牛逼克拉斯

24人浏览 · 2026-10-22 15:40:08

雷霆牛逼克拉斯 · 2026-10-22 15:40:08 发布

开篇：地铁里没网，用户点个赞按钮直接转圈圈

很多应用的体验极差，就是因为它是“网络优先”的。

用户在电梯里、地铁上，点个收藏，或者发个评论，按钮直接开始转圈，转了几秒钟弹个 Toast：“网络异常”。用户刚才的编辑内容全丢了，或者操作直接失败。

在这个网络无处不在又随时可能断开的时代，“离线优先（Offline First）” 架构才是留住用户的王道。

用户不管有没有网，点按钮立刻成功（UI 立刻更新），数据先存本地。等网络恢复了，再悄悄在后台把数据同步到服务器。这就是所谓的“乐观更新（Optimistic UI）”和“本地队列”。

https://placeholder-01.jpg/

一、架构设计：本地数据库是“唯一真相”

在这套架构里，UI 渲染的数据永远来自本地数据库（RDB），而不是网络请求的直接返回。

核心流程：

用户操作 -> 写入本地 RDB -> 状态标记为 PENDING（待同步）。
UI 监听 RDB，数据一变，界面立刻刷新。
网络恢复（或定时器触发） -> 后台读取 PENDING 的数据 -> 发送网络请求。
请求成功 -> 更新 RDB 状态为 SYNCED（已同步）。

二、建表与状态设计

我们需要一个表来存业务数据，以及一个表来存操作队列。

typescript

// 1. 业务表
const SQL_TODO = `
  CREATE TABLE IF NOT EXISTS todo (
    id TEXT PRIMARY KEY,
    title TEXT,
    isCompleted INTEGER,
    syncStatus INTEGER -- 0: 待同步, 1: 已同步
  )
`;

// 2. 操作队列表（处理复杂的增删改顺序）
const SQL_QUEUE = `
  CREATE TABLE IF NOT EXISTS sync_queue (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    actionType TEXT, -- 'INSERT', 'UPDATE', 'DELETE'
    entityId TEXT,
    payload TEXT, -- JSON数据
    retryCount INTEGER DEFAULT 0
  )
`;

三、写入与触发同步

当用户添加一条待办：

typescript

async function addTodo(title: string) {
  const id = generateUUID();
  // 1. 写业务表
  await rdbStore.insert('todo', { id, title, isCompleted: 0, syncStatus: 0 });
  
  // 2. 写同步队列
  await rdbStore.insert('sync_queue', {
    actionType: 'INSERT',
    entityId: id,
    payload: JSON.stringify({ id, title })
  });

  // 3. 通知 UI 刷新（如果没用 DataObserver，可以用 EventHub）
  eventHub.emit('TODO_CHANGED');
  
  // 4. 尝试触发同步
  triggerSync();
}

triggerSync 是核心。你不能同步队列里有一万条数据就发一万个请求，得批量。

typescript

import networkObserver from '@ohos.net.connection';

let isSyncing = false;

async function triggerSync() {
  if (isSyncing) return;
  // 检查网络
  if (!hasNetwork()) return;

  isSyncing = true;
  try {
    // 从队列中取一批（比如 10 条）
    const queueItems = await getQueueItems(10);
    if (queueItems.length === 0) return;

    // 组装成批量接口发给服务端
    const response = await api.syncBatch(queueItems);
    
    if (response.success) {
      // 删掉已成功的队列数据
      await removeQueueItems(queueItems.map(i => i.id));
      // 更新业务表状态
      await updateTodoStatusToSynced(queueItems);
    }
  } catch (err) {
    // 失败处理：增加 retryCount
    await incrementRetry(queueItems);
  } finally {
    isSyncing = false;
    // 如果还有数据，继续同步
    triggerSync();
  }
}

注意那个 if (isSyncing) return;。 如果你不加这个锁，用户疯狂点按钮，会触发几百次同步，服务端直接把你 IP 封了。