1. 背景与问题

移动游戏切后台时服务端持续推送消息产生 backlog，切回前台一次性处理导致主线程阻塞，是几乎所有长连接游戏的共性问题。

典型问题表现：

• 前台恢复时卡顿、掉帧、短暂假死
• 历史动画 / 音效 / toast 集中爆发
• 旧上下文消息污染新上下文（旧局、旧房间）
• 重复结算、重复提示、状态错乱
• 断线重连、弱网抖动时缺少统一恢复机制
• 不同游戏类型各自实现恢复逻辑，重复建设且不可复用

2. 设计目标

构建一套兼容多游戏类型的客户端底层运行时框架，统一解决：

• 类型无关：不同游戏仅需通过配置文件声明策略组合，无需修改核心代码
• 消息整形：接收、分类、整形与裁剪
• 恢复统一：前后台切换恢复、断线重连与重同步
• 主线程安全：预算化调度，杜绝”队列清空式处理”
• 逻辑/表现解耦：状态层与表现层分离，恢复期间可静默
• 服务端协同：标准化的前后台状态同步协议
• 可观测性：内置关键指标采集与调试面板

不直接覆盖：业务状态机重构、服务端完整协议重设计、引擎渲染线程优化、资源加载系统改造、UI 业务逻辑重构细节。

3. 设计原则

一句话方案：采用”消息语义分类 + 上下文隔离 + 消息整形压缩 + 快照/事件混合恢复 + 主线程预算调度 + 表现静默恢复”的统一运行时架构。

1. 先分类，再处理 —— 所有消息先经语义分类和一致性标注，再决定处理方式
2. 状态优先收敛 —— 不盲目回放历史，优先用快照对齐真值
3. 以上下文为隔离边界 —— contextId + epoch 严格隔离不同对局/房间/地图
4. 主线程永远按预算消费 —— 禁止单帧清空队列
5. 逻辑状态与表现彻底解耦 —— 恢复期间表现层可静默
6. 策略可插拔、可配置 —— 差异体现在策略配置，而非框架分叉
7. backlog 超限时优先重同步 —— 而不是硬吃到底

4. 架构总览

分层架构

┌───────────────────────────────────────────────────────────────┐
│                      应用层 (Application Layer)                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ MMO 游戏 │  │ 棋牌游戏 │  │ 卡牌游戏 │  │ 回合制   │      │
│  └─────┬────┘  └─────┬────┘  └─────┬────┘  └─────┬────┘      │
│        └──────────────┼──────────────┼────────────┘           │
│                       ▼                                       │
│  ┌────────────────────────────────────────────────────────┐   │
│  │          游戏类型适配层 (Adapter Layer)                  │   │
│  │        通过配置文件选择策略组合，无需修改核心代码         │   │
│  └────────────────────────┬───────────────────────────────┘   │
│                           ▼                                   │
│  ┌────────────────────────────────────────────────────────┐   │
│  │               核心处理层 (Core Layer)                    │   │
│  │  MessageShaper │ RecoveryCoordinator │ MainScheduler   │   │
│  │  DomainCore    │ PresentationBridge  │ LifecycleManager│   │
│  └────────────────────────┬───────────────────────────────┘   │
│                           ▼                                   │
│  ┌────────────────────────────────────────────────────────┐   │
│  │              网络通信层 (Network Layer)                   │   │
│  │  协议编解码器 │ 连接状态管理 │ 前后台信令通道             │   │
│  └────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────┘

核心处理管线

TransportLayer → DecodePipeline → IngressRouter → MessageShaper
    → RecoveryCoordinator → DomainCore → PresentationBridge → MainThreadScheduler

• TransportLayer：网络收发
• DecodePipeline：协议解析，原始消息标准化为统一信封
• IngressRouter：按上下文（contextId + epoch）和语义分类路由
• MessageShaper：消息整形——去重、覆盖、合并、限长、后台压缩、恢复裁剪
• RecoveryCoordinator：恢复决策——判断走 replay / snapshot / hybrid
• DomainCore：核心真值状态，不涉及任何表现
• PresentationBridge：UI / 动画 / 音效的表现调度
• MainThreadScheduler：主线程预算调度，控制每帧消费量

5. 统一消息模型

所有下行消息先标准化为统一信封：

