目录— 个文件
⌕
目录加载中…
…/core/http/TsrpcManager.ts
1import { sys } from "cc";
2import { HttpClient as MiniappHttpClient } from "tsrpc-miniapp";
3import { frameworkManager } from "../base/FrameworkClassRegistry";
4import { Framework } from "../../Framework";
5import { IFrameworkManager } from "../base/IFrameworkManager";
6import { Singleton } from "../base/Singleton";
7// import { HttpClient as BrowserHttpClient } from "tsrpc-browser";
8import type { IHttpProxy } from "tsrpc-base-client";
9import type { ApiReturn } from "tsrpc-proto";
10import { serviceProto, ServiceType } from "../../module/server/protocols/serviceProto";
11
12
13/**
14 * 公司统一的 TSRPC 请求管理器。
15 *
16 * 这个类可以理解为“客户端访问自建游戏服务器的统一入口”,目前主要负责:
17 * 1. 创建并复用 TSRPC HttpClient;
18 * 2. 根据当前运行环境选择微信/抖音/支付宝小游戏 request 对象;
19 * 3. 给所有 TSRPC 请求自动追加 Authorization token;
20 * 4. 提供统一 callApi 能力给 Framework.Server 这类业务通信层使用。
21 *
22 * 注意:
23 * - 这里处理的是“自建 TSRPC 服务端”,不是指上、奥音、支付宝那类第三方 HTTP 后台。
24 * - 服务端地址由项目入口设置,不跟随马甲包配置覆盖。
25 * - 具体协议定义来自框架 module/server/protocols/serviceProto.ts。
26 * - 登录、玩家云存档、排行榜等“业务接口语义”不放在这里,统一放到 Framework.Server。
27 */
28
29/**
30 * 探测当前小游戏运行环境。
31 *
32 * TSRPC 的 miniapp client 需要知道宿主 request API 是谁:
33 * - 抖音小游戏:globalThis.tt
34 * - 微信小游戏:globalThis.wx
35 * - 支付宝小游戏:globalThis.my
36 *
37 * 这里返回的对象会传给 tsrpc-miniapp,由它内部使用对应平台的 request 能力。
38 */
39function detectMiniappObj(): unknown {
40 const g = globalThis as Record<string, unknown>;
41 if (g["tt"] !== undefined) return g["tt"];
42 if (g["wx"] !== undefined) return g["wx"];
43 if (g["my"] !== undefined) return g["my"];
44 if (g["jd"] !== undefined) return g["jd"];
45 if (sys.isBrowser && typeof fetch === "function") {
46 return createBrowserMiniappAdapter();
47 }
48 return undefined;
49}
50
51type MiniappRequestOption = {
52 url: string;
53 data?: string | ArrayBuffer;
54 method?: string;
55 header?: Record<string, string>;
56 responseType?: string;
57 success?: (res: { statusCode: number; data: string | ArrayBuffer }) => void;
58 fail?: (err: unknown) => void;
59};
60
61type MiniappRequestTask = {
62 abort: () => void;
63};
64
65/**
66 * 浏览器调试适配层。
67 *
68 * 让 tsrpc-miniapp 在 web / 编辑器预览环境下继续工作:
69 * - 对外伪装成 miniappObj.request;
70 * - 内部用浏览器 fetch 发 HTTP;
71 * - 这样 Framework.Server / Framework.Tsrpc 整条链都不用再分叉。
72 */
73function createBrowserMiniappAdapter(): { request: (options: MiniappRequestOption) => MiniappRequestTask } {
74 return {
75 request(options: MiniappRequestOption): MiniappRequestTask {
76 const controller = new AbortController();
77 const method = options.method ?? "POST";
78 const headers = options.header ?? {};
79 const body = method.toUpperCase() === "GET" ? undefined : options.data;
80
81 fetch(options.url, {
82 method,
83 headers,
84 body,
85 signal: controller.signal,
86 }).then(async (response) => {
87 let data: ArrayBuffer | string;
88 if (options.responseType === "arraybuffer") {
89 data = await response.arrayBuffer();
90 } else {
91 data = await response.text();
92 }
93 options.success?.({
94 statusCode: response.status,
95 data,
96 });
97 }).catch((error) => {
98 // 主动 abort 时交给上层按 fail 处理,行为与小游戏 request 更一致。
99 options.fail?.(error);
100 });
101
102 return {
103 abort: () => controller.abort(),
104 };
105 },
106 };
107}
108
109@frameworkManager()
110export class TsrpcManager extends Singleton<TsrpcManager> implements IFrameworkManager {
111 Name: string = "TsrpcManager";
112
113 /** 登录成功后服务端下发的 token,后续请求会自动带到 Authorization 头里 */
114 private _token: string = "";
115 /** 仅用于服务器请求鉴权,不影响游戏业务时间。 */
116 private serverTimeOffsetMs: number = 0;
117 // private _client: ((MiniappHttpClient<ServiceType> | BrowserHttpClient<ServiceType>)) | null = null;
118 /**
119 * TSRPC 客户端实例。
120 *
121 * 采用懒创建:
122 * - 第一次真正请求接口时创建;
123 * - 后续所有接口复用同一个 client;
124 * - token 变化不需要重建 client,因为请求头注入函数每次会读取最新 this._token。
125 */
126 private _client: (MiniappHttpClient<ServiceType>) | null = null;
127
128 /** 项目入口提供的连接地址;不设置框架默认域名。 */
129 private serverUrl: string | undefined;
130
131 /** 首次请求前设置地址;不支持已创建客户端在运行中切服。 */
132 public SetServerUrl(serverUrl: string): void {
133 if (!serverUrl.trim()) {
134 throw new Error("[TsrpcManager] 服务器地址不能为空");
135 }
136 if (this._client && this.serverUrl !== serverUrl) {
137 throw new Error("[TsrpcManager] 客户端创建后不能切换服务器");
138 }
139 this.serverUrl = serverUrl;
140 }
141
142 /** 框架初始化入口。目前没有额外初始化逻辑,client 会在第一次请求时懒创建。 */
143 public async Init(): Promise<void> {
144 // 记录管理器初始化入口,便于排查启动顺序。
145 Framework.Log.Log(this.Name, "Init", "初始化TSRPC管理器");
146 }
147
148 /** 框架销毁入口。当前只复用懒创建 client,无需额外清理。 */
149 DeInit(): void {
150 // 清除上一会话的鉴权时间偏移。
151 this.serverTimeOffsetMs = 0;
152 }
153
154 /** TSRPC 本身不需要逐帧更新。 */
155 Update(_deltaTime: number): void { }
156
157 /** 当前请求 token,主要用于调试查看。 */
158 get token(): string {
159 return this._token;
160 }
161
162 /**
163 * 设置登录 token。
164 *
165 * LoginManager 登录成功后会调用这里。
166 * 后续所有 TSRPC 请求会自动带上:
167 * Authorization: Bearer ${token}
168 */
169 setToken(token: string): void {
170 this._token = token;
171 }
172
173 /** 接收服务器已校验的时间,修正请求头以满足服务端时间戳要求。 */
174 public SetServerTime(timestamp: number): void {
175 this.serverTimeOffsetMs = timestamp - Date.now();
176 }
177
178 // private getClient(): ((MiniappHttpClient<ServiceType> | BrowserHttpClient<ServiceType>)) {
179 /**
180 * 获取 TSRPC client。
181 *
182 * 这里做了三件事:
183 * 1. 使用项目入口提供的服务端地址;
184 * 2. 注入 serviceProto,保证请求和协议定义严格匹配;
185 * 3. 绑定小游戏平台对象,让 tsrpc-miniapp 能使用 tt/wx/my.request。
186 */
187 private getClient(): MiniappHttpClient<ServiceType> {
188 if (!this._client) {
189 // 缺少入口装配必须明确失败,不能回退到某个项目服务器。
190 if (!this.serverUrl) {
191 throw new Error("[TsrpcManager] 请在首次请求前设置服务器地址");
192 }
193 this._client = new MiniappHttpClient(serviceProto, {
194 server: this.serverUrl,
195 json: true,
196 miniappObj: detectMiniappObj()
197 });
198 this._injectAuthHeader(this._client);
199 }
200 return this._client;
201 }
202
203 /**
204 * 给 TSRPC 底层请求注入 Authorization 头。
205 *
206 * tsrpc-miniapp 的 client 没有在这里直接暴露统一拦截器,所以代码通过访问内部 _http.fetch 包一层:
207 * - 保存原始 fetch;
208 * - 每次请求前追加 timestamp,并在 token 存在时追加 Authorization;
209 * - 再调用原始 fetch。
210 *
211 * 风险点:
212 * - `_http` 是 tsrpc-miniapp 的内部字段,未来库升级可能变化;
213 * - 注入失败会明确打印错误,避免服务器持续返回鉴权或时间戳错误却无法定位。
214 */
215 // private _injectAuthHeader(client: MiniappHttpClient<ServiceType> | BrowserHttpClient<ServiceType>): void {
216 private _injectAuthHeader(client: MiniappHttpClient<ServiceType>): void {
217 try {
218 const httpProxy = (client as unknown as { _http: IHttpProxy })._http;
219 if (!httpProxy || typeof httpProxy.fetch !== "function") return;
220 const origFetch = httpProxy.fetch.bind(httpProxy);
221 const self = this;
222 httpProxy.fetch = function (options) {
223 options.headers = {
224 ...options.headers,
225 // 仅鉴权请求应用校时;业务始终读取设备时间。
226 timestamp: String(Date.now() + self.serverTimeOffsetMs),
227 };
228 if (self._token) {
229 options.headers = {
230 ...options.headers,
231 Authorization: `Bearer ${self._token}`,
232 };
233 }
234 return origFetch(options);
235 };
236 } catch (error) {
237 console.error("[TsrpcManager] 注入 Authorization/timestamp 请求头失败", error);
238 }
239 }
240
241 /**
242 * 通用 TSRPC API 调用。
243 *
244 * 这是 TsrpcManager 对外暴露的唯一请求入口。
245 * 业务层不要直接在这里增加登录、存档等业务接口;
246 * 具体业务接口统一放到 Framework.Server。
247 *
248 * 特性:
249 * - 不做节流、不做合并、不替换请求,所有请求都如实发送;
250 * - 传输层错误(未配置服务器、网络不可达等)直接 throw,让调用方 catch;
251 * - 业务层错误(服务端返回的 API 错误)通过 isSucc=false 正常返回。
252 */
253 public async callApi<T extends keyof ServiceType["api"]>(
254 apiName: T,
255 req: ServiceType["api"][T]["req"],
256 ): Promise<ApiReturn<ServiceType["api"][T]["res"]>> {
257 return await this.getClient().callApi(apiName, req);
258 }
259}
讲解260 行
TSRPC 服务端请求入口人工通读
TsrpcManager.ts
封装 tsrpc-miniapp 客户端,第一次请求时才创建并复用,按 tt、wx、my、jd 探测宿主 request,浏览器下用 fetch 适配。请求底层包一层补时间戳与 token,业务统一走 callApi。
先读 detectMiniappObj 与浏览器适配层,再看 SetServerUrl 的不可切换约束,然后读 getClient 的懒创建与 _injectAuthHeader 的注入,最后看 callApi。
特殊处理与易错点
- 初始化顺序依赖客户端一旦创建就不允许再改服务器地址,SetServerUrl 会抛错;入口必须在任何请求之前完成设置。L136
- 单例/静态状态token 变更不会重建 client,注入函数每次请求都读最新的 this._token,因此登录前后共用同一个客户端。L169
- 特殊处理SetServerTime 保存的是 timestamp 减当前时间的偏移量,请求头用当前时间加偏移还原服务器时间,业务时间仍取本机。L174
- 易错点请求头是通过替换 client 内部 _http.fetch 注入的,依赖 tsrpc-miniapp 私有字段,库升级后可能静默失效,失败只打控制台。L218
- 缓存与销毁时机DeInit 只清掉时间偏移,client 与 token 都保留,同一进程内重新初始化会复用上一会话的鉴权状态。L151
- 渠道差异非小游戏环境的浏览器适配层用 fetch 并支持 abort,但 GET 时丢弃 data,响应按 responseType 决定返回文本还是二进制。L45
39方法按抖音微信支付宝京东顺序探测宿主,否则尝试浏览器适配。
52属性url(string):该模块的运行态字段。
73方法构造小游戏request形态的浏览器适配器,内部使用fetch发请求。
75方法用fetch发送适配请求并按文本或二进制回调,提供主动中止句柄。
99注释主动 abort 时交给上层按 fail 处理,行为与小游戏 request 更一致。
110注释TsrpcManager:TSRPC 客户端:懒创建 HttpClient,注入 Authorization/time
111属性管理器名称,日志里的模块标识。
114属性登录成功后服务端下发的 token,注入函数每次请求时读取,getter 供调试查看。
116属性服务器时间与本机时间的偏移,仅用于请求头,不影响游戏业务时间。
126注释TSRPC 客户端实例。 采用懒创建: - 第一次真正请求接口时创建; - 后续所有接口复用同一个 client; - token 变化不需要重建 client,因为请求头注入函数每次会读取最新 this._token。
129属性项目入口设置的服务地址,框架不提供默认域名。
132方法校验地址非空后保存;若客户端已创建且地址不同则直接抛错,禁止运行中切服。
143方法只写一条初始化日志,不创建客户端,客户端留到第一次请求时懒创建。
145注释记录管理器初始化入口,便于排查启动顺序。
149方法把服务器时间偏移清零,客户端实例与 token 都保留不动。
151注释清除上一会话的鉴权时间偏移。
155方法空实现,请求由 Promise 驱动,没有逐帧任务。
158方法只读返回当前请求使用的 token,主要用于调试查看登录状态。
169方法覆盖当前 token,不做校验也不重建客户端,后续请求立即生效。
174方法用服务器时间戳减本机当前时间算出偏移,供请求头校时使用。
187方法没有实例时检查地址并新建客户端、注入协议与宿主对象,再包一层鉴权请求头后返回。
190注释缺少入口装配必须明确失败,不能回退到某个项目服务器。
216方法取客户端内部 http 代理保存原 fetch,替换为每次请求补时间戳与鉴权头后转发的新函数。
226注释仅鉴权请求应用校时;业务始终读取设备时间。
253方法把接口名与请求对象原样转给底层客户端,等待并返回服务端的 ApiReturn。