40-多端同步消息顺序乱-用本地事件序号和幂等消费收口

第40篇｜多端同步消息顺序乱：用本地事件序号和幂等消费收口

摘要：多端同步最怕“看起来同步了，顺序却乱了”。新增、编辑、删除从不同设备回来，如果页面直接按到达顺序更新，很容易旧事件覆盖新状态。更稳的做法是所有远端事件先入本地收件箱，按对象版本和事件序号幂等消费，消费失败留下冲突日志，而不是悄悄改页面。

一个笔记应用里，手机端编辑标题，平板端马上删除同一条笔记。服务端事件先推来了编辑，后推来了删除，本地页面短暂显示新标题，几秒后又恢复了旧列表。用户以为删除失败，其实是客户端直接按到达顺序改 UI，没有给事件序号和对象版本一个明确的仲裁位置。

这篇文章解决四个实际问题：

1. 把远端事件先写入 SyncInbox，不直接改页面。
2. 用 objectId、serverVersion、eventId 做幂等和顺序判断。
3. 消费后更新本地原始记录，再派生页面摘要。
4. 冲突进入日志表，给用户或调试工具可见证据。

先确认乱的是到达顺序还是业务顺序

网络事件到达顺序不等于业务发生顺序。同步问题要先看 eventId、serverVersion 和对象当前版本，而不是只看日志打印先后。

这一步的价值是先把问题放回运行链路。只要能确认问题停在哪个位置，后面就不用靠猜测改页面。

同步事件不应该直接碰页面状态

页面展示的是本地数据的派生结果。远端事件先进入同步层，再由本地仓储更新原始记录，最后页面刷新摘要。

边界定清后，代码就不会在页面、服务和回调之间来回复制同一段判断。后续新增场景也能先判断应该落在哪一层。

同步事件要带对象版本

export enum SyncEventType {
  Create = 'create',
  Update = 'update',
  Delete = 'delete'
}

export interface SyncEvent {
  eventId: string
  objectId: string
  eventType: SyncEventType
  serverVersion: number
  payloadJson: string
  arrivedAt: number
}

export interface LocalRecord {
  objectId: string
  serverVersion: number
  deleted: boolean
  contentJson: string
}

serverVersion 用来判断事件新旧，eventId 用来判断是否重复，deleted 用来表达墓碑状态，避免旧更新把已删除对象复活。

这类模型最好放在 models 或 common 中，页面、Service 和仓储都使用同一份类型，避免各层用字符串互相猜。

入箱先去重，再消费

export class SyncInbox {
  constructor(private readonly store: SyncEventStore) {}

  async accept(event: SyncEvent): Promise<void> {
    if (await this.store.exists(event.eventId)) {
      return
    }
    await this.store.insert(event)
  }

  async nextBatch(limit: number): Promise<SyncEvent[]> {
    return this.store.findPendingOrdered(limit)
  }
}

收事件和消费事件分开。即使前台页面不在，事件也能先落进本地收件箱；等消费器可用时再按规则处理。

Service 的目标不是把所有逻辑都塞进去，而是把跨页面、跨生命周期或需要持久化的判断集中起来。页面只表达用户动作。

消费者按版本推进本地记录

export class SyncEventConsumer {
  constructor(private readonly repository: NoteRepository) {}

  async consume(event: SyncEvent): Promise<void> {
    const current = await this.repository.findById(event.objectId)
    if (current !== null && event.serverVersion <= current.serverVersion) {
      return
    }

    if (event.eventType === SyncEventType.Delete) {
      await this.repository.saveTombstone(event.objectId, event.serverVersion)
      return
    }

    await this.repository.save({
      objectId: event.objectId,
      serverVersion: event.serverVersion,
      deleted: false,
      contentJson: event.payloadJson
    })
  }
}

这个消费者不按到达顺序信任事件，而是按对象版本推进。删除被保存成墓碑，能挡住更早版本的更新事件。

页面层要控制展示和交互节奏，但不应该拥有底层事实。这样页面重建、横竖屏变化或返回前台时，都能重新从 Service 拿到可信结果。

页面只刷新派生摘要

@Component
struct NoteHomePage {
  @State summary: NoteHomeSummary = createEmptyNoteSummary()
  private summaryService: NoteSummaryService = createNoteSummaryService()

  async onShown(): Promise<void> {
    this.summary = await this.summaryService.loadHomeSummary()
  }

  async onSyncConsumed(): Promise<void> {
    this.summary = await this.summaryService.loadHomeSummary()
  }
}

页面不消费远端事件，也不自己合并内容。它只在同步消费完成后重新读取派生摘要，避免 UI 和本地仓储出现两套真相。

实际项目里，很多问题不是第一次进入页面暴露，而是在冷启动、返回前台、页面重建或回调晚到时暴露。把这段生命周期补上，修复才算闭环。

冲突要留下日志，不要静默覆盖

兜底路径不是可有可无。用户遇到异常时，页面至少要给出当前状态、可执行动作和可排查线索。

排查时找直接改 UI 的同步代码

rg -n "SyncEvent|serverVersion|eventId|tombstone|deleted" entry features common
rg -n "onMessage|receiver|websocket|push.*sync" entry features common
rg -n "@State.*list|summary.*=.*event|payloadJson" entry features common

第一组命令找旧路径，第二组命令找新边界，第三组命令看生命周期或回调位置。命中后不要只看字段名，要判断它是否仍在直接改页面状态。

落地时要分清事件日志和业务记录

同步链路里有两类数据很容易混在一起：一类是业务记录，比如笔记、订单、任务；另一类是事件日志，比如服务端推来的“更新”“删除”“恢复”。业务记录决定页面展示，事件日志决定这次同步有没有被处理过。

如果项目只保存业务记录，不保存事件处理痕迹，重复推送和乱序推送就很难解释。反过来，如果页面直接读事件日志，也会把“待处理事件”误当成真实业务状态。我的建议是：页面永远读业务记录或摘要，同步调试面板才读事件日志。

验证清单

这些验证最好在真机或模拟器里按顺序走一遍。只看源码很难发现冷启动、重启和回调晚到这类问题。

常见问题和处理方式

如果现象没有出现在表里，仍然建议按“输入来源 -> 中间状态 -> 持久化或页面展示 -> 失败兜底”的顺序排查。

小结：同步要按版本消费，不按到达顺序相信

多端同步不是把远端消息直接贴到页面。事件先入箱，消费时按 eventId 幂等、按 serverVersion 仲裁，删除保留墓碑，页面只读取本地派生结果。这样网络乱序不会变成数据乱序。
ox 先判重 |

如果现象没有出现在表里，仍然建议按“输入来源 -> 中间状态 -> 持久化或页面展示 -> 失败兜底”的顺序排查。

小结：同步要按版本消费，不按到达顺序相信

多端同步不是把远端消息直接贴到页面。事件先入箱，消费时按 eventId 幂等、按 serverVersion 仲裁，删除保留墓碑，页面只读取本地派生结果。这样网络乱序不会变成数据乱序。