struct MessageEnvelope {
    uint64_t    messageId;       // 消息唯一标识，用于去重
    std::string sessionId;       // 会话 ID
    std::string contextId;       // 房间 / 地图 / 对局 / 战斗实例
    uint64_t    epoch;           // 上下文生命周期版本
    uint64_t    seq;             // 上下文内消息序列号
    SemanticClass    semantic;   // 消息语义分类（5 类）
    ConsistencyPolicy policy;    // 一致性策略（4 类）
    MessagePriority  priority;   // 处理优先级（5 级）
    std::string routeKey;        // 用于覆盖/合并的粒度键（如 entityId）
    uint64_t    timestamp;       // 服务端生成的时间戳
    uint64_t    arriveTime;      // 客户端接收时刻
    Payload     payload;         // 消息体
};

核心字段说明：

• contextId：房间 / 地图 / 对局 / 战斗实例，是上下文隔离的基础
• epoch：上下文生命周期版本，用于区分”同一房间的不同局”
• seq：上下文内消息序列号，用于保序、缺序检测和恢复定位
• routeKey：用于合并/覆盖的粒度键（如同一实体的位置更新共享一个 key）

消息语义分类（SemanticClass）

统一分为 5 类：

• Command：强控制指令，必须执行。踢下线、强制切场景、支付回调
• Event：离散业务事件，有时序依赖。出牌、技能释放、结算
• StateDelta：状态增量，可合并。位置更新、属性变化、Buff 更新
• Snapshot：状态快照，覆盖式。全量状态同步、进房快照
• PresentationHint：纯表现提示，可丢弃。伤害跳字、特效播放、聊天飘字

一致性策略（ConsistencyPolicy）

统一分为 4 类，使不同游戏类型的差异体现在策略配置，而不是底层框架分叉：

• StrictOrdered：严格保序，不可丢弃。超限触发 resync。适用于出牌序列、结算流程、扣费
• OrderedMergeable：允许按 routeKey 合并 patch。适用于属性增量、区域状态 patch
• LastWriteWins：按 routeKey 只保留最终值。适用于位置、朝向、倒计时
• BestEffort：可丢弃，不影响核心真值。适用于特效、聊天、表情、toast

消息优先级（MessagePriority）

• CRITICAL（0）：不可丢弃，必须立即处理（断线、支付回调）
• HIGH（1）：尽量不丢弃，优先处理（关键战斗结果）
• NORMAL（2）：正常处理，后台可考虑丢弃
• LOW（3）：低价值，后台优先丢弃（特效、聊天）
• DEBUG（4）：仅调试用途，生产环境直接丢弃

6. 上下文隔离

所有消息处理必须以 contextId + epoch 作为隔离边界。过期消息一律丢弃。

目的：

• 防止旧局、旧房间、旧地图的消息污染新状态
• 支持切局、切图、重进房间、断线恢复等场景
• 支持多上下文独立恢复与裁剪

规则：

• 消息的 contextId + epoch 与当前上下文不匹配 → 一律丢弃
• 切换上下文时清空旧上下文的全部队列和缓存
• 恢复流程以当前 contextId + epoch 为准，不跨上下文回放

7. MessageShaper：消息整形层

核心模块，负责把”收到的很多消息”整理成”值得被处理的少量消息”。

职责：去重（基于 messageId）、覆盖（LastWriteWins）、合并（OrderedMergeable）、限长（队列超限按优先级裁剪）、后台压缩、恢复裁剪、缺序检测（seq gap）、backlog 超限触发重同步。

按策略处理规则

• StrictOrdered：保序缓存，seq gap 时等待补包，超限触发 resync
• LastWriteWins：按 routeKey 覆盖，仅保留最新值
• OrderedMergeable：按 routeKey 合并 patch，保持合并顺序
• BestEffort：限长、丢弃、恢复时静默跳过

合并策略配置示例

{
  "type": "StateBasedMerge",
  "rules": [
    { "messageType": "POSITION", "mergeKey": "entityId", "method": "latest" },
    { "messageType": "ATTRIBUTE", "mergeKey": "entityId_attr", "method": "latest" },
    { "messageType": "BUFF", "mergeKey": "entityId_buffId", "method": "latest" }
  ]
}

丢弃策略

