Godot 前后台切换后的会话续租：别让玩家回来时卡在半登录状态

半登录状态比掉线更麻烦

移动端游戏从后台回到前台时，最常见的坏体验不是直接掉线，而是卡在半登录状态。大厅还显示好友列表，活动入口还能点，资源下载也在转圈，但进入房间失败、聊天发送失败、商店拉取价格失败。玩家看到的是一个“好像在线”的客户端，实际每个需要服务端确认的动作都在失败。

Godot 客户端如果把登录、房间、资源下载、聊天、支付、活动配置都各自维护连接状态，前后台切换后就很容易出现这种裂缝。某个模块认为 token 还没过期，另一个模块已经收到 401；下载队列以为网络恢复了，账号服务还没续租；UI 层先恢复按钮可点，底层会话还没有完成刷新。问题不在某个请求失败，而在恢复流程没有统一门闸。

会话续租系统的目标，是让客户端从后台回来时先回答三个问题：当前身份是否仍然可信，当前网络是否可用，当前资源请求是否可以恢复。只有这三个问题有明确答案，UI 才能恢复交互。否则就应该显示短暂的恢复状态，而不是让玩家在半登录状态里到处碰错误。

前后台不是暂停和继续那么简单

很多项目最初会在 NOTIFICATION_APPLICATION_FOCUS_IN 或类似生命周期事件里简单重连。这个做法只处理了“应用回来了”，没有处理“回来时世界变了”。后台期间，token 可能过期，平台账号可能被系统刷新，网络从 Wi-Fi 切到蜂窝，房间可能已解散，活动配置可能更新，正在下载的资源包可能已经有新版本。

因此前台恢复要做成状态机，而不是一串回调。状态机里至少有 Suspended、ResumeDetected、NetworkProbe、SessionRenewing、ResourceReconcile、Ready 和 Blocked。Ready 不是收到网络可用就进入，而是账号、网络和关键资源都通过检查后进入。

flowchart TD
    A["App Resume"] --> B["Freeze Interactive UI"]
    B --> C["Probe Network"]
    C --> D{"Network Usable?"}
    D -- "No" --> E["Offline Shell"]
    D -- "Yes" --> F["Renew Session Token"]
    F --> G{"Session Valid?"}
    G -- "No" --> H["Login Recovery"]
    G -- "Yes" --> I["Reconcile Requests"]
    I --> J["Resume Download Queue"]
    J --> K["Unfreeze UI"]

这张图里最重要的一步是冻结交互 UI。冻结不等于黑屏，也不等于把所有按钮变灰。它指的是在恢复完成前，禁止发起会依赖旧身份、旧房间或旧资源版本的动作。玩家可以查看本地信息，可以看到恢复进度，但不能用过期上下文进入下一步。

统一的 ResumeGate

建议做一个 ResumeGate autoload，负责收集前后台事件、网络探测、会话续租和资源恢复状态。其他模块不要自己判断“现在是否能请求服务端”，而是向 ResumeGate 查询当前 gate 状态。这样聊天、房间、下载、商城、活动入口看到的是同一套恢复结果。

ResumeGate 的字段可以包括：resume_id、app_was_background_seconds、network_generation、session_generation、resource_generation、gate_state、blocked_reason。每次从后台回来都生成新的 resume_id。旧请求如果在新 resume_id 之后返回，就不能直接改 UI，只能交给对应模块判断是否仍然有效。

generation 的作用很大。移动端切网络时，DNS、连接池、下载任务和身份状态都可能发生变化。用 generation 标记能避免旧回调覆盖新状态。例如玩家从后台回来，第一次网络探测失败，UI 显示离线；两秒后网络恢复并开始续租。此时第一次失败的回调如果晚到，不应该把状态又改回离线。

会话续租的分层

会话续租不是只刷新 token。实际项目至少有三层：平台层、游戏账号层、玩法会话层。平台层可能是 Apple、Google、Steam 或渠道 SDK 的票据；游戏账号层是后端识别玩家身份的 access token；玩法会话层是房间、匹配、聊天频道、下载授权等短期状态。

从后台回来后，不一定所有层都要重新登录。短后台，比如 15 秒内切出去回个消息，通常只需要网络探测和关键请求心跳。中等后台，比如几分钟，应该刷新游戏账号 token 和房间状态。长后台，比如几十分钟，可能需要重新拉取活动配置、好友状态和资源清单。策略应该由后台时长、token 剩余时间、网络变化和平台 SDK 状态共同决定。

可以用这样的判断：

