第40篇多端同步消息顺序乱用本地事件序号和幂等消费收口摘要多端同步最怕“看起来同步了顺序却乱了”。新增、编辑、删除从不同设备回来如果页面直接按到达顺序更新很容易旧事件覆盖新状态。更稳的做法是所有远端事件先入本地收件箱按对象版本和事件序号幂等消费消费失败留下冲突日志而不是悄悄改页面。一个笔记应用里手机端编辑标题平板端马上删除同一条笔记。服务端事件先推来了编辑后推来了删除本地页面短暂显示新标题几秒后又恢复了旧列表。用户以为删除失败其实是客户端直接按到达顺序改 UI没有给事件序号和对象版本一个明确的仲裁位置。这篇文章解决四个实际问题把远端事件先写入 SyncInbox不直接改页面。用 objectId、serverVersion、eventId 做幂等和顺序判断。消费后更新本地原始记录再派生页面摘要。冲突进入日志表给用户或调试工具可见证据。先确认乱的是到达顺序还是业务顺序网络事件到达顺序不等于业务发生顺序。同步问题要先看 eventId、serverVersion 和对象当前版本而不是只看日志打印先后。位置现象风险处理方向旧编辑晚到标题被旧值覆盖没有版本判断低版本事件跳过删除后又出现编辑事件复活已删对象删除状态不是终态墓碑记录重复推送同一事件消费两次没有 eventId 幂等消费表去重页面闪烁收到事件直接改 UI缺少本地入箱统一消费后刷新这一步的价值是先把问题放回运行链路。只要能确认问题停在哪个位置后面就不用靠猜测改页面。同步事件不应该直接碰页面状态页面展示的是本地数据的派生结果。远端事件先进入同步层再由本地仓储更新原始记录最后页面刷新摘要。模块应该负责不应该负责SyncReceiver原始事件和来源设备页面列表SyncInbox待消费事件、重试次数业务 UI 文案EventConsumer版本仲裁和幂等组件布局Repository本地原始记录和墓碑远端连接状态SummaryService页面卡片和统计事件传输细节边界定清后代码就不会在页面、服务和回调之间来回复制同一段判断。后续新增场景也能先判断应该落在哪一层。同步事件要带对象版本exportenumSyncEventType{Createcreate,Updateupdate,Deletedelete}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):Promisevoid{if(awaitthis.store.exists(event.eventId)){return}awaitthis.store.insert(event)}asyncnextBatch(limit:number):PromiseSyncEvent[]{returnthis.store.findPendingOrdered(limit)}}收事件和消费事件分开。即使前台页面不在事件也能先落进本地收件箱等消费器可用时再按规则处理。Service 的目标不是把所有逻辑都塞进去而是把跨页面、跨生命周期或需要持久化的判断集中起来。页面只表达用户动作。消费者按版本推进本地记录exportclassSyncEventConsumer{constructor(privatereadonlyrepository:NoteRepository){}asyncconsume(event:SyncEvent):Promisevoid{constcurrentawaitthis.repository.findById(event.objectId)if(current!nullevent.serverVersioncurrent.serverVersion){return}if(event.eventTypeSyncEventType.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:NoteHomeSummarycreateEmptyNoteSummary()privatesummaryService:NoteSummaryServicecreateNoteSummaryService()asynconShown():Promisevoid{this.summaryawaitthis.summaryService.loadHomeSummary()}asynconSyncConsumed():Promisevoid{this.summaryawaitthis.summaryService.loadHomeSummary()}}页面不消费远端事件也不自己合并内容。它只在同步消费完成后重新读取派生摘要避免 UI 和本地仓储出现两套真相。实际项目里很多问题不是第一次进入页面暴露而是在冷启动、返回前台、页面重建或回调晚到时暴露。把这段生命周期补上修复才算闭环。冲突要留下日志不要静默覆盖情况页面表现工程处理低版本事件跳过并记录 objectId说明本地已有更新版本删除后更新保留墓碑记录迟到更新payload 解析失败事件保留待重试不要改本地记录连续失败进入冲突日志提供人工恢复入口兜底路径不是可有可无。用户遇到异常时页面至少要给出当前状态、可执行动作和可排查线索。排查时找直接改 UI 的同步代码rg-nSyncEvent|serverVersion|eventId|tombstone|deletedentry features common rg-nonMessage|receiver|websocket|push.*syncentry features common rg-nState.*list|summary.*.*event|payloadJsonentry features common第一组命令找旧路径第二组命令找新边界第三组命令看生命周期或回调位置。命中后不要只看字段名要判断它是否仍在直接改页面状态。落地时要分清事件日志和业务记录同步链路里有两类数据很容易混在一起一类是业务记录比如笔记、订单、任务另一类是事件日志比如服务端推来的“更新”“删除”“恢复”。业务记录决定页面展示事件日志决定这次同步有没有被处理过。数据保存目的生命周期LocalRecord给页面和业务查询使用直到用户删除或被同步删除SyncEvent保证事件可重试、可幂等成功消费后可归档ConflictLog留下无法自动处理的证据人工处理或下次版本修复后清理Tombstone防止旧更新复活已删对象等服务端确认安全后再压缩如果项目只保存业务记录不保存事件处理痕迹重复推送和乱序推送就很难解释。反过来如果页面直接读事件日志也会把“待处理事件”误当成真实业务状态。我的建议是页面永远读业务记录或摘要同步调试面板才读事件日志。验证清单验证项预期结果重复 eventId只消费一次低版本编辑晚到不会覆盖新内容删除后编辑到达对象保持删除态payload 解析失败事件可重试本地不变页面回前台摘要来自仓储重算这些验证最好在真机或模拟器里按顺序走一遍。只看源码很难发现冷启动、重启和回调晚到这类问题。常见问题和处理方式现象常见原因处理方式删除后又出现没有墓碑保存 deleted 终态列表闪烁事件直接改页面消费完成后统一刷新旧内容覆盖新内容缺少版本判断按 serverVersion 推进重复执行没有 eventId 去重SyncInbox 先判重如果现象没有出现在表里仍然建议按“输入来源 - 中间状态 - 持久化或页面展示 - 失败兜底”的顺序排查。小结同步要按版本消费不按到达顺序相信多端同步不是把远端消息直接贴到页面。事件先入箱消费时按 eventId 幂等、按 serverVersion 仲裁删除保留墓碑页面只读取本地派生结果。这样网络乱序不会变成数据乱序。ox 先判重 |如果现象没有出现在表里仍然建议按“输入来源 - 中间状态 - 持久化或页面展示 - 失败兜底”的顺序排查。小结同步要按版本消费不按到达顺序相信多端同步不是把远端消息直接贴到页面。事件先入箱消费时按 eventId 幂等、按 serverVersion 仲裁删除保留墓碑页面只读取本地派生结果。这样网络乱序不会变成数据乱序。