基于后台时长和优先级的分级丢弃：

• 后台 < 30 秒：仅丢弃 DEBUG
• 后台 30 秒 ~ 2 分钟：丢弃 LOW 及部分 NORMAL（非 DECISION 域）
• 后台 > 2 分钟：仅保留 CRITICAL 及最新状态快照
• 内存压力超阈值：主动清理非关键队列

{
  "type": "PriorityBasedDiscard",
  "backgroundRules": [
    { "priority": "LOW", "thresholdSec": 10, "action": "discard" },
    { "priority": "NORMAL", "thresholdSec": 60, "action": "discard" }
  ],
  "domainRules": [
    { "domain": "DECISION", "action": "never_discard" }
  ]
}

8. RecoveryCoordinator：恢复协调器

负责统一决定恢复方式。推荐使用 Hybrid 模式。

支持三种模式：

• EventReplayOnly：仅回放事件。服务端无 snapshot 能力时的降级方案
• SnapshotOnly：仅拉快照。SLG / 放置类，对账式恢复
• Hybrid（推荐）：快照 + 关键事件补放。棋牌、MMO、回合制等大多数场景

Hybrid 恢复流程

1. 拉取 snapshot，对齐真值状态
2. 仅补 replay snapshot.seq 之后的关键事件（StrictOrdered）
3. 跳过所有历史表现（PresentationHint）
4. 以收紧预算恢复若干帧后回到 Active 状态

触发重同步的条件

当发生以下任一情况时，判定状态不可信，直接进入 Resyncing：

• seq gap 无法补齐
• snapshot 校验失败
• context 已失效（epoch 不匹配）
• StrictOrdered backlog 超限
• 领域状态自检不通过

9. 主线程预算调度

禁止使用”队列清空式处理”，采用固定预算。

struct SchedulerBudget {
    int    maxLogicMessages;         // 每帧最大逻辑消息数
    int    maxPresentationMessages;  // 每帧最大表现消息数
    double maxLogicMs;               // 每帧最大逻辑耗时
    double maxPresentationMs;        // 每帧最大表现耗时
};

追帧模式

切回前台时根据积压量自动切换：

• 0 ~ 30 条：正常模式，业务定义间隔（如 300ms），完整动画
• 30 ~ 100 条：快速追帧，50ms 间隔，缩短动画
• 100 ~ 500 条：超快追帧，10ms 间隔，跳过动画仅更新数据
• > 500 条：直接请求全量状态同步

调度原则：

• 主线程只做必须在主线程执行的事
• UI 刷新统一合批（脏标记驱动，而非每条消息触发）
• 恢复态预算比正常态更保守

{
  "type": "FrameAlignedConsume",
  "normalIntervalMs": 300,
  "fastForwardIntervalMs": 50,
  "ultraFastIntervalMs": 10,
  "maxPerFrame": 2,
  "skipThreshold": 500
}

10. 逻辑与表现解耦

DomainCore 只维护真值状态，不直接执行 UI 刷新、动画播放、音效触发、toast 提示。

逻辑层输出 ApplyResult，由 PresentationBridge 按表现模式决定如何展示：

• Normal：完整播放动画、音效、UI 更新。正常前台运行
• SilentRecover：静默更新状态，不播放历史表现。恢复期间使用
• FinalStateOnly：直接跳到最终状态，无过渡。长时间后台恢复 / 棋牌回放跳过

恢复期间默认使用 SilentRecover 或 FinalStateOnly，避免历史动画/音效集中爆发。

11. 生命周期设计

统一状态流转：

Active → Background → Recovering → Active
                   ↘ Resyncing → Active
                   ↘ Reconnecting → Recovering / Resyncing
                   ↘ Disconnected

• Active：前台正常运行
• Background：后台，MessageShaper 进入压缩模式
• Recovering：切回前台，正在恢复（暂停普通派发）
• Resyncing：异常重同步（seq gap / snapshot 失败 / backlog 超限）
• Reconnecting：网络断线重连中
• Disconnected：已断线，等待用户操作

进入后台

1. 切换为 Background
2. 向服务端发送 { state: "BACKGROUND", timestamp } 通知
3. MessageShaper 进入压缩模式（加速合并、降级丢弃）
4. BestEffort 消息降级或直接丢弃
5. 表现层静默

