登录、会话与游戏协议
适用:微信小游戏登录链路、TypeScript 协议建模,客户端目标 Cocos Creator 3.8.8。资料核查:2026-11-17。已读取 wx.login 与服务端 code2Session 的官方原文,并与微信官方类型仓库交叉核对;资料核查不代表本项目已完成真实登录接入。
平台身份与游戏会话分两次建立
小游戏调用 wx.login 得到临时 code,后端再通过平台服务交换身份信息,最后签发自己的游戏会话。客户端拿到 code 不代表已经建立业务登录。玩家的体力、背包与房间归属都应绑定游戏侧用户标识;平台标识是身份映射依据,不应成为客户端随意填写即可通过的参数。不要把“界面显示已登录”作为业务请求已经可信的证明。
登录成功结果、头像昵称授权、隐私相关授权是不同概念。完成登录并不意味着获得任意个人信息,也不意味着用户同意所有数据用途。游戏应能在不读取额外信息时进入可玩的基本流程,只有功能确实依赖某项能力时才请求对应授权。平台字段的存在条件也需要逐项核对,不能假设所有用户都能得到相同的联合标识。
服务端保存 AppSecret 等平台凭据;客户端只提交 code 与当前客户端版本。交换接口返回的 session_key 属于平台会话材料,不是发给客户端的通用访问令牌。业务访问令牌要有自己的过期、撤销、权限范围和日志脱敏规则。若长连接采用一次性入场票据,应限制其用途和房间范围,避免把长期令牌放进会被代理日志记录的 URL。
登录也是并发与时序问题
启动、前台恢复、某次接口返回未认证,都可能同时触发登录。若每个组件独立调用,会出现旧请求覆盖新会话、重复交换和大量并发重试。用一个登录协调器共享进行中的 Promise,并使用会话世代阻止过时响应写回;错误后清除进行中状态,允许明确重试。不要把失败 Promise 永久缓存,也不要无限递归“登录后重发”。
class SessionGate {
private pending?: Promise<string>;
private epoch = 0;
constructor(private exchange: () => Promise<string>) {}
login(): Promise<string> {
if (this.pending) return this.pending;
const epoch = this.epoch;
const task = this.exchange().then(token => {
if (epoch !== this.epoch) throw new Error('STALE_LOGIN');
return token;
});
this.pending = task;
void task.finally(() => {
if (this.pending === task) this.pending = undefined;
}).catch(() => {});
return task;
}
invalidate() { this.epoch++; this.pending = undefined; }
}
示例只演示并发合并,不保存令牌、不实现平台交换。实际代码还需要请求超时、主动取消或过期结果丢弃,以及退出时清理用户数据。客户端记录“收到响应但已过时”能解释很多偶发登录错乱。保存本地令牌可以改善体验,但被修改或丢失应只导致重新认证,不应让本地存储成为身份权威。
为协议定义时间语义
业务后端习惯 requestId,但游戏协议还需要房间标识、输入序号、服务端 tick 与内容版本。每个字段只承担一种职责:requestId 用于关联一次尝试;operationId 标识一个业务意图;inputSeq 用于确认模拟输入;roomEpoch 防止旧房间消息污染新房间。重试保留 operationId,同时可以产生新的 requestId,才能既幂等又看得见多次尝试。
type CommandEnvelope = {
protocol: 1;
requestId: string;
operationId: string;
kind: 'claimLevelReward';
body: { runId: string; ruleVersion: string };
};
type Reply<T> =
| { ok: true; requestId: string; data: T }
| { ok: false; requestId: string; code: string; retryable: boolean };
TypeScript 类型只约束编译期,不验证网络输入。服务端仍需检查字段类型、长度、枚举、数组数量和嵌套深度。JSON 中的 number 不能随意承载所有数据库大整数;货币与大标识可用十进制字符串传递,明确单位与舍入策略。二进制协议也一样需要边界检查,序列化快并不等于安全。
协议升级先考虑并存窗口。旧包可能仍在手机运行,服务端升级后要么兼容约定的旧协议,要么返回可理解的升级原因,不能让客户端一直加载。新增可选字段通常比改变既有字段含义温和;删除旧字段前应观察仍在使用该协议的会话比例。玩法规则版本与传输协议版本分开:换一张数值表不一定改变消息结构。
认证失效时保留业务意图
访问令牌过期与业务命令失败需要区分。读请求可在重新认证后重试;领取、消费等写操作必须先有幂等设计。若服务端已扣除体力但响应丢失,客户端不能在登录恢复后生成新意图再扣一次。认证协调器只解决“谁来登录”,业务协调器决定“重试同一次操作还是查询结果”。
常见故障是开发者工具关闭域名校验后能登录,真机却失败。按 DNS、证书、平台域名配置、请求错误、平台交换结果、业务建会话逐层定位。日志保留阶段、耗时与错误码,不打印 code、令牌、session_key 或完整平台响应。测试身份应来自测试环境,不能在正式代码留下“openid=某值即管理员”的入口。
重试前先分类错误
将平台取 code 失败、服务端交换失败、业务账号受限、协议不兼容和普通网络超时分别编码。前两项可能需要重新获取临时材料;账号受限需要明确终态;不兼容需要升级路径;超时则先保留业务操作标识。客户端不应通过匹配一段中文 errMsg 决定经济操作是否重试,错误文案可以调整,稳定错误码才是协议的一部分。
登录页还要处理等待中的用户操作。玩家点击返回、切换账号或重试后,之前那条链路未必真正停止,因此界面状态与认证世代都要核对。测试时让第一次交换最后返回,再确认第二次身份没有被覆盖;让第一次失败晚到,也不能把已经成功的界面退回错误页。这样的受控顺序测试通常比随机连点更容易证明修复。
交给 AI 的任务与验收
可复制任务:“实现登录协调器与平台适配接口,业务层不直接引用 wx。覆盖三个并发登录调用、退出后旧响应迟到、交换失败后重试、过期会话重认证。设计领取奖励协议,分清 requestId 与 operationId,并给服务端增加运行时参数校验。禁止在客户端放平台密钥。”
验收证据应包括一次平台接口调用被三个调用者共享、旧响应未覆盖新身份、非法字段被拒绝、同一奖励意图恢复后仍只有一次结果。浏览器替身证明时序逻辑;微信构建与真机证明平台交换通路。两类结果分别记录,继续阅读重连与幂等。
官方来源与核查边界
- 微信官方小游戏 API 类型仓库:本次核对提交 42c427aa8c3961b7a4f8ea5bd6112c2bcf058177,含 login 结果与接口说明。
- 微信 wx.login与服务端 code2Session:已核对临时 code、服务端交换参数及身份/会话字段;AppSecret 参与的交换只能在服务端进行。
- OWASP WebSocket Security:鉴权、消息校验与敏感日志原则,本文代码为原创教学示例。