@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.6 → 1.0.0-cg.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,207 @@
1
+ # 从 GitHub 上游 RTM SDK 迁移到当前 SDK
2
+
3
+ ## 对照基线与范围
4
+
5
+ 本文对照的是上游 [`highras/rtm-client-sdk-websocket`](https://github.com/highras/rtm-client-sdk-websocket),`master` 分支在 2026-10-13 检查到的 commit [`afe69746fea1444687f8999e9de05cbbb4838400`](https://github.com/highras/rtm-client-sdk-websocket/tree/afe69746fea1444687f8999e9de05cbbb4838400),不是 npm 上的 `rtm-fpnn-webjs-sdk@1.0.4`。上游 `master` 会继续变化,因此本页以该 commit 固定对照;当前仓库以实际工作区实现为新版本基线。
6
+
7
+ 上游源码的包元数据版本为 `1.0.0`。npm 已发布包可能与该 commit 不同;本文不声称 GitHub `master` 与某个 npm tarball 完全一致。如果项目使用 fork、内部构建或 npm 锁定版本,请先核对项目实际运行的源码。
8
+
9
+ 本次重新拉取 GitHub `master` 后,HEAD 仍为上述 commit。逐方法对照结果:上游有 91 个 `RTMClient` 类方法,当前有 105 个公开类方法;没有删除或改名原有方法,新增 14 个,3 个原有方法扩展了签名。此计数不包含构造器、getter、私有辅助方法或动态挂载的事件方法。
10
+
11
+ 本页讨论浏览器端 RTM SDK。服务端 SDK 的 `RTMServerClient`、`get_token`、`get_online_users`、`send_messages`、`broadcast_message` 等接口不属于这里的 `RTMClient` 迁移范围。
12
+
13
+ ## 先看结论
14
+
15
+ - 只把上游的 `RTMClient` 换成当前 SDK 的 `RTMClient` 并继续使用 FPNN,核心构造参数、登录调用、重连默认值和 FPNN Push 事件基本保持一致,通常是低成本迁移。
16
+ - 当前 SDK 新增的 `createClient()` 在浏览器支持 SharedWorker 时共享同 UID 的连接;不支持时自动退回当前页面的独立连接。支持时它会改变连接所有权和多窗口生命周期;若始终要“一页一个客户端连接”,继续使用 `RTMClient`,或设置 `sharing: false`。
17
+ - 当前 SDK 还支持 TLV v1。TLV 是显式协议迁移:Push 名称、事件字段、错误结构和支持范围与 FPNN 不完全相同,不能只替换 endpoint。
18
+
19
+ ### 从本 SDK 旧版升级时的协议默认值变化
20
+
21
+ 这项差异不是上游 `RTMClient` 的迁移差异:此前本 SDK 的 `createClient()` 和 `RTMSharedWorkerClient` 在省略协议时默认使用 TLV v1;当前版本统一改为默认 FPNN,以匹配旧 `RTMClient` 的默认协议。若旧代码只提供 `tlvEndpoint` / `tlv_endpoint`、没有写 `protocol`,升级后会因缺少 FPNN `endpoint` 而在创建客户端时抛错。请显式补上 `protocol: 'tlv-v1'`;FPNN 调用则使用 `endpoint` 或 `ssl_endpoint` 并可省略 `protocol`。不要依赖 endpoint 字段自动推断协议。
22
+
23
+ ## FPNN 接入:原有调用基本沿用
24
+
25
+ ### 首先替换包引用
26
+
27
+ | 原项目接入方式 | 迁移改动 |
28
+ | --- | --- |
29
+ | 使用 `rtm-fpnn-webjs-sdk`,或直接引用上游源码 | 替换为 `@cg-devcenter/rtc-fpnn-webjs-sdk` 的实际发布包或当前构建。ESM 使用 `import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk'`,也支持具名导入。CommonJS 使用 `require('@cg-devcenter/rtc-fpnn-webjs-sdk')`。 |
30
+ | HTML 加载旧 `dist/rtm.min.js` | 替换 SDK 文件;UMD 仍提供 `window.rtm`,业务构造和调用可以沿用。 |
31
+ | 为 SDK 加载 `fpnn`、`msgpack`、`md5`、`Int64BE` 四个全局依赖 | 当前 SDK 已打包这些依赖,单纯供 SDK 使用时不再需要分别加载。若业务代码仍直接访问这些全局变量,需继续提供它们或调整业务引用;包根不额外导出 `fpnn` 全局。 |
32
+ | 深层引用旧包的 `src/*`、`libs/*` | 改用包根的公开导出;当前 npm `files` / `exports` 不提供这些旧内部路径。 |
33
+
34
+ 例如旧代码用 `fpnn.FPConfig.ERROR_CODE.FPNN_EC_OK` 判断登录错误码,移除独立 FPNN 脚本后该全局变量不会由新 SDK 自动创建。登录时应按已有 `callback(accepted, errorCode)` 检查 `accepted`;也可以保留业务确实依赖的外部 FPNN 运行时。当前 SDK 内部仍优先使用已注入的兼容全局依赖。
35
+
36
+ 只替换包引用并继续 `new RTMClient(...)`,不会自动启用共享连接,也不要求部署 Worker 或切换 TLV。
37
+
38
+ 上游 `master` 使用 `new RTMClient(options)` 提供 `pid` 和 `endpoint` 或 `ssl_endpoint`,再用 `login(uid, token, callback, timeout)` 登录。UID 和 token 不在构造参数中;上游也没有要求业务先调用 dispatch 发现流程。当前 SDK 的 `RTMClient` 保留这套 FPNN 接入方式。
39
+
40
+ | 上游 GitHub `master` | 当前 SDK 的 FPNN `RTMClient` | 迁移说明 |
41
+ | --- | --- | --- |
42
+ | `new RTMClient({ pid, endpoint })` | 相同 | `endpoint` 仍是 FPNN Gate 的 `host[:port]`。 |
43
+ | `ssl_endpoint` | 相同 | 使用部署方提供的 SSL Gate 地址;当前 FPNN 配置要求 `host[:port]`,不要把 TLV WebSocket URL 当作 FPNN endpoint。 |
44
+ | `login(uid, token, callback, timeout)` | 相同 | token/credential 仍应由业务服务端签发。 |
45
+ | `autoReconnect` 默认 `true` | 默认 `true` | 无需为了保持上游默认值而改配置。 |
46
+ | `connectionTimeout`、`maxPingIntervalSeconds`、`attrs`、`platformImpl`、`md5`、`regressiveStrategy` | 保留 | 逐项按当前[接入指南](USAGE.md)确认配置约束。 |
47
+ | `ErrorRecorder`、`ReloginCompleted`、`SessionClosed` | 保留 | 事件名和主要用途不变;单个业务请求错误仍检查该请求的 callback/Promise。 |
48
+ | `client.processor.on(RTMConfig.SERVER_PUSH...)` | 保留 | FPNN 事件名及按消息类型拆分 Push 的行为沿用上游处理方式。 |
49
+
50
+ ```js
51
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
52
+
53
+ // 保留上游的一页一个客户端连接行为
54
+ const client = new rtm.RTMClient({
55
+ protocol: 'fpnn',
56
+ pid,
57
+ endpoint: 'rtm-gate.example.com:13321',
58
+ autoReconnect: true,
59
+ });
60
+
61
+ client.processor.on(rtm.RTMConfig.SERVER_PUSH.recvChat, (message) => {
62
+ console.log('chat', message);
63
+ });
64
+
65
+ client.login(uid, credential, (accepted, errorCode) => {
66
+ if (!accepted) console.error('RTM login failed', errorCode);
67
+ }, 30_000);
68
+ ```
69
+
70
+ ### 不使用 SharedWorker 时的兼容边界
71
+
72
+ 当使用 `new RTMClient({ protocol: 'fpnn', ... })`,或使用 `createClient({ sharing: false, protocol: 'fpnn', ... })` 时,当前 SDK 为每个客户端实例创建自己的 FPNN 连接。这与上游 `RTMClient` 的连接模型一致:多个页面各自创建客户端时,仍然是多个独立连接;不会自动跨页面共享登录态或转发 Push。当前 FPNN 请求仍由 `fpnn.FPClient` 承载,常用登录、发送 API 和 `RTMConfig.SERVER_PUSH` 事件名沿用上游。
73
+
74
+ 这表示**接入模型和常见 FPNN 业务行为基本兼容,不表示实现逐行相同或所有异常时序都完全相同**。当前 SDK 在连接生命周期中增加了过期连接隔离和登录/重连竞态保护,降低旧连接回调影响新连接的风险;这些属于实现层修复,边界时序下的事件先后可能与上游不同。
75
+
76
+ 还需注意以下差异:
77
+
78
+ - 当前 FPNN `endpoint` / `ssl_endpoint` 会校验为 `host[:port]`,不接受 URL scheme、路径、查询或片段;上游示例也使用 `host:port`,但当前版本会更早、明确地拒绝格式错误的地址。上游把普通 endpoint 的端口 `13325` 规范化为 `13321`,当前版本保留该兼容处理。
79
+ - 默认 `autoReconnect: true` 与上游一致。当前版没有为了 FPNN 迁移改变这一默认值。
80
+ - `login(uid, token, callback, timeout)`、FPNN Push 名称及普通 API 参数顺序沿用上游;当前版另外提供 Promise facade 和一批新增 API,见下表。
81
+ - `getUnreadMessage` 新增可选 `withLogout`,`removeSession` 新增可选 `localOnly`,`bye` 新增可选超时和 callback。旧 JavaScript 调用形式仍可用;当前类型声明也保留旧调用重载,只有需要新语义时才传新增参数。
82
+ - `createClient()` 即使默认协议为 FPNN,也会在 SharedWorker 可用时优先共享;浏览器没有 SharedWorker API 时自动使用独立连接。需要始终独立时,应使用 `RTMClient` 或显式设置 `sharing: false`;只设置 `protocol: 'fpnn'` 不会关闭可用时的共享。
83
+
84
+ 共享模式下,当前 `createClient()` 通过 SharedWorker 按 PID、协议、UID 和 Gate 地址复用连接;首次登录的页面提供 credential,同身份的其他页面复用会话。
85
+
86
+ ```js
87
+ // 选择共享连接;省略 protocol 时当前默认 FPNN
88
+ const client = rtm.createClient({ pid, endpoint: 'rtm-gate.example.com:13321' });
89
+ await client.promises.login(uid, credential);
90
+
91
+ // 如果使用 createClient 但要保留独立连接
92
+ const independentClient = rtm.createClient({
93
+ sharing: false,
94
+ pid,
95
+ protocol: 'fpnn',
96
+ endpoint: 'rtm-gate.example.com:13321',
97
+ });
98
+ ```
99
+
100
+ 浏览器应用无需自行维护 Worker 名称或 URL。共享连接要求页面同源,并使用一致的连接配置;完整身份规则、生命周期和构建工具配置见[默认共享接入](USAGE.md#默认共享接入)。
101
+
102
+ ### 启用 SharedWorker 后真正需要调整的地方
103
+
104
+ 工作区构建版本 `1.0.0-cg.8` 的 `createClient()` 会在配置不能安全传递给 Worker 时使用页面内 `RTMClient`,并通过 `getConnectionInfo()` 报告原因。npm `latest` `1.0.0-cg.7` 尚未包含这项配置回退和诊断;该版仅在浏览器缺少 SharedWorker 时使用页面内连接。`cg.8` 尚未发布到 npm。
105
+
106
+ | 接入部分 | 迁移要求 |
107
+ | --- | --- |
108
+ | 创建客户端 | 将 `new RTMClient(options)` 改成 `createClient(options)`;默认 FPNN,SharedWorker 可用时共享、不可用时自动独立连接。UID 可继续从 `login()` 参数取得。 |
109
+ | 登录 | 首次提供 credential,同 UID 的其他页面复用或加入同一次登录。共享层协调登录,认证请求由底层 SDK 执行。 |
110
+ | 业务 API、结果和事件 | FPNN 方法名、callback / Promise 结果和 Push 名称沿用底层 SDK;包括 `fileToken` 和三种文件发送。Worker 不维护业务禁用名单。 |
111
+ | 组件卸载 / 页面关闭 | 使用 `destroy()` 解绑当前页面;`bye()` / `close()` 会结束所有页面共享的 RTC 会话。不要继续用 `close()` 做单页清理。 |
112
+ | 多页配置 | 同 UID 页面需使用相同 PID、协议、Gate 和连接配置;页面需同源并支持 SharedWorker。 |
113
+ | 函数或平台对象配置 | `createClient()` 检测到 `md5`、`platformImpl`、`webSocketFactory`、函数型 metadata 等无法保留到 Worker 的运行时值时,会自动使用当前页面内的 `RTMClient`,完整保留配置行为;用 `getConnectionInfo()` 查看 `mode` 和 `fallbackReason`。直接构造 `RTMSharedWorkerClient` 仍要求配置可传递,并会对不支持的值报出路径和原因。 |
114
+ | 构建和部署 | 普通 HTML 将 Worker 与 SDK 部署在同源同目录;Vite 注册 `/vite-plugin`;Webpack 4 注册 `/webpack4` 插件;Webpack 5 使用包根 ESM 资源解析。 |
115
+ | 会话筛选 | 默认全部 SDK 事件广播到所有页面端口。已有 `conversation` / `setConversation()` 用法继续可用,筛选只在页面适配器中执行。 |
116
+
117
+ 共享层只负责 SDK 实例、登录合并、调用/事件转发和生命周期;消息协议、文件上传、重连、ACK、去重、服务端能力和业务错误由底层 SDK 决定。SDK/Worker 升级时关闭所有旧共享页面,等待默认 5 秒回收旧 Worker 后再打开,避免新旧版本混用。
118
+
119
+ ## 上游 API 与当前 API 的变化
120
+
121
+ 大多数原有 FPNN 方法保留。下面列出确实发生的签名变化,以及新增能力;不要把这些变化与 TLV wire 字段名混为一谈。
122
+
123
+ | 上游 GitHub `master` | 当前 SDK | 影响与迁移方式 |
124
+ | --- | --- | --- |
125
+ | `getUnreadMessage(clear, timeout, callback)` | `getUnreadMessage(clear, withLogout, timeout, callback)`,兼容旧重载 | `withLogout` 用于请求登出时间;旧二参数 timeout-only 和三参数 callback 调用在 JS 与 TypeScript 中均可沿用。 |
126
+ | `removeSession(to, timeout, callback)` | `removeSession(to, localOnly, timeout, callback)`,兼容旧重载 | `localOnly` 用于选择本地/单向删除语义;旧调用继续沿用,未显式提供新布尔参数时 FPNN 请求不增加 `oneway` 字段。 |
127
+ | `bye()` | `bye(timeout, callback)` | 可选设置关闭请求超时并接收结果;无参调用仍可用。关闭后仍应按生命周期说明清理客户端。 |
128
+ | 通过外部 Promise 转换工具封装 callback | `client.promises` | 新增 SDK 自带 Promise facade;旧 callback API 仍保留。 |
129
+ | 只有 `RTMClient` 独立连接 | 新增 `createClient()` / `RTMSharedWorkerClient` | 新增同源多页面共享连接和 Push 路由;只在需要该能力时切换。 |
130
+
131
+ `getUnreadMessage` 和 `removeSession` 的新增布尔参数不是基础接入的必填项。上游调用可继续按原顺序传参;只有需要登出时间或本地删除语义时才传新增参数。`textCheck(text, timeout, callback)` 也有运行时和类型声明兼容重载。继续使用原有 callback 或外部 Bluebird Promise 转换工具时,不必改用新增的 `client.promises`;若主动改用 SDK Promise facade,省略 callback,并按当前参数顺序传入可选位,例如 `client.promises.getUnreadMessage(false, undefined, 15000)`。
132
+
133
+ ### 新增 14 个公开方法
134
+
135
+ 以下为完整 callback 签名;使用 `client.promises` 时省略末尾 callback。这些方法也由 SharedWorker 客户端代理。参数含义见[API 参数说明](USAGE.md#5-参数与返回值约定),FPNN method 与 TLV URI 对照见[协议迁移对照](PROTOCOL_MIGRATION.md)。接入指南中标为 TLV 的返回结构仅适用于 TLV,不应套用到 FPNN。
136
+
137
+ | 完整方法签名 | 用途 / 文档入口 |
138
+ | --- | --- |
139
+ | `getServerTime(timeout, callback)` | 查询服务端时间,见[时间查询](USAGE.md#初始化和生命周期-api)。 |
140
+ | `sendMessages(tos, mtype, msg, attrs, mid, timeout, callback)` | 批量发送私聊消息,见[消息发送](USAGE.md#消息发送和单条消息)。 |
141
+ | `setSessionRead(category, xid, readSeq, timeout, callback)` | 设置会话已读序号上界,见[未读与会话](USAGE.md#未读会话与-push)。 |
142
+ | `getP2PMessageByMessageId(ouid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询私聊历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
143
+ | `getGroupMessageByMessageId(gid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询群历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
144
+ | `getRoomMessageByMessageId(rid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询房间历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
145
+ | `getBroadcastMessageByMessageId(mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询广播历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
146
+ | `getP2PMessageCount(ouid, begin, end, mtypes, timeout, callback)` | 查询私聊消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
147
+ | `getGroupMessageCount(gid, begin, end, mtypes, timeout, callback)` | 查询群消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
148
+ | `getRoomMessageCount(rid, begin, end, mtypes, timeout, callback)` | 查询房间消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
149
+ | `getBroadcastMessageCount(begin, end, mtypes, timeout, callback)` | 查询广播消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
150
+ | `enterRooms(rids, timeout, callback)` | 批量进入房间,见[群组和房间](USAGE.md#群组和房间)。 |
151
+ | `getUserRoomsAndLastMessage(mtypes, timeout, callback)` | 查询用户房间及最近消息,见[群组和房间](USAGE.md#群组和房间)。 |
152
+ | `setRoomProfile(rid, publicData, privateData, label, avatar, timeout, callback)` | 设置房间公共/私有资料、名称和头像,见[群组和房间](USAGE.md#群组和房间)。原 `setRoomInfo` 保留。 |
153
+
154
+ 这 14 项是 `RTMClient` 新增业务方法的统计;`client.promises`、`createClient()` 和 SharedWorker 客户端属于额外的接入能力,不包含在这 14 项中。
155
+
156
+ ### 上游类型声明与源码不一致的地方
157
+
158
+ 以下差异需要按项目实际调用核对;它们不是 JS 方法改名。上游源码与其 `dist/rtm.d.ts` 已有不一致,当前声明更贴近实际源码参数:
159
+
160
+ | API | 上游声明 / 文档 | 上游源码与当前推荐调用 |
161
+ | --- | --- | --- |
162
+ | `getMessage` / `deleteMessage` / `getChat` / `deleteChat` | 上游 `.d.ts` 缺少首个 `from` 参数 | `method(from, mid, xid, type, timeout, callback)`。若 TypeScript 项目按旧声明只传五个参数,需要补发送者 ID;上游 JS 源码本来就要求这个参数。 |
163
+ | `imageCheck` | 声明和文档省略 `strategyId` | `imageCheck(image, type, undefined, timeout, callback)`,有策略时替换 `undefined`。 |
164
+ | `audioCheck` | 声明和文档省略 `strategyId` | `audioCheck(audio, type, lang, codec, srate, undefined, timeout, callback)`。 |
165
+ | `videoCheck` | 声明和文档省略 `strategyId` | `videoCheck(video, type, videoName, undefined, timeout, callback)`。 |
166
+ | `removeSession` 与五种 `get*ConversationList` | 存在于上游 JS,缺失于上游 `.d.ts` | 当前补充了这些声明;这些会话查询不是本次新增的 JS 能力。 |
167
+
168
+ 当前构造配置也有实际类型约束,例如 `pid` 是 number、FPNN endpoint 是 string,使用 TypeScript 的项目应按照真实业务值修正此前被 `any` 隐藏的配置问题。
169
+
170
+ ### 已修复的旧实现行为
171
+
172
+ 上游 `getChat` 错误地递归调用自身,`deleteChat` 向 `deleteMessage` 多传了一个 `this`。当前实现分别正确委托 `getMessage` / `deleteMessage`;方法名和源码签名保留,依赖旧行为的自定义补丁应重新核对。这属于旧实现修复,不能视为逐行行为完全不变。
173
+
174
+ 连接生命周期另外修复了旧连接回调污染新连接、重复重连定时器和 processor 定时器回收问题。FPNN 基础库本体只修改了 UMD 全局对象选择以支持 Worker,MessagePack、MD5、Int64 库与上游文件相同。
175
+
176
+ 当前 SDK 仍保留上游的 `dataGet`、`dataSet`、`dataDelete`、`getGroupMembers(gid, online, timeout, callback)`、历史查询 `mtypes` 参数和 `translate(..., type, profanity, timeout, callback)` 等签名;这些不是迁移差异。也不要将 processor 的 `kickout` Push 事件误认为客户端主动踢人 API。
177
+
178
+ ## 选择 TLV v1 是另一项迁移
179
+
180
+ 继续使用 FPNN 时不需要更换消息事件名称。改用 TLV v1 时,创建客户端需显式设置 `protocol: 'tlv-v1'` 并提供部署方给出的完整 WebSocket URL。TLV Push 使用 `event.direct`、`event.group`、`event.room`、`event.broadcast` 等名称,字段结构也不同;应使用 `RTMConfig.TLV_SERVER_PUSH` 常量和对应契约处理。
181
+
182
+ TLV v1 仅支持[支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵)中标出的 API。未支持的 FPNN API 不会自动回退到 FPNN。FPNN 与 TLV 的业务 API、wire method、URI 和字段对照见[协议迁移对照](PROTOCOL_MIGRATION.md)及[TLV 契约](TLV_CONTRACT.md)。
183
+
184
+ ## 迁移成本判断
185
+
186
+ | 迁移目标 | 预计改动 | 主要检查项 |
187
+ | --- | --- | --- |
188
+ | 上游 `RTMClient` → 当前 `RTMClient`,继续 FPNN | 低 | 包导入、构建方式、credential、Gate 配置;原登录和常用消息代码大多可沿用。 |
189
+ | 改用 `createClient()` 以共享多窗口连接 | 低到中 | 同 UID 页面连接配置一致;处理共享会话生命周期;验证不同窗口收到各自需要的 Push。 |
190
+ | 从 FPNN 切换到 TLV v1 | 中到高 | Push 名称和字段、错误结构、服务端 URI 支持范围、历史和未读行为及文件等不支持 API。 |
191
+
192
+ ## 发布前检查
193
+
194
+ 本次静态审计覆盖公开方法名、签名、FPNN Push 常量和基础库差异;审计时还对 85 个原有方法按历史参数构造模拟请求,比较 FPNN method、payload、timeout 和模拟空应答的 callback 结果。该 85 项回放是一次性审计记录,不由当前回归套件逐项重放。保留的 `test/migration-compatibility.js` 针对新增布尔参数的旧 timeout/callback 调用、显式空参数位、Promise facade,以及 `textCheck` 策略参数进行回归;包类型用例检查旧调用重载。审计发现并修复 `getUnreadMessage(clear, timeout)`、`removeSession(to, timeout)` 省略 callback 时丢失 timeout,以及 `textCheck(text, numericStrategyId, undefined, callback)` 将策略误当 timeout 的问题。`textCheck` 短 timeout 重载和 SDK Promise 简写仍可用,显式四参策略调用按上游源码保留字段。这些检查不替代真实 Gate 验证;文件方法的上游对照回放只覆盖 token 阶段,完整共享上传链路由本地模拟套件覆盖。
195
+
196
+ - 确认正在对照的是上述 GitHub commit,还是业务项目实际锁定的 npm 包、fork 或内部构建。
197
+ - 继续 FPNN 时,先用当前 `RTMClient` 做最小登录、Push、发送和重连验证;不要把 TLV WebSocket URL 填入 FPNN `endpoint`。
198
+ - 若切换到 `createClient()`,明确接受默认共享连接行为;若不需要共享,使用 `RTMClient` 或 `sharing: false`。
199
+ - 搜索项目中 `getUnreadMessage`、`removeSession`、`bye` 的调用,确认新增参数只在业务需要时启用。
200
+ - 切换 TLV v1 时,按支持矩阵逐项检查 API、Push 结构、错误与服务端权限。
201
+
202
+ ## 相关文档
203
+
204
+ - [FPNN 与 TLV v1 协议迁移对照](PROTOCOL_MIGRATION.md)
205
+ - [当前 SDK 接入指南](USAGE.md)
206
+ - [Push 事件说明](EventProcess.md)
207
+ - [当前 SDK 能力总览](CAPABILITIES.md)
package/docs/Rooms.md CHANGED
@@ -6,6 +6,8 @@
6
6
 
7
7
  ## Apis
8
8
 
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。
10
+
9
11
  * `enterRoom(rid, timeout, callback)`: 进入房间
10
12
  * `rid`: **(Required | Int64)** 房间 id
11
13
  * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
package/docs/System.md CHANGED
@@ -6,6 +6,8 @@
6
6
 
7
7
  ## Apis
8
8
 
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。
10
+
9
11
  * `addAttrs(attrs, timeout, callback)`: 设置客户端信息, 保存在当前链接中, 客户端可以获取到
10
12
  * `attrs`: **(Required | object[string, string])** key-value形式的变量
11
13
  * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
package/docs/USAGE.md CHANGED
@@ -6,20 +6,23 @@
6
6
 
7
7
  | 入口 | 运行环境 | 能力范围 |
8
8
  | --- | --- | --- |
9
- | `createClient()` | 支持 SharedWorker 的浏览器 | 推荐入口,默认 TLV、同 UID 多窗口共享连接。 |
10
- | `createClient({sharing: false})` / `RTMClient` + `protocol: 'tlv-v1'` | 浏览器;Node.js 需注入 `webSocketFactory` | 独立连接;本文 TLV v1 支持矩阵列出的 API。 |
9
+ | `createClient()` | 浏览器 | 默认 FPNN;支持 SharedWorker 时共享同 UID 多窗口连接,不支持时自动使用独立连接。 |
10
+ | `createClient({protocol: 'tlv-v1'})` | 浏览器 | 显式选择 TLV v1;支持 SharedWorker 时共享连接,不支持时自动使用独立 TLV 连接;可调用本文支持矩阵列出的 API。 |
11
+ | `createClient({sharing: false, protocol: 'tlv-v1'})` / `RTMClient` + `protocol: 'tlv-v1'` | 浏览器;Node.js 需注入 `webSocketFactory` | 独立 TLV v1 连接;本文 TLV v1 支持矩阵列出的 API。 |
11
12
  | `RTMClient` + `protocol: 'fpnn'` | 浏览器 | 旧版兼容入口;兼容 API 仍受 FPNN 服务端能力和部署配置限制。 |
12
- | `RTMSharedWorkerClient` | 支持 SharedWorker 的浏览器、同源页面 | TLV v1 / FPNN;多个同源页面共享一个 UID 的 RTC 会话,并由 SDK 路由实时 Push。 |
13
+ | `RTMSharedWorkerClient` | 支持 SharedWorker 的浏览器、同源页面 | 显式创建 Worker 客户端;默认 FPNN,指定 TLV v1 时使用 TLV。多个同源页面共享一个 UID 的 RTC 会话,Worker 全量转发 SDK 事件。 |
13
14
 
14
15
  本文给出 TLV v1 方法参数和常见返回约定,不重复 TLV wire 字段的完整 schema。TLV Gate Answer 字段、数据类型和状态码以[TLV v1 Client 契约](TLV_CONTRACT.md)为准;TypeScript 完整声明见 [`dist/rtm.d.ts`](../dist/rtm.d.ts)。`fpnn` 的具体兼容范围以旧服务端为准;旧接口参数说明见[用户](Users.md)、[群组](Groups.md)、[房间](Rooms.md)、[消息](Messages.md)、[聊天](Chat.md)、[数据](Data.md)、[系统](System.md)、[文件](Files.md)、[好友](Friends.md)、[增值服务](ValueAdded.md)和[事件处理](EventProcess.md)文档。
15
16
 
16
17
  需要从 FPNN 迁移到 TLV v1 时,先看 [协议迁移对照](PROTOCOL_MIGRATION.md):它列出了相同 `RTMClient` 业务 API 对应的旧 FPNN method 与 TLV URI,并标明支持边界和兼容差异。
17
18
 
19
+ 如果是从上游 [`highras/rtm-client-sdk-websocket`](https://github.com/highras/rtm-client-sdk-websocket) 迁移,请先看[RTM SDK 迁移指南](RTM_MIGRATION.md)。该指南固定对照 GitHub `master` 的指定 commit;npm 包、fork 或内部构建可能与该源码不同。飞书统计中的服务端调用不属于本浏览器 SDK。
20
+
18
21
  ### 交给测试人员或 AI 接入前
19
22
 
20
23
  请随文提供以下环境信息,避免接入者猜测项目配置或尝试从浏览器获取项目密钥:
21
24
 
22
- - SDK:测试项目可安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。若验证的功能尚未进入 npm `latest`,请同时提供 yalc 链接、本地 tarball 或源码工作区。
25
+ - SDK:测试项目可安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。包根 ESM 与 Vite、Webpack 4 构建插件均已随 npm `latest` 发布。当前工作区包版本 `1.0.0-cg.8` 尚未发布,registry `latest` 仍为 `1.0.0-cg.7`;下文标为工作区新版的 API 需使用本地源码或 `cg.8` 构建产物验证,不属于当前 npm `latest` 的能力。
23
26
  - RTC 环境:`pid`、协议(通常为 `tlv-v1`)、完整 WebSocket endpoint,以及应用页面的 origin。
24
27
  - 测试身份:发送 UID、接收 UID、账号权限和预期验证场景;不要在文档或任务描述中粘贴长期凭证。
25
28
  - credential 获取方式:由哪个业务服务端接口签发、请求需要的登录态/参数、响应 JSON 字段名和 credential 有效期。项目 `SecretKey` 只保留在受控服务端或本机签发工具中。
@@ -29,7 +32,7 @@
29
32
 
30
33
  ### 用于实际项目的实时信令
31
34
 
32
- - 先确认协议、PID、Gate 地址与签发 credential 的服务端属于同一环境。线上 HTTPS 页面使用 WSS;共享 Worker 应部署在应用同源地址,并被站点 CSP 的 `worker-src` 允许。Vite 优先使用 `/vite` 入口。
35
+ - 先确认协议、PID、Gate 地址与签发 credential 的服务端属于同一环境。线上 HTTPS 页面使用 WSS;共享 Worker 应部署在应用同源地址,并被站点 CSP 的 `worker-src` 允许。现代 ESM 项目使用包根入口;Vite 项目增加一次 `/vite-plugin` 插件配置。
33
36
  - 全局信令接收器保持 `conversation: null`;设置会话过滤后,该页面只收到匹配的消息 Push。UI 不可见或失去焦点不会改变 SDK 路由,但浏览器挂起页面会延后 JS 执行,静默回收 Worker 的恢复边界见下文。
34
37
  - SDK 传送实时消息和信令,不提供音视频采集、编解码或媒体连接。业务应定义消息类型、业务 ID、有效期与处理确认;Gate 接受发送不等于对方业务已处理。
35
38
  - 请求中断时发送结果可能未知,SDK 不自动重放。业务根据业务 ID 做幂等处理,并自行决定重试与断线补偿;需要历史补偿时也要确认项目启用对应服务能力。
@@ -37,18 +40,27 @@
37
40
 
38
41
  ## 2. 快速开始:登录、收 Push、发消息、关闭
39
42
 
40
- ### 默认共享接入(当前源码)
43
+ ### 默认共享接入
44
+
45
+ 工作区 `1.0.0-cg.8` 的 `createClient(options)` 优先使用 SharedWorker;浏览器不支持 SharedWorker,或配置中含有无法保留到 Worker 的运行时值(例如函数型 `webSocketFactory`、`md5`、`platformImpl` 或 metadata)时,会自动使用当前页面内的 `RTMClient`。两种模式使用同一个 `createClient()` facade、业务 API、事件和 Promise 接口;页面内模式不共享连接或登录态。该版本可通过 `client.getConnectionInfo()` 读取 `{ mode: 'shared' | 'direct', fallbackReason: string | null }`。`sharing: false` 会主动选择页面内模式,`fallbackReason` 为 `null`。Worker 脚本加载失败、初始化失败或超时仍会报告错误,不会静默改成页面内连接。省略 `protocol` 时默认使用 FPNN;直接构造 `RTMSharedWorkerClient` 表示明确要求 Worker,不能传输的配置会抛出具体原因。只有显式设置 `protocol: 'tlv-v1'` 才选择 TLV v1。npm `latest` `1.0.0-cg.7` 包含 `createClient()` 入口和 FPNN SharedWorker 扩展,但尚不支持配置值导致的自动直连回退,也没有 `getConnectionInfo()`;这些能力尚未发布到 npm。当前 npm 版本仍会在浏览器缺少 SharedWorker 时使用页面内连接。共享连接按 PID、协议、UID 和 Gate endpoint 区分环境;两个共享入口在连接参数一致时可复用同一会话。
41
46
 
42
- 新入口 `createClient(options)` 默认启用 SharedWorker,默认使用 TLV;显式 `protocol: 'fpnn'` 也可共享。请使用 npm `latest` 标签对应的版本;若该标签尚未包含此入口或 FPNN 共享扩展,请使用本地构建/yalc。旧 `RTMClient`、`RTMSharedWorkerClient` 的业务 API 保留;SharedWorker 自动按 PID、协议、UID 和 Gate endpoint 区分环境;同一环境下两种 SDK 入口复用同一会话。
47
+ ```js
48
+ const client = rtm.createClient({ pid, endpoint, webSocketFactory });
49
+ if (typeof client.getConnectionInfo === 'function') {
50
+ console.log(client.getConnectionInfo());
51
+ // { mode: 'direct', fallbackReason: 'options.webSocketFactory is a function; SharedWorker cannot preserve page-side function behavior' }
52
+ }
53
+ ```
43
54
 
44
- Vite 项目从 `/vite` 导入,普通 HTML 把 SDK 与 Worker bundle 部署到同源目录;业务不需要填写 Worker 名称。下面可作为 Vite 页面脚本使用,替换项目配置和 credential 接口:
55
+ 现代 ESM 项目从包根导入。Worker URL 按构建工具解析:Vite 开发模式在 `vite.config.js` 注册一次 SDK 插件,避免依赖预构建将 SDK 的 `import.meta.url` 移入 `.vite/deps`;生产 Worker 资源由 Vite 构建输出。Webpack 4 注册 SDK 的 `/webpack4` 插件;Webpack 5 使用包根 ESM 入口和标准资源解析。普通 HTML 将 SDK 脚本和 Worker 文件放在同源同目录。上述常规方式都不需要业务传 `workerUrl`;只有自定义 Worker 部署位置时才需要覆盖它。旧 `/vite` 入口继续兼容。包根 ESM 与构建插件已包含在 npm `latest` 中。下面可作为 Vite 页面脚本使用,替换项目配置和 credential 接口:
45
56
 
46
57
  ```js
47
- import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
58
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
48
59
 
49
60
  const uid = '10001';
50
61
  const peerUid = '10002';
51
62
  const client = rtm.createClient({
63
+ protocol: 'tlv-v1',
52
64
  pid: 12345,
53
65
  tlvEndpoint: 'wss://<gate-host>/service/websocket',
54
66
  autoReconnect: true,
@@ -87,15 +99,15 @@ UID 使用正整数或十进制字符串;超过 JavaScript 安全整数范围
87
99
 
88
100
  | 配置 / API | 默认与边界 |
89
101
  | --- | --- |
90
- | `createClient(options)` | 使用扁平客户端配置,默认 `sharing: true`、`protocol: 'tlv-v1'`;浏览器没有 SharedWorker 时明确抛出 `RTM_SHARED_WORKER_UNSUPPORTED`。 |
91
- | `sharing: false` | 返回独立的 `RTMClient`,新入口仍默认 TLV;Node.js 或需要文件上传/函数型配置时显式选择,FPNN 仍仅支持浏览器。不会因共享初始化失败自动降级。 |
102
+ | `createClient(options)` | 使用扁平客户端配置,默认优先共享、协议默认 `fpnn`;无法使用 SharedWorker 或配置含不可传输的运行时值时,自动回退为当前页面连接,并可用 `getConnectionInfo()` 查询模式和原因。 |
103
+ | `sharing: false` | 显式选择页面内连接,但仍返回相同的 `createClient()` facade。Node.js 使用 TLV 时传 `protocol: 'tlv-v1'` 和 `webSocketFactory`;FPNN 仍仅支持浏览器。 |
92
104
  | `uid` | 可选;提供时立即挂接共享 Worker,适合收件箱自动观察其他页面登录。省略时在 `login()` / `loginIfNeeded()` / `whenReady(uid)` 时挂接。一个实例固定一个 UID;切换账号需 detach 后创建新实例。 |
93
- | `workerName` / `workerUrl` | 可选高级覆盖项;默认共享身份由 PID、协议、UID 和 Gate endpoint 生成,endpoint 不需要单独配置。默认路径沿用脚本同目录规则,Vite `/vite` 自动打包。`workerNamespace` 仍可隔离应用。 |
105
+ | `workerName` / `workerUrl` | 可选高级覆盖项;常规接入不需要配置 `workerUrl`。默认共享身份由 PID、协议、UID 和 Gate endpoint 生成,endpoint 不需要单独配置。普通 HTML 使用脚本同目录规则;Vite 使用 `/vite-plugin`;Webpack 4 使用 `/webpack4`;Webpack 5 使用标准 ESM 资源解析。只有自定义 Worker 部署位置时才传同源 `workerUrl`。`workerNamespace` 仍可隔离应用。 |
94
106
  | `whenReady(uid?)` | 等待首次挂接并返回当时的快照;后续状态用 `getSharedSession()` 或 `SharedSessionState` 读取。尚未绑定 UID 且未传 UID 时立即 reject `RTM_SHARED_UID_REQUIRED`,不会无限等待。 |
95
107
  | `promises.login(uid, credential?, timeout?)` | 成功 resolve `{accepted: true, errorCode}`,RTC 拒绝或本地/Worker 错误 reject;并发同 UID 登录只发一次鉴权。`loginIfNeeded()` 保留 `{accepted, errorCode, reused, uid}` 的结果约定。 |
96
- | `login(uid, credential?, callback?, timeout?)` | RTC 拒绝与本地/Worker 失败均回调 `callback(false, numericCode)`;本地/Worker 失败的详细错误通过 `SharedWorkerError` 事件提供。仅 `accepted === true` 表示登录成功;`promises.login()` 会 reject 详细错误。 |
97
- | `destroy()` | 只 detach 当前页面;最后一页离开后按 `idleShutdownTimeout` 回收共享连接。`bye()` / `close()` 才结束所有共享页面的会话。 |
98
- | 会话路由与业务 API | 沿用 `setConversation()`、`processor`、重连和原协议的业务返回;共享模式不支持文件发送或函数型配置。绑定 UID 前的业务请求明确报 `RTM_SHARED_UID_REQUIRED`。 |
108
+ | `login(uid, credential?, callback?, timeout?)` | RTC 拒绝回调 `callback(false, numericCode)`;共享模式的本地/Worker 失败会通过 `SharedWorkerError` 提供详情。仅 `accepted === true` 表示登录成功;`promises.login()` 会 reject 详细错误。 |
109
+ | `destroy()` | 共享模式只 detach 当前页面;最后一页离开后按 `idleShutdownTimeout` 回收共享连接。独立模式关闭本页的 RTMClient。`bye()` / `close()` 结束当前连接。 |
110
+ | 会话路由与业务 API | 沿用 `setConversation()`、`processor`、重连和原协议的业务返回;业务能力由底层 `RTMClient` 决定,FPNN 文件发送可用。`createClient()` 会为函数或自定义实例配置自动选择页面内模式;直接 `RTMSharedWorkerClient` 则要求配置可传给 Worker。绑定 UID 前的业务请求明确报 `RTM_SHARED_UID_REQUIRED`。 |
99
111
 
100
112
  共享还要求同一浏览器配置文件、origin 和 Worker URL。同一浏览器配置文件、origin、Worker URL、PID、协议、UID 和 Gate endpoint 的页面会复用一条连接;Gate 地址不同会自动隔离。**同一共享身份下的 `clientOptions` 必须一致**;认证、重连或其他参数不同会初始化失败,不会覆盖已有连接。`createClient()` 和 `RTMSharedWorkerClient` 自动使用相同规则,同一应用混用入口也能加入同一会话。显式传入 `workerName` 或 `workerNamespace` 时,共享页面仍须保持一致。
101
113
 
@@ -182,13 +194,48 @@ Gate endpoint 已自动区分测试、预发和生产环境,通常不需要设
182
194
  const rtm = require('@cg-devcenter/rtc-fpnn-webjs-sdk');
183
195
  ```
184
196
 
185
- Vite 项目可从专用 ESM 入口导入;该入口会把 SharedWorker 脚本作为构建资源并自动传给 `RTMSharedWorkerClient`,不需要手动写 Worker 文件路径:
197
+ 现代 ESM 项目可从包根入口导入。Vite 项目在 `vite.config.js` 注册一次 SDK 插件,处理开发依赖预构建;SDK 的 ESM Worker 资源由 Vite 输出并自动传给 `RTMSharedWorkerClient`。应用代码不需要填写 Worker 路径:
198
+
199
+ ```js
200
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
201
+ ```
186
202
 
187
203
  ```js
188
- import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
204
+ // vite.config.js
205
+ import { rtmSdkVitePlugin } from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite-plugin';
206
+
207
+ export default {
208
+ plugins: [rtmSdkVitePlugin()],
209
+ };
189
210
  ```
190
211
 
191
- 浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 取 SDK。Node.js 仅支持 TLV v1;需要在 `RTMClient` 选项中传入 `webSocketFactory(url)`,返回对象须支持 `send(data)`、`close(code?, reason?)` 及 `onopen`、`onmessage`、`onerror`、`onclose`。SDK 不附带 Node WebSocket 实现。`fpnn` 和 SharedWorker 仅面向浏览器。
212
+ Vue 2 / Webpack 4 项目在 Webpack 配置中注册 SDK 插件一次。它会随构建输出 Worker 资源并处理 `publicPath`,业务代码仍从包根导入 SDK,也不需要传 `workerUrl`:
213
+
214
+ ```js
215
+ // webpack.config.js
216
+ const RTMSDKWebpack4Plugin = require('@cg-devcenter/rtc-fpnn-webjs-sdk/webpack4');
217
+
218
+ module.exports = {
219
+ plugins: [new RTMSDKWebpack4Plugin()],
220
+ };
221
+ ```
222
+
223
+ Webpack 5 项目从包根 ESM 入口导入即可使用标准资源解析,不需要 SDK 插件。无论使用 Vue、React 还是普通 JS,页面里的客户端创建方式相同。
224
+
225
+ 浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 取 SDK。Node.js 仅支持 TLV v1;通过 `RTMClient` 或 `createClient()` 传入 `webSocketFactory(url)`,返回对象须支持 `send(data)`、`close(code?, reason?)` 及 `onopen`、`onmessage`、`onerror`、`onclose`。`createClient()` 在 Node.js 会报告 direct 模式。SDK 不附带 Node WebSocket 实现。`fpnn` 和 SharedWorker 仅面向浏览器。
226
+
227
+ 若用 unpkg 或 jsDelivr 加载 `rtm.min.js`,不要让 SDK 自动推导共享 Worker 地址:推导出的 Worker 会落在 CDN 域名,与业务页面不同源。可把同版本的 `rtm.shared-worker.js` 部署到应用自己的同源静态目录,并显式传入 `workerUrl`;如果不需要多页面共享,可设置 `sharing: false`。例如:
228
+
229
+ ```js
230
+ const client = window.rtm.createClient({
231
+ pid,
232
+ endpoint,
233
+ uid,
234
+ workerUrl: '/sdk/rtm.shared-worker.js',
235
+ });
236
+ ```
237
+
238
+ SharedWorker 仍要求 Worker 与页面同源;仅配置跨域 CORS 不会满足此限制。常规 npm bundler 接入和应用同源 HTML 部署不受此 CDN 注意事项影响。
192
239
 
193
240
  ## 3. 生命周期与错误处理
194
241
 
@@ -215,13 +262,15 @@ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
215
262
  | --- | --- | --- | --- |
216
263
  | `pid` | `number` | 必填 | RTC 项目 ID。 |
217
264
  | `protocol` | `'tlv-v1' \| 'fpnn'` | 默认 `'fpnn'` | 新接入请显式设为 `'tlv-v1'`。 |
265
+ | `endpoint` | `string` | FPNN 必填 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `ws://`。 |
266
+ | `ssl_endpoint` | `string` | FPNN 可选 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `wss://`;提供时优先于 `endpoint`。 |
218
267
  | `tlvEndpoint` | `string` | TLV 必填 | Gate 提供的完整 `ws://` 或 `wss://` URL,含部署要求的路径,通常以 `/service/websocket` 结尾。 |
219
268
  | `autoReconnect` | `boolean` | `true` | 自动重连开关。终止性鉴权错误不会无限重试。 |
220
269
  | `connectionTimeout` | `number` | `30000` | 建立 WebSocket 连接的超时。 |
221
270
  | `requestTimeout` | `number` | `20000` | 请求默认超时;方法级 `timeout > 0` 时覆盖此值。 |
222
- | `requestMetadata` | `object \| (() => object)` | 可选 | TLV v1 只发送 `trace`、`sent_ms`。禁止放 credential、SecretKey 等敏感字段。SharedWorker 仅接受静态对象。 |
223
- | `requestMetadataProvider` | `() => object` | 可选 | `requestMetadata` 函数形式的兼容选项;SharedWorker 不支持函数。 |
224
- | `webSocketFactory` | `(url) => RTMWebSocket` | Node 必填 | 自定义 WebSocket 工厂。浏览器通常使用全局 `WebSocket`。 |
271
+ | `requestMetadata` | `object \| (() => object)` | 可选 | TLV v1 只发送 `trace`、`sent_ms`。禁止放 credential、SecretKey 等敏感字段。SharedWorker 仅接受静态可传输对象;函数形式会使 `createClient()` 回退到页面内连接。 |
272
+ | `requestMetadataProvider` | `() => object` | 可选 | `requestMetadata` 函数形式的兼容选项;通过 `createClient()` 使用时会自动选择页面内连接。 |
273
+ | `webSocketFactory` | `(url) => RTMWebSocket` | Node 必填 | 自定义 WebSocket 工厂。浏览器通常使用全局 `WebSocket`;`createClient()` 会在配置该函数时选择页面内连接。 |
225
274
  | `authSec` / `authVer` | `number` / `2` | 可选 | 自签鉴权字段;须同时提供,且 `authVer` 必须为 `2`。 |
226
275
  | `locale` / `clientVersion` | `string` | 可选 | 登录语言和客户端版本。未提供版本时 SDK 使用内置版本字符串。 |
227
276
  | `attrs` | `Record<string, string>` | 可选 | 登录连接属性。 |
@@ -262,19 +311,21 @@ Promise 成功表示 Gate 已应答关闭请求。直接结束整个会话可调
262
311
 
263
312
  ## 4. 同 UID 多窗口:SharedWorker
264
313
 
265
- `RTMSharedWorkerClient` 是 SDK 提供的同源多页面连接复用能力。每个页面创建一个客户端端口,SDK 在 SharedWorker 内维护一个 `RTMClient` 和一条 WebSocket。普通浏览器脚本加载时,SDK 默认从主 SDK 脚本地址推导同目录下的 `rtm.shared-worker.js`;部署在其他位置时,需显式传入同源 `workerUrl`。Vite 项目推荐从 `@cg-devcenter/rtc-fpnn-webjs-sdk/vite` 导入,SDK 会自动把 Worker 作为构建资源并配置地址。其他构建工具可在其资源管线支持时导入 `@cg-devcenter/rtc-fpnn-webjs-sdk/shared-worker?url`,再将解析出的 URL 传给 `workerUrl`。共享身份需要相同浏览器配置文件、origin、解析后的 Worker URL、`workerName` 和结构一致的 `clientOptions`。一个 Worker 只登录一个 UID、使用一种协议;传入 `uid` 后,SDK 根据协议、PID、UID 和实际 Gate endpoint 自动生成稳定身份,因此不同 Gate 环境自动使用不同连接;同一名称下其他 `clientOptions` 不一致会明确报错。`createSharedWorkerName()` 可显式传 `endpoint` 构造隔离名称。SDK 升级后请刷新同一 origin 下需要共享会话的旧页面,避免新旧版本各自挂在不同 Worker 身份上。
314
+ SharedWorker 是 SDK 实例和登录状态的共享底座:负责端口、同 UID 登录合并、调用转发和生命周期。协议实现、业务 API、文件上传、重连、ACK 和去重均由底层 `RTMClient` 执行,公开业务方法从 SDK 自动代理。Worker 不检查消息类型、不筛选业务事件,也不增加业务能力限制。`conversation` / `setConversation()` 是页面端的可选筛选工具。
315
+
316
+ `RTMSharedWorkerClient` 是 SDK 提供的同源多页面连接复用能力。每个页面创建一个客户端端口,SDK 在 SharedWorker 内维护一个 `RTMClient` 和一条 WebSocket。常规接入无需手写 `workerUrl`,Worker URL 按构建方式自动解析:普通 HTML 从主 SDK 脚本地址推导同目录下的 `rtm.shared-worker.js`;Vite 项目在配置中注册 `/vite-plugin`;Webpack 4 项目注册 `/webpack4` 插件;Webpack 5 项目从包根 ESM 入口使用标准资源解析。旧 `/vite` 入口继续兼容。只有自定义 Worker 部署位置时才显式传入同源 `workerUrl`。Vue、React 和普通 JS 使用相同的 SDK API,具体 Worker 配置由构建工具决定。共享身份需要相同浏览器配置文件、origin、解析后的 Worker URL、`workerName` 和结构一致的 `clientOptions`。一个 Worker 只登录一个 UID、使用一种协议;传入 `uid` 后,SDK 根据协议、PID、UID 和实际 Gate endpoint 自动生成稳定身份,因此不同 Gate 环境自动使用不同连接;同一名称下其他 `clientOptions` 不一致会明确报错。`createSharedWorkerName()` 可显式传 `endpoint` 构造隔离名称。SDK 升级后请关闭同一共享身份的所有旧页面,等待 `idleShutdownTimeout`(默认 5 秒)后重新打开,确保旧 Worker 结束并加载新脚本;新旧页面/Worker 版本混用不受支持。
266
317
 
267
318
  | API / 选项 | 参数与结果 |
268
319
  | --- | --- |
269
- | `new RTMSharedWorkerClient(options)` | `clientOptions` 必填;`protocol` 省略时仍为 TLV v1,提供 `pid` 和完整 `tlvEndpoint`。选择 FPNN 时显式设置 `protocol: 'fpnn'`,并提供 `endpoint` 或 `ssl_endpoint`(`host[:port]`,不含 URL scheme 和路径)。`workerUrl` 可选,同源 Worker 脚本 URL;普通浏览器脚本省略时 SDK 推导加载 SDK 的脚本同目录下的 `rtm.shared-worker.js`,Vite 项目应使用 `/vite` 入口自动打包 Worker。提供 `uid` 且省略 `workerName` 时,SDK 根据协议、`clientOptions.pid`、`uid`、实际 Gate endpoint 和 `workerNamespace` 生成稳定名称;若需要自行构造名称,可调用 `createSharedWorkerName({protocol, pid, uid, endpoint, namespace})`。若 `uid` 和 `workerName` 都省略,会使用通用默认名称;多账号应用应传其中一个,避免不同 UID 页面加入同一个 Worker。`readyTimeout` 默认 10000 毫秒;`idleShutdownTimeout` 默认 5000 毫秒,最后一个页面 detach 后等待这段时间再关闭共享连接,设为 `0` 表示立即关闭;同一 Worker 的所有页面必须使用相同值。`conversation` 可选,默认 `null` 接收全部会话 Push。 |
320
+ | `new RTMSharedWorkerClient(options)` | `clientOptions` 必填;`clientOptions.protocol` 省略时默认 FPNN,提供 `pid` 及 `endpoint` 或 `ssl_endpoint`(`host[:port]`,不含 URL scheme 和路径)。选择 TLV v1 时显式设置 `protocol: 'tlv-v1'`,并提供完整 `tlvEndpoint`。`workerUrl` 可选,同源 Worker 脚本 URL;普通浏览器脚本省略时 SDK 推导加载 SDK 的脚本同目录下的 `rtm.shared-worker.js`,现代 ESM 入口自动解析包内 Worker 资源。提供 `uid` 且省略 `workerName` 时,SDK 根据协议、`clientOptions.pid`、`uid`、实际 Gate endpoint 和 `workerNamespace` 生成稳定名称;若需要自行构造名称,可调用 `createSharedWorkerName({protocol, pid, uid, endpoint, namespace})`。若 `uid` 和 `workerName` 都省略,会使用通用默认名称;多账号应用应传其中一个,避免不同 UID 页面加入同一个 Worker。`readyTimeout` 默认 10000 毫秒;`idleShutdownTimeout` 默认 5000 毫秒,最后一个页面 detach 后等待这段时间再关闭共享连接,设为 `0` 表示立即关闭;同一 Worker 的所有页面必须使用相同值。`conversation` 可选,默认 `null` 接收全部会话 Push。 |
270
321
  | `whenReady()` | 等 Worker 首次初始化并返回 `{status, uid}` 初始快照;再次调用不会刷新快照,当前状态用 `getSharedSession()`。初始化失败时 Promise reject,SDK 会自动 detach 并关闭当前页面的端口。 |
271
322
  | `getSharedSession()` | 同步返回本页面最近观察到的 `{status, uid}`。 |
272
323
  | `loginIfNeeded(uid, credential?, timeout?)` | 同 UID 会话已登录则复用;登录中则加入该登录;会话空闲时须提供服务端签发的 credential。resolve `{accepted, errorCode, reused, uid}`。 |
273
- | `setConversation(conversation, callback?)` | 修改当前页面 Push 路由;传 `null` 接收全部会话。出错时通过可选 callback 返回。 |
324
+ | `setConversation(conversation, callback?)` | 修改当前页面监听器的本地 Push 筛选;Worker 始终全量分发事件,传 `null` 接收全部会话。出错时通过可选 callback 返回。 |
274
325
  | `destroy()` | detach 当前页面端口;Worker 仍有其他页面时不关闭 RTC 连接。它会完成端口与监听器清理后再传播待处理业务回调抛出的异常。 |
275
- | `shared.promises.*` / `shared.*` | 可调用所选协议的 `RTMClient` 业务 API,参数、callback、返回对象和 Push 事件均沿用该协议;两种协议都不支持 `sendFile` / `sendGroupFile` / `sendRoomFile`。`bye()` / `close()` 影响所有共享页面。 |
326
+ | `shared.promises.*` / `shared.*` | 可调用所选协议的 `RTMClient` 业务 API,参数、callback、返回对象和 Push 事件均沿用该协议;业务方法自动代理,能力与协议错误由底层 SDK 决定;FPNN 支持 `sendFile` / `sendGroupFile` / `sendRoomFile`,TLV 由协议契约拒绝。`bye()` / `close()` 影响所有共享页面。 |
276
327
 
277
- 普通浏览器脚本部署时,把 `dist/rtm.min.js` 与 `dist/rtm.shared-worker.js` 放在同源静态目录的同一目录,SDK 会自动定位 Worker 文件。Vite 项目从包的 `/vite` 入口导入;SDK 会将 Worker 作为构建资源输出并自动配置地址,无需手动设置 `workerUrl`。其他构建工具需保证 Worker 最终同源可访问,并在自动推导不适用时显式传入 `workerUrl`。以下示例展示页面接入、首次登录、后续页面复用、Push 监听和当前页 detach。与快速开始相同,替换项目参数和 credential 接口:
328
+ 普通浏览器脚本部署时,把 `dist/rtm.min.js` 与 `dist/rtm.shared-worker.js` 放在同源静态目录的同一目录,SDK 会自动定位 Worker 文件。现代 ESM 项目从包根导入;Vite 使用 `/vite-plugin`,Webpack 4 使用 `/webpack4` 插件,Webpack 5 使用标准 ESM 资源解析。以上常规方式均无需手动设置 `workerUrl`;自定义 Worker 部署位置时才传同源覆盖地址。以下示例展示页面接入、首次登录、后续页面复用、Push 监听和当前页 detach。与快速开始相同,替换项目参数和 credential 接口:
278
329
 
279
330
  ```js
280
331
  const rtm = window.rtm;
@@ -340,17 +391,17 @@ connectInbox().catch(console.error);
340
391
 
341
392
  - 首个页面在 UID 尚未登录时传入服务端签发的 credential;其他同 UID 页面在已登录时不需要 credential。若它们赶在首次登录完成前打开,`loginIfNeeded()` 会加入同一次登录。
342
393
  - `whenReady()` 返回首次挂接快照 `{status, uid}`,当前状态用 `getSharedSession()`;`loginIfNeeded(uid, credential?, timeout?)` 返回 `{accepted, errorCode, reused, uid}`。credential 不会广播到页面。
343
- - `conversation: {type: 'direct'|'group'|'room', id}` 只把匹配的私聊发送者、群或房间 Push 路由到该页面;`null` 接收全量会话 Push。运行中可调用 `setConversation(...)` 切换路由。
344
- - `event.broadcast` 和 `event.kicked` 发给全部页面;`event.room_removed` 发给订阅该房间的页面。页面自己的消息监听器由 SDK 端口分发。
394
+ - `conversation: {type: 'direct'|'group'|'room', id}` 在当前页面适配器中筛选私聊发送者、群或房间 Push;`null` 接收全部会话。Worker 始终向所有端口分发完整 SDK 事件,运行中可调用 `setConversation(...)` 修改本地筛选。
395
+ - 所有 SDK 事件由 Worker 原样分发到全部页面端口。页面适配器的可选 `conversation` 筛选会将 `event.room_removed` 限定为当前房间;`event.broadcast` 和 `event.kicked` 始终通知当前页面监听器。
345
396
  - `destroy()` 只 detach 当前页面;还有页面连接时共享连接继续运行。任一页面调用 `bye()` / `close()` 会结束所有页面共享的 RTC 会话。
346
397
  - 最后一个页面 detach 后,SDK 默认等待 5 秒再销毁 RTMClient 和连接;宽限期内新页面接入会取消回收。浏览器也可能在页面挂起或资源回收时结束 Worker,但 SDK 当前没有就绪后的心跳检测,浏览器静默回收不保证触发事件。
347
398
  - 收到 `SharedWorkerError` 时,表示 SDK 检测到当前页面到 Worker 的错误(例如初始化失败、Worker `error` 或消息端口错误),可丢弃旧 client 并用相同连接配置创建新 client。此事件不是 Worker 被浏览器回收的通用通知;如果浏览器静默结束 Worker,页面可能无法及时获知。新 client 的登录快照若为 `idle`,重新登录时必须取得服务端为该 UID 签发的 credential。SDK 不在页面、Worker 或存储中持久化 credential,也不会在 Worker 进程丢失后自动重登。
348
- - SharedWorker 仅共享实时连接和 Push,不同步页面草稿、未读 UI 或消息列表,也不持久化登录态。它不跨 origin、浏览器配置文件或 InPrivate 窗口共享;不支持时 SDK 不静默降级为每页一条连接。
349
- - `clientOptions` 必须可结构化克隆;不能包含 `requestMetadataProvider`、元数据函数或 `webSocketFactory`。SharedWorker 只接受静态 `requestMetadata` 对象。
399
+ - SharedWorker 仅共享实时连接和 Push,不同步页面草稿、未读 UI 或消息列表,也不持久化登录态。它不跨 origin、浏览器配置文件或 InPrivate 窗口共享;浏览器没有 SharedWorker API 时,`createClient()` 会改用每页一条独立连接,因此这些页面不能共享登录态。Worker 脚本加载或初始化失败仍会报告错误。
400
+ - 直接构造 `RTMSharedWorkerClient` 时,`clientOptions` 必须可安全传递给 Worker;函数、循环引用、访问器和自定义原型实例会抛出带配置路径的错误。通过 `createClient()` 时,这些配置会改用页面内 `RTMClient`,原因可通过 `getConnectionInfo()` 查询。
350
401
 
351
402
  ### FPNN 多窗口接入
352
403
 
353
- FPNN SharedWorker 的可用性以 npm `latest` 标签对应的 SDK 版本为准;若该标签版本尚未包含此扩展,请使用本地构建或 yalc。Node.js 仍只支持 TLV。
404
+ FPNN SharedWorker 已包含在 npm `latest` 中。Node.js 仍只支持 TLV。
354
405
 
355
406
  首次登录、后续窗口 `loginIfNeeded()`、`SharedSessionState`、路由和 detach 的使用方式与上面的 TLV 示例相同。FPNN 只改变连接配置和 Push 订阅;以下片段假定已加载 `rtm` 并取得 `pid`、`uid`、`peerUid`、FPNN Gate 地址及首次登录所需的 credential:
356
407
 
@@ -359,7 +410,7 @@ const shared = new rtm.RTMSharedWorkerClient({
359
410
  uid,
360
411
  conversation: { type: 'direct', id: peerUid },
361
412
  clientOptions: {
362
- protocol: 'fpnn', // 显式选择;省略时仍是 TLV。
413
+ protocol: 'fpnn', // 可省略;未指定协议时 RTMSharedWorkerClient 默认 FPNN。
363
414
  pid,
364
415
  ssl_endpoint: 'gate.example:13321', // wss;ws 使用 endpoint: 'gate.example:13321'
365
416
  autoReconnect: true,
@@ -380,7 +431,7 @@ await shared.promises.sendChat(peerUid, 'hello', '{}');
380
431
 
381
432
  FPNN 的 `endpoint` / `ssl_endpoint` 接收 `host[:port]`,SDK 补上 `ws://` / `wss://` 和 `/service/websocket`;它与 TLV 的完整 URL 配置不同。自动 Worker identity 包含协议,因此同 UID 的 FPNN / TLV 页面不会共享一条连接。若显式指定相同 `workerName` 却传入不同协议或配置,后加入页面初始化失败,不会覆盖已有会话。
382
433
 
383
- FPNN Push 保留 `SERVER_PUSH` 事件和 `from / gid / rid / mid / msg` 等字段;TLV 保留 `TLV_SERVER_PUSH` 事件及其字段。共享层只提取内部会话路由,不把 FPNN 业务数据包装成 TLV,也不执行额外的 ACK 或去重。FPNN 的聊天、命令、通用消息、文件接收事件均按会话过滤;广播和被踢下线事件发给所有页面。`sendFile` / `sendGroupFile` / `sendRoomFile` 在两种模式下都本地拒绝,文件接收和 FPNN `fileToken` 查询不在此限制内。传统参数与 Push 细节见 [协议迁移对照](PROTOCOL_MIGRATION.md) 和 [事件处理说明](EventProcess.md)。
434
+ FPNN Push 保留 `SERVER_PUSH` 事件和 `from / gid / rid / mid / msg` 等字段;TLV 保留 `TLV_SERVER_PUSH` 事件及其字段。Worker 原样分发所有 SDK 事件;ACK、去重、协议校验和业务请求都由底层 `RTMClient` 处理。页面适配器只在应用显式设置 `conversation` 时进行本地筛选。FPNN 的 `fileToken`、`sendFile`、`sendGroupFile`、`sendRoomFile` 都可通过共享调用使用,File 对象经结构化克隆交给 Worker,上传继续由 SDK 的文件代理连接完成。TLV 文件调用由底层协议契约返回 `200020`,共享层不维护业务 API 禁用名单。传统参数与 Push 细节见 [协议迁移对照](PROTOCOL_MIGRATION.md) 和 [事件处理说明](EventProcess.md)。
384
435
 
385
436
  ## 5. 参数与返回值约定
386
437
 
@@ -556,9 +607,9 @@ TLV 不支持的调用按实现分为三类:
556
607
 
557
608
  - TLV 合约中保留、但没有 Client API 路由的 wire(如 `filetoken`、`addfriends`、`acheck`)返回 `200020`(`RTM_EC_FORBIDDEN_METHOD`)。
558
609
  - 未登记且非保留的 wire 返回 `20004`(`RTM_EC_UNKNOWN_METHOD`)。
559
- - `RTMSharedWorkerClient` 的 `sendFile`、`sendGroupFile`、`sendRoomFile` 在本地拒绝;callback 收到 `{mid, error}`,其中 `error.code` 为 `200999`(`RTM_EC_UNKNOWN_ERROR`);Promise 版本 reject 同一个错误对象,不会发送 wire 请求。
610
+ - 共享客户端原样转发 SDK 请求及结果。TLV 文件发送由底层 `filetoken` 的契约校验拒绝;callback 收到 `{mid, error}`,其中 `error.code` 为 `200020`,Promise 版本 reject 同一对象。
560
611
 
561
- 这些错误都不会自动切换到 FPNN。SharedWorker 的 TLV 模式复用 TLV 支持范围;FPNN 模式可转发其兼容业务 API(文件发送除外)。两种模式都不接受函数型配置;`clientOptions` 必须可结构化克隆。FPNN 兼容能力列表见[能力总览](CAPABILITIES.md),服务端支持仍需单独确认。
612
+ 这些错误都不会自动切换到 FPNN。SharedWorker 的 TLV 模式复用 TLV 支持范围;FPNN 模式可转发其兼容业务 API,包括文件发送。通过 `createClient()` 使用函数型配置会自动选择页面内 `RTMClient`;直接构造 `RTMSharedWorkerClient` 时,`clientOptions` 必须可安全传递给 Worker。FPNN 兼容能力列表见[能力总览](CAPABILITIES.md),服务端支持仍需单独确认。
562
613
 
563
614
  ## 7. 调试与参考
564
615
 
package/docs/Users.md CHANGED
@@ -6,6 +6,8 @@
6
6
 
7
7
  ## Apis
8
8
 
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。
10
+
9
11
  * `getUserGroups(timeout, callback)`: 获取用户所在的Group
10
12
  * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
11
13
  * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
@@ -6,6 +6,8 @@
6
6
 
7
7
  ## Apis
8
8
 
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。审核接口中的 `strategyId` 必须占据其参数位置;只传 timeout 时先传 `undefined`,例如 `imageCheck(image, type, undefined, timeout, callback)`。
10
+
9
11
  * `translate(originalMessage, originalLanguage, targetLanguage, type, profanity, timeout, callback)`: 翻译消息
10
12
  * `originalMessage`: **(Required | stirng)** 待翻译的原始消息
11
13
  * `originalLanguage`: **(Optional | string)** 待翻译的消息的语言类型, 可为 `undefined`
@@ -17,8 +19,9 @@
17
19
  * `err`: **(Error)**
18
20
  * `data`: **(object[source:string, target:string, targetText:string, sourceText:string])**
19
21
 
20
- * `textCheck(text, timeout, callback)`: 文本审核
22
+ * `textCheck(text, strategyId, timeout, callback)`: 文本审核;兼容简写 `textCheck(text, timeout, callback)`。
21
23
  * `text`: **(Required | string)** 文本
24
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined`,旧式 timeout 简写不需要此参数
22
25
  * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
23
26
  * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
24
27
  * `err`: **(Error)**
@@ -28,9 +31,10 @@
28
31
  * `tags`: 触发的分类,比如涉黄涉政等等,具体见文本审核分类
29
32
  * `wlist`: 敏感词列表
30
33
 
31
- * `imageCheck(image, type, timeout, callback)`: 图片审核
34
+ * `imageCheck(image, type, strategyId, timeout, callback)`: 图片审核
32
35
  * `image`: **(Required | string)** 图片的url 或者内容
33
36
  * `type`: **(Required | number)** 1, url, 2, 内容
37
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined` 保留参数位置
34
38
  * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
35
39
  * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
36
40
  * `err`: **(Error)**
@@ -38,12 +42,13 @@
38
42
  * `result`: 0: 通过,2,不通过
39
43
  * `tags`: 触发的分类,比如涉黄涉政等等,具体见文本审核分类
40
44
 
41
- * `audioCheck(audio, type, lang, codec, srate, timeout, callback)`: 音频审核
45
+ * `audioCheck(audio, type, lang, codec, srate, strategyId, timeout, callback)`: 音频审核
42
46
  * `audio`: **(Required | string)** 音频的url 或者内容
43
47
  * `type`: **(Required | number)** 1, url, 2, 内容
44
48
  * `lang`: **(Required | string)** 音频语言
45
49
  * `codec`: **(Optional | string)** 音频b编码, 默认AMR_WB
46
50
  * `srate`: **(Optional | number)** 音频采样率, 16000
51
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined` 保留参数位置
47
52
  * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
48
53
  * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
49
54
  * `err`: **(Error)**
@@ -51,10 +56,11 @@
51
56
  * `result`: 0: 通过,2,不通过
52
57
  * `tags`: 触发的分类,比如涉黄涉政等等,具体见文本审核分类
53
58
 
54
- * `videoCheck(video, type, videoName, timeout, callback)`: 视频审核
59
+ * `videoCheck(video, type, videoName, strategyId, timeout, callback)`: 视频审核
55
60
  * `video`: **(Required | string)** 视频的url 或者内容
56
61
  * `type`: **(Required | number)** 1, url, 2, 内容
57
62
  * `videoName`: **(Required | string)** 音频文件名
63
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined` 保留参数位置
58
64
  * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
59
65
  * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
60
66
  * `err`: **(Error)**