func classify_resume(ctx: ResumeContext) -> String:
    if ctx.background_seconds > 1800:
        return "full_recovery"
    if ctx.network_changed or ctx.token_expires_in < 300:
        return "session_renewal"
    if ctx.room_active:
        return "heartbeat_check"
    return "light_probe"

这个函数不需要一次写得很复杂，但要集中。不要让每个模块都写一套“后台超过几分钟就刷新”的判断，否则后期改策略时一定漏。

UI 怎么表现恢复

恢复 UI 要克制。玩家切回游戏时，最不想看到一堆技术文案。建议保留当前画面，顶部或按钮附近显示轻量状态：“正在恢复连接”“正在确认登录状态”“资源队列恢复中”。如果恢复在一两秒内完成，不需要弹窗。如果失败原因明确，比如账号在其他设备登录、网络不可用、资源版本不兼容，再显示可操作提示。

关键是不要让 UI 先于状态恢复。很多半登录问题来自 UI 层在 focus_in 后立刻启用按钮，而会话层还在刷新。按钮可见没问题，但点击动作要经过 ResumeGate。对于战斗、房间、支付、资源下载这种高风险动作，Gate 未 Ready 时应返回结构化原因，UI 再决定展示等待、重试或退出。

恢复期间也要保护玩家上下文。比如玩家后台前正在房间准备页，回来后房间已解散。客户端不应该继续显示旧房间并允许点击准备，而应该通过房间状态 reconcile 把玩家带到大厅，并给出简短原因。再比如资源包版本变化，下载授权过期，应先刷新资源 manifest，再续传，不要拿旧 URL 重试到失败。

请求恢复和取消

前后台切换时，未完成请求要分三类。第一类是幂等查询，例如拉活动配置、拉好友列表，可以取消后重发。第二类是业务动作，例如购买、领取奖励、加入房间，不能简单重发，必须查询最终状态。第三类是长任务，例如资源下载、语音连接、上传日志，需要暂停、校验和续传。

ResumeGate 不直接管理所有请求，但应该提供统一的恢复信号。每个模块注册自己的 on_resume_reconcile(resume_id)，在里面处理取消、查询或恢复。这样恢复流程可见，也便于 QA 检查。

资源下载尤其要小心。后台期间系统可能暂停网络，临时 URL 可能过期，Range 请求可能不再被服务端接受。恢复时先校验本地分片和 manifest revision，再决定续传、重签名 URL 或从头下载。不要让下载线程在 token 刷新前先跑起来，否则会制造大量 401 和重复失败。

网络变化的细节

移动端从后台回来时，网络“可用”只是最低条件。还要知道网络类型是否变化、是否从 Wi-Fi 切到蜂窝、是否进入低数据模式、是否需要重新解析域名、是否应该降低并发。Godot 层未必能直接拿到所有平台细节，但可以通过原生桥接或平台服务提供归一化结果。

如果网络从 Wi-Fi 切到蜂窝，恢复下载队列前要重新走计费策略。玩家之前同意在 Wi-Fi 下载，不代表同意用蜂窝继续下载。这个场景和单纯“移动网络计费提示”不同：它发生在后台恢复中，玩家可能并不知道网络已经变化。ResumeGate 应该把 network_generation 变化通知给 DownloadPolicy。

如果网络变差但仍可用，聊天、心跳和轻量配置可以恢复，大包下载、语音高码率和图片上传可以延后。恢复不是全开或全关，而是按业务风险分层恢复。

日志要串起一次恢复

一次前后台恢复可能涉及十几个模块。如果没有 trace，很难知道玩家卡在哪里。建议每次恢复生成 resume_trace_id，所有相关日志都带上它。日志字段包括后台时长、网络变化、token 剩余时间、续租耗时、失败码、资源 reconcile 耗时、UI 解冻时间。

线上指标可以关注：恢复成功率、恢复耗时 P50/P95、半登录错误数、旧请求覆盖次数、续租失败原因分布、恢复后 30 秒内退出率。半登录错误可以定义为 Gate 未 Ready 时模块仍发起高风险请求，或者 Ready 后收到旧 generation 的失败回调并影响 UI。

开发包里最好有 Resume 面板。面板显示当前 gate state、最近 resume_id、各模块 reconcile 状态、阻塞原因和旧回调丢弃次数。这个面板能让 QA 在真机上复现“切后台 10 分钟后回来点匹配失败”的问题，而不是只给一句“偶现”。

QA 应该怎么测

QA 场景要覆盖不同后台时长：5 秒、1 分钟、10 分钟、30 分钟。每个时长再组合网络变化：Wi-Fi 不变、Wi-Fi 到蜂窝、蜂窝到 Wi-Fi、无网恢复、弱网恢复。还要覆盖不同页面：大厅、房间、战斗、结算、商店、资源下载中、语音频道中。

