跳到主要内容

断线恢复与经济操作幂等

适用:引擎无关的会话恢复与服务端事务设计,TypeScript 示例面向 Cocos Creator 3.8.8 接入。资料核查:2026-11-17。

断线不是一个事件,而是一段不确定区间​

连接关闭、心跳超时、切入后台、无线网络切换,客户端观察到的现象不同,但共同问题是“不知道哪些消息已经生效”。发送成功回调只说明本地接口接受了发送,不能证明业务提交;没有收到响应,也不能证明服务端没执行。游戏里的消耗体力、领取奖励和复活购买,都必须在这种不确定性下仍有唯一结果。

把连接状态写成显式状态机:未连接、连接中、认证中、同步中、可交互、等待重试、已终止。只有可交互状态允许发送需要当前房间上下文的命令。重连后不能因为 socket open 就立即恢复战斗;必须重新认证、确认房间世代并得到可用快照。UI 可以让玩家看到重连进度,但不能在等待期间偷偷累积无限攻击输入。

为旧连接加一道世代边界​

每次创建新连接都分配本地 generation。所有回调捕获自己的 generation,处理时与当前值比较,过时回调直接丢弃。否则旧连接晚到的 close 会把新连接标成离线,旧快照也会覆盖重连结果。解绑事件和关闭旧 socket 仍要做,但世代检查是处理异步迟到的明确保护。

class ConnectionEpoch {
private current = 0;
begin() { return ++this.current; }
accept(epoch: number) { return epoch === this.current; }
stop() { this.current++; }
}
const epochs = new ConnectionEpoch();
const mine = epochs.begin();
// socket.onMessage(msg => {
// if (!epochs.accept(mine)) return;
// applyValidatedMessage(msg);
// });

自动重试需要退避、随机抖动、最大尝试或时间预算,以及用户可见的重试入口。恢复网络后可以提前尝试,但多个触发源应合并。大规模停机时所有客户端同时高频重连会让恢复更慢。认证明确失败、协议不兼容、房间已结束等业务结果不应当作瞬时网络错误持续重试。

快照与事件的交接要无缝​

恢复接口可接收 roomId、roomEpoch、最后确认的输入序号及最后事件游标。服务端判断保留的事件是否覆盖断线区间:覆盖则返回连续事件;不足则返回全量快照。全量快照要带 eventCursor,表示它已包含到哪个事件,后续只应用更大的游标。否则在“获取快照”和“开始订阅”之间可能漏掉奖励、出生或死亡。

快照并不是把客户端整个对象树序列化。它是恢复游戏所需的权威状态,包括实体身份、阶段、计时依据与必要的规则版本。客户端自行重建节点、粒子和镜头。短暂装饰效果通常无需补播;经济变化必须由持久化记录恢复。恢复后先重建模型,再开放输入,避免 UI 与战斗同时写入半初始化对象。

幂等业务键代表玩家的一次意图​

领取同一关卡奖励,业务键可以是用户、局标识与奖励种类的组合;购买则使用服务端订单标识。客户端生成的 operationId 只能标识请求意图,服务器仍应约束它对应的用户与参数。若相同键换了商品或金额,应返回冲突,不能悄悄重用旧结果,更不能把“换个键”当作允许重复领取的依据。

-- 示意:同一数据库事务内完成,表结构按项目调整。
BEGIN;
INSERT INTO reward_claim(user_id, run_id, reward_kind, amount)
VALUES (:user, :run, :kind, :server_amount)
ON CONFLICT (user_id, run_id, reward_kind) DO NOTHING;
-- 仅插入成功者写账本与更新余额;冲突者读取原结果。
-- 失败时整体回滚;唯一索引必须实际存在。
COMMIT;

上面强调原子边界,而不是某种特定数据库写法。先查询“有没有领过”再独立更新余额,会在并发下重复发奖;先记已处理再另起事务加余额,会在崩溃后漏发。缓存锁可以降低竞争,但最终业务唯一约束与事务才定义结果。跨服务时可采用事务消息或 outbox,再用消费者去重,不能假装分布式调用天然恰好一次。

经济结果与动画完成解耦​

开箱动画结束不应成为发奖触发点。服务端确认结果后客户端可以播放动画,若切后台或崩溃,下次通过账本和操作状态恢复结果展示。广告复活也一样:广告结果、奖励资格和复活表现各有阶段,任何回调重复都不能让经济变化重复。客户端的禁用按钮只是体验控制,不是并发安全措施。

本地待处理操作队列要有明确生命周期,只持久化允许恢复的业务意图。旧的移动、拖动和瞄准输入通常应丢弃,不能在恢复后补发十秒前的操作。展示“结果确认中”比假定失败后让玩家重复点击更准确;超过等待窗口后提供查询和客服定位标识,不要显示未经证实的到账结论。

用故障注入验证而不是等待偶发​

至少在四个断点断网:请求发出前、服务端提交前、提交后响应前、客户端收到结果后写本地前。重复发送相同意图、同时打开两条连接、让旧连接晚到 close,再检查状态机与账本。重连成功率应按恢复阶段统计,区分连通失败、认证失败、补快照失败和 UI 重建失败。

常见“重连成功但不能移动”是可交互状态未恢复、输入监听未重新绑定或规则状态仍处于暂停;“重连后速度翻倍”通常是重复绑定更新与监听。保留监听数量、连接 generation 和房间 epoch 的诊断字段,可以直接验证这些假设。

查询接口也是恢复协议的一部分​

经济操作超时后,需要按操作标识查询 pending、succeeded 或 failed,并返回已经保存的最终结果。pending 不能无限存在,服务端要有恢复任务或可追踪的处理所有者;failed 也要说明是否允许在原意图内重试,还是必须由玩家发起新操作。客户端不应通过余额变化猜测某一次领取是否成功,因为期间可能还有其他合法变更。

幂等记录保留多久也影响正确性。若比客户端可能重试的窗口短,旧操作可能重新生效;若永久保留全部响应,又会增加存储成本。按业务事实设计唯一键和留存,对领取资格这类永久约束不能仅靠短期去重缓存。先定义最长恢复窗口,再制定记录归档策略。

交给 AI 的任务与验收​

可复制任务:“为领取奖励与房间恢复设计显式状态机。实现连接世代过滤、有界退避和快照游标衔接;用故障注入模拟服务端已提交但响应丢失。数据库用唯一业务键与同事务账本,不接受客户端金额。输出每种失败后的可观察状态。”

验收同一操作并发提交多次只增加一次余额;提交后断线可查询原结果;旧 socket 不能改变新连接;事件补发不重演已包含在快照里的变化。最后检查后台恢复与主动退出分别走到哪里,而不只测试正常关闭连接。

官方来源​

  • IETF RFC 6455:连接关闭与传输语义,不提供业务幂等保证。
  • PostgreSQL INSERT 文档:ON CONFLICT 的正式语义;SQL 为课程设计示意,需结合实际事务实现。
  • 微信官方 API 类型仓库:SocketTask 与生命周期接口形态,核对提交 42c427aa8c3961b7a4f8ea5bd6112c2bcf058177。本文未实测微信恢复行为。