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

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

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

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

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

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

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

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

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

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

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

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

同步事件要带对象版本

exportenumSyncEventType{Create='create',Update='update',Delete='delete'}exportinterfaceSyncEvent{eventId:stringobjectId:stringeventType:SyncEventType serverVersion:numberpayloadJson:stringarrivedAt:number}exportinterfaceLocalRecord{objectId:stringserverVersion:numberdeleted:booleancontentJson:string}

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

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

入箱先去重，再消费

exportclassSyncInbox{constructor(privatereadonlystore:SyncEventStore){}asyncaccept(event:SyncEvent):Promise<void>{if(awaitthis.store.exists(event.eventId)){return}awaitthis.store.insert(event)}asyncnextBatch(limit:number):Promise<SyncEvent[]>{returnthis.store.findPendingOrdered(limit)}}

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

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

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

exportclassSyncEventConsumer{constructor(privatereadonlyrepository:NoteRepository){}asyncconsume(event:SyncEvent):Promise<void>{constcurrent=awaitthis.repository.findById(event.objectId)if(current!==null&&event.serverVersion<=current.serverVersion){return}if(event.eventType===SyncEventType.Delete){awaitthis.repository.saveTombstone(event.objectId,event.serverVersion)return}awaitthis.repository.save({objectId:event.objectId,serverVersion:event.serverVersion,deleted:false,contentJson:event.payloadJson})}}

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

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

页面只刷新派生摘要

@Componentstruct NoteHomePage{@Statesummary:NoteHomeSummary=createEmptyNoteSummary()privatesummaryService:NoteSummaryService=createNoteSummaryService()asynconShown():Promise<void>{this.summary=awaitthis.summaryService.loadHomeSummary()}asynconSyncConsumed():Promise<void>{this.summary=awaitthis.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 仲裁，删除保留墓碑，页面只读取本地派生结果。这样网络乱序不会变成数据乱序。