回到前台

1. 切换为 Recovering，暂停普通消息派发
2. 向服务端发送 { state: "FOREGROUND", background_duration, queue_size } 通知
3. 清理过期消息（上下文隔离 + 时间过期）
4. RecoveryCoordinator 构建 RecoveryPlan
5. 拉取 snapshot / resume 数据（如需要）
6. 裁剪 backlog，replay 关键事件
7. 以收紧预算恢复若干帧，切回 Active

异常重同步

当 RecoveryCoordinator 判定状态不可信时：

1. 切换为 Resyncing，清空当前上下文全部队列
2. 向服务端请求全量状态同步（sync_full_state）
3. 以 snapshot 重建 DomainCore，切回 Active

12. 适配多游戏类型

本方案不按游戏类型写死逻辑，而是通过策略配置适配。差异体现在配置，而非代码分叉。

棋牌 / 回合制

• StrictOrdered：发牌、出牌、结算、奖惩
• LastWriteWins：倒计时、当前操作者
• BestEffort：表情、聊天飘字
• 合并策略：关闭（棋牌）/ 战斗内可合并（回合制）
• 恢复：snapshot + critical replay，FinalStateOnly 优先

MMO / 实时对战

• StrictOrdered：结算、任务、背包变化、切图
• OrderedMergeable：属性 patch、区域 patch
• LastWriteWins：位置、朝向、目标
• 合并策略：激进合并，位置/属性只保留最新
• 恢复：区域 snapshot 优先，不追帧，直接应用最终状态

SLG / 放置 / 经营

• StrictOrdered：奖励、扣费、建筑完成
• LastWriteWins：资源量、建筑状态、队列剩余时间
• BestEffort：产出表现、红点、普通提示
• 恢复：snapshot-only 或对账式恢复

策略对比

13. 服务端协同设计

前后台状态同步协议

客户端在前后台切换时向服务端发送状态通知：

• state（Enum）：FOREGROUND / BACKGROUND
• timestamp（Int64）：切换时刻
• background_duration（Int32）：切回前台时携带，后台持续时长（秒）
• queue_size（Int32）：当前积压消息数
• last_seq（Int64）：最后处理的消息序列号

服务端推送策略调整

服务端建议提供的能力

1. Snapshot API —— 全量状态快照，支持按上下文拉取
2. lastSeq / resume token —— 恢复能力，客户端告知 lastSeq 后只补发后续消息
3. lifecycle hint —— 告知服务端客户端当前生命周期状态
4. deadline-based timer —— 下发截止时间而非每秒推倒计时
5. 局部 snapshot —— 可选，只下发变化部分
6. force_full_resync —— 服务端主动要求客户端全量重同步

14. 配置化设计

架构行为由声明式配置文件驱动：

{
  "gameType": "card",
  "queue": {
    "maxSize": 500,
    "expireMs": 5000,
    "skipThreshold": 200
  },
  "classifier": {
    "rules": [
      { "typePattern": "DEAL_*", "semantic": "Event", "policy": "StrictOrdered", "priority": "HIGH" },
      { "typePattern": "TIMER_*", "semantic": "StateDelta", "policy": "LastWriteWins", "priority": "NORMAL" },
      { "typePattern": "CHAT_*", "semantic": "PresentationHint", "policy": "BestEffort", "priority": "LOW" }
    ]
  },
  "strategies": {
    "merge": { "type": "StateBasedMerge", "rules": [] },
    "discard": { "type": "PriorityBasedDiscard", "rules": [] },
    "consume": { "type": "FrameAlignedConsume", "normalIntervalMs": 300, "maxPerFrame": 2, "skipThreshold": 500 }
  },
  "recovery": { "mode": "Hybrid", "snapshotTimeoutMs": 3000, "maxReplayCount": 100 },
  "presentation": { "recoverMode": "FinalStateOnly" }
}

扩展新游戏类型只需：实现 IMergeStrategy、IDiscardStrategy、IConsumeStrategy 接口 → 注册到 StrategyRegistry → 配置文件指向新类型。

15. 监控与可观测性

核心指标