重点观察三个指标。第一，UI 是否在恢复完成前发起高风险动作。第二，失败提示是否和真实原因一致，例如网络不可用、登录过期、房间解散、资源版本变化。第三，恢复完成后旧请求是否还会改 UI。

自动化可以通过调试接口模拟 app_suspend 和 app_resume，再注入 token 过期、网络 generation 变化、资源 manifest 变化。真机测试则验证平台生命周期和 SDK 行为。尤其 iOS 和 Android 对后台网络、通知、语音和系统设置返回的处理差异很大，不能只在桌面编辑器里测。

落地顺序

第一步做 ResumeGate，不改太多业务。先让前后台事件、网络探测、token 状态和 UI gate 可见。只要能在开发包看到当前恢复阶段，就已经能定位很多半登录问题。

第二步接入三类高风险动作：房间、支付、资源下载。它们最怕旧身份和旧请求。所有入口都必须经过 Gate，Gate 未 Ready 时返回明确原因。

第三步处理请求 generation。让旧回调不再直接覆盖新状态，尤其是登录、下载和房间模块。这个阶段会发现很多历史代码把 UI 和网络回调绑得太紧，需要逐步拆。

第四步补线上指标和灰度策略。恢复失败不一定都要弹窗，有些可以自动重试，有些必须回登录页，有些只需要暂停下载。指标能帮助团队判断哪类失败最常见，而不是凭感觉优化。

常见事故复盘

前后台恢复最典型的事故，是玩家在房间准备页切出去很久，回来后 UI 仍然显示自己在房间里，但服务端房间已经超时释放。玩家点击准备，客户端发出旧 room_id 请求，服务端返回房间不存在。页面脚本把这个错误当成普通网络失败，继续留在准备页，玩家只能反复点击。正确处理应该是在 ResumeGate 恢复阶段让 RoomService 主动 reconcile：查询 room_id 是否仍有效，若无效则退出到大厅，并显示“房间已结束，已返回大厅”。这样玩家看到的是状态变化，而不是莫名失败。

第二类事故是下载队列抢跑。应用回到前台后，下载线程先恢复，拿旧 token 请求 CDN，连续返回 401。几秒后账号服务续租成功，但下载器已经把任务标记为失败。玩家看到“下载失败”，手动重试才继续。这里的问题不是 CDN，也不是 token，而是恢复顺序错了。下载队列应该等待 ResumeGate 的 ready_for_downloads，并在 token generation 变化后重签 URL。旧 401 只能作为过期请求记录，不能直接改变最终任务状态。

第三类事故是 UI 解冻太早。恢复动画还在转，按钮已经能点，玩家连续点击匹配。第一次请求使用旧会话，第二次请求使用新会话，两个回调顺序不确定，最后页面可能显示“匹配中”，服务端却没有队列记录。解决方法是给高风险按钮加 gate token。按钮点击时读取当前 resume_generation，请求返回时若 generation 不匹配，就丢弃结果并要求页面重新读取当前状态。

与服务器约定

客户端做得再稳，也需要服务器配合。会话续租接口要返回明确错误码，例如 session_expired、platform_ticket_invalid、account_conflict、maintenance、rate_limited。不要所有失败都返回通用 401。客户端只有知道失败层级，才能决定自动重试、回登录页、保留离线壳，还是提示维护。

房间、聊天、下载授权也要提供查询最终状态的接口。前后台恢复期间，客户端不应该猜测一个动作是否成功。例如玩家后台前点击了领取奖励，请求超时，回来后不能直接重发，应该查询奖励是否已领取。服务端如果没有幂等键或状态查询，客户端就只能在风险和重复请求之间摇摆。

另外，服务器最好接受客户端传 resume_trace_id 和 client_generation。这不是业务必需字段，但对排查非常有帮助。一次恢复中哪些请求使用旧 generation、哪些请求被服务端拒绝、哪些请求在续租后成功，都能被串起来。移动端问题经常跨客户端和服务端，只有一边日志很难判断。

小结

前后台切换后的会话续租，是移动端 Godot 客户端非常典型的交叉问题。它不是纯网络，也不是纯 UI，而是身份、网络、资源和页面状态一起恢复。处理不好就会出现半登录状态，玩家能看见旧世界，却做不了新动作。

最实用的做法是建立统一 ResumeGate。先冻结高风险交互，再探测网络、续租会话、协调资源请求，最后解冻 UI。只要这条主线清楚，各模块就不会在玩家回到游戏的一瞬间各自抢跑。