• backlog.before_recover：恢复前积压消息数
• backlog.after_trim：整形后剩余消息数
• snapshot.fetch_latency_ms：快照拉取延迟
• replay.critical_count：恢复时回放的关键事件数
• messages.discarded：累计丢弃消息数
• messages.merged：累计合并掉的消息数
• recover.duration_ms：恢复总耗时
• recover.min_fps：恢复期间最低帧率
• frame.logic_time_ms：每帧逻辑处理耗时
• frame.presentation_time_ms：每帧表现处理耗时
• frame.drop_count：因消息处理导致的掉帧次数
• stale.dropped_count：过期上下文丢弃消息数
• forced_resync.count：强制重同步次数
• queue.size.peak：峰值队列长度

验收目标

• 恢复期间最低 FPS ≥ [项目定义]
• 恢复完成耗时 ≤ [项目定义]
• 旧上下文污染率 = 0
• 重复结算 / 重复扣费 = 0
• forced resync 率 ≤ [项目定义]

调试面板（开发阶段）

• 各优先级队列长度柱状图
• 消息吞吐折线图
• 当前追帧进度条
• 手动模拟前后台切换按钮
• 一键导出当前队列快照
• 实时显示当前 lifecycle 状态和 recovery plan

日志与告警

• 队列溢出告警：队列大小超过阈值时上报
• 长时间追帧告警：追帧耗时超过预设值时记录
• 异常丢弃统计：关键消息被误丢弃时立即上报
• seq gap 告警：消息序列号断裂时记录

16. 落地计划

Phase 1：止血（1 ~ 2 周）

• 主线程预算调度（maxPerFrame + maxLogicMs）
• BestEffort 消息后台丢弃
• LastWriteWins 按 routeKey 覆盖
• 验收：前台恢复不再出现长时间卡顿

Phase 2：整形（2 ~ 3 周）

• MessageShaper 完整实现
• routeKey 分桶 + merge / trim / queue limit
• 消息分类器 + 配置驱动
• 验收：积压 500 条消息恢复时间 ≤ 目标值

Phase 3：恢复（2 ~ 3 周）

• RecoveryCoordinator 实现
• snapshot 恢复 + replay 裁剪
• lifecycle 状态机 + 上下文隔离（contextId + epoch）
• 验收：旧上下文污染率 = 0，重复结算 = 0

Phase 4：解耦（2 ~ 3 周）

• DomainCore / PresentationBridge 分离
• UI 脏标记合批刷新
• SilentRecover / FinalStateOnly 表现模式
• 验收：恢复期间无历史动画/音效爆发

Phase 5：服务端协同（协调推进）

• 前后台状态同步协议上线
• resume 协议 + Snapshot API
• lifecycle hint + deadline-based timer
• 验收：端到端恢复流程闭环

17. 主要风险

• 服务端 snapshot 能力不足：先接入 replay + 限流，逐步补 snapshot
• 老项目 UI 与逻辑耦合严重：分阶段抽离，先引入脏标记刷新
• 缺少 seq / epoch：协议逐步补字段，先以 snapshot 兜底
• 策略配置复杂：提供默认模板与项目预设
• 监控不足：优先接埋点后灰度

18. 评审重点问题

1. 当前项目是否具备 contextId + epoch + seq 基础字段？
2. 服务端是否能提供 snapshot 或 resume 能力？
3. 哪些消息必须纳入 StrictOrdered 白名单？
4. backlog 超限时是否接受直接 resync？
5. 业务是否能接受恢复期间跳过历史表现？
6. 主线程预算目标值按什么设备档位定义？

19. 总结

本方案通过七大机制——统一消息模型、语义分类、上下文隔离、消息整形压缩、快照/事件混合恢复、主线程预算调度、逻辑/表现解耦——建立了一套适用于多游戏类型的客户端底层运行时架构。

核心价值：

• 以统一抽象兼容多类型游戏 —— 差异体现在配置，而非代码分叉
• 以前置整形和预算调度控制主线程风险 —— 杜绝积压引发的卡顿
• 以 snapshot/replay 混合恢复保障正确性 —— 状态不可信时果断 resync
• 以上下文隔离消灭污染 —— 旧局消息永远不会影响新局
• 以配置策略替代项目级重复实现 —— 一次建设，多项目复用

建议按”先止血 → 后整形 → 再恢复 → 再解耦 → 最后服务端协同”的路径分阶段落地。