@jhh96/light-app-bridge 1.0.5 → 1.1.0

package/README.md

@@ -15,16 +15,15 @@
 | `window.worklink`（含 `invokeModuleMethodSync`） | 发送消息 / 取 webContentsId | preload 注入 |
 | `window.worklink.plugin.getContentContext` | 解析目标轻应用 webContentsId（**仅 plugin 角色**） | pluginLightAppPreload 注入 |
 
-**收消息（二选一，自动选择，不强依赖 waltz）：**
+**收消息（自动选择，不强依赖 waltz）：**
 
 | 监听后端 | 优先级 | 适用环境 | 说明 |
 |---------|--------|---------|------|
 | `window.waltz.event.on('native-call-js')` | 高（优先） | 有 waltz 注入的环境 | 推荐路径，立即可用 |
-| `window.handleMessageFromNative` | 低（回退） | 无 waltz 的环境 | hook 此全局方法（waltzBridge 投递消息的统一入口）。**可能晚于构造注入**，SDK 会轮询等待（上限 10s） |
+| `window.handleMessageFromNative` | 低（回退） | 无 waltz 的环境 | 由 SDK 定义此全局方法（该方法原本由 waltz.min.js 注册；无 waltz 时为 undefined，renderer 投递消息前会检查其类型，没人定义则消息被丢弃）。renderer 收到消息后主动调用它传入消息。若该方法已存在则包装透传，不破坏原逻辑 |
 
-- 两者都始终不可用时，`connect()`/`ready()` reject（构造不抛，因监听后端允许稍后出现）
 - SDK 内部按 waltz → handleMessageFromNative 顺序探测，无需手动指定
-- 握手会等监听就绪后才开始，避免早到的 ack/hello 丢失
+- 握手会等监听绑定后才开始，避免早到的 ack/hello 丢失
 
 ## 安装（两个项目）
 
@@ -59,14 +58,21 @@ bridge.onMessage((data, id) => {
 
 ```js
 {
-  __sdk: 'lightAppBridge',   // 标识：在 plugin-message 流中过滤出本 SDK 的消息
-  id: 'r_xxx',               // 关联 id：send 生成，回复原样带回
-  type: 'req' | 'res',       // 请求 / 响应
-  data: any                  // 任意业务数据
+  __sdk: 'LightAppBridge',    // SDK 标识：过滤出本 SDK 的消息，隔离其它消息
+  v: 1,                       // 协议版本号
+  id: 'r_xxx',                // 关联 id：send 生成，回复原样带回
+  type: 'hello'|'ack'|'req'|'res',  // 握手 hello/ack；业务 req/res
+  data: any                   // 任意业务数据
 }
 ```
 
+## 连接与生命周期
+
+- 构造即自动握手（插件发 hello 每秒重试；轻应用持续等待、不超时）
+- 握手失败后**再次 `connect()` 可重连**（自动重置状态，无需重建实例）
+- `destroy()` 销毁实例：解绑监听、拒绝未完成请求；销毁后 `send`/`connect` 立即 reject
+
 ## 文件
 
-- `src/lightAppBridge.js` —— SDK 源码（ESM，可直接 import）
-- `src/index.js` —— barrel re-export
+- `src/lightAppBridge.ts` —— SDK 源码（TypeScript，构建产物为 ESM）
+- `src/index.ts` —— barrel re-export

package/dist/lightAppBridge.d.ts

@@ -39,6 +39,16 @@ export interface BridgeOptions {
     timeout?: number;
     /** 握手超时(ms)，默认 30000。仅 plugin 角色生效；lightapp 端持续等待，不超时 */
     handshakeTimeout?: number;
+    /**
+     * 调试模式：开启后在控制台打印完整通信轨迹，便于排查 plugin ↔ lightapp
+     * 联调问题。覆盖：
+     *   - 构造（角色/配置）、握手（hello/ack/连接建立/超时/重连）
+     *   - 发送请求（send data + id）、底层投递（目标 webContentsId + 信封）
+     *   - 收到消息（type/id/from/data）、响应返回（res 数据/超时）
+     *   - handler 异常、销毁
+     * 大 payload 截断到 500 字符防刷屏。
+     */
+    debug?: boolean;
 }
 /** send 单次调用选项 */
 export interface SendOptions {
@@ -70,12 +80,18 @@ export default class LightAppBridge {
     private _connectPromise;
     private _unlisten;
     private _listenerReady;
+    private _connectFailed;
+    private _destroyed;
+    private _debug;
+    private _helloCount;
     /**
      * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
      * @param options 超时配置
      * @throws 依赖未就绪时抛出（window.worklink；监听后端可稍后出现，不算构造失败）
      */
     constructor(role?: BridgeRole, options?: BridgeOptions);
+    /** debug 日志（options.debug 开启时打印，前缀带角色便于双端对照） */
+    private _log;
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     private _checkDeps;
     /** 绑定消息监听：优先 waltz；无 waltz 时定义/包装 window.handleMessageFromNative */
@@ -85,13 +101,21 @@ export default class LightAppBridge {
     /** 处理一条归一化后的消息 */
     private _onMessage;
     /**
-     * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
+     * 建立连接（握手）。构造时已自动调用，通常无需手动调。
+     *   - 已连接 / 握手进行中：幂等，返回同一个 Promise
+     *   - 上次握手失败：重新发起（内部自动重置状态，无需重建实例——
+     *     典型场景：插件先启动、轻应用窗口尚未打开导致超时，对端就绪后再次 connect 即可）
+     *   - 实例已销毁：reject
+     * 行为：
      *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack 或超时）
-     *   - 轻应用：被动等待 hello（持续监听，不超时——插件可能任意晚才发起连接）
-     * 多次调用幂等，返回同一个连接 Promise。
+     *   - 轻应用：被动等待 hello（持续监听，不超时）
      * @returns 对端 webContentsId
      */
     connect(): Promise<number | null>;
+    /** 重置连接状态（用于首次握手或失败后重连） */
+    private _resetConnectState;
+    /** 连接失败：标记失败并 reject（再次 connect 可重试） */
+    private _failConnect;
     /** 发送 hello（携带自身 webContentsId） */
     private _sendHello;
     /** 收到 hello（轻应用侧）：记录对端、回 ack、完成握手 */
@@ -132,7 +156,7 @@ export default class LightAppBridge {
      * @returns 调用以取消监听
      */
     onMessage(handler: MessageHandler): () => void;
-    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试 */
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试。销毁后实例不可再用 */
     destroy(): void;
 }
 /**

package/dist/lightAppBridge.js

@@ -26,7 +26,21 @@ const PROTOCOL_VERSION = 1; // 协议版本号
 const DEFAULT_TIMEOUT = 3000; // send 默认超时(ms)
 const DEFAULT_HANDSHAKE_TIMEOUT = 30000; // 握手超时(ms)
 const HELLO_RETRY_INTERVAL = 1000; // 插件 hello 重试间隔(ms)
+const DEBUG_PAYLOAD_LIMIT = 500; // debug 日志 payload 截断长度
 const genId = () => 'r_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 7);
+/** debug 日志用：安全序列化 payload，超长截断 */
+function debugPayload(data) {
+    let s;
+    try {
+        s = typeof data === 'string' ? data : JSON.stringify(data);
+    }
+    catch {
+        s = String(data);
+    }
+    if (s === undefined)
+        s = 'undefined';
+    return s.length > DEBUG_PAYLOAD_LIMIT ? s.slice(0, DEBUG_PAYLOAD_LIMIT) + `…(截断,共${s.length}字符)` : s;
+}
 /** 判断是否为本 SDK 的消息（按 __sdk 标识过滤） */
 const isBridgeMsg = (msg) => !!(msg && typeof msg === 'object' && msg.__sdk === SDK_ID);
 /** 创建一个可外部 resolve 的 Promise */
@@ -163,6 +177,9 @@ export default class LightAppBridge {
         this._started = false;
         this._unlisten = null;
         this._listenerReady = null;
+        this._connectFailed = false;
+        this._destroyed = false;
+        this._helloCount = 0;
         let r = role === 'plugin' || role === 'lightapp' ? role : 'lightapp';
         if (role !== 'plugin' && role !== 'lightapp') {
             const wl = window.worklink;
@@ -171,6 +188,11 @@ export default class LightAppBridge {
         this.role = r;
         this.timeout = options.timeout != null ? options.timeout : DEFAULT_TIMEOUT;
         this.handshakeTimeout = options.handshakeTimeout != null ? options.handshakeTimeout : DEFAULT_HANDSHAKE_TIMEOUT;
+        this._debug = !!options.debug;
+        this._log('构造: role=' + r + ', timeout=' + this.timeout +
+            ', handshakeTimeout=' + this.handshakeTimeout +
+            ', 监听后端=' + (hasWaltz() ? 'waltz' : 'handleMessageFromNative') +
+            ', 自身id=' + this.getId());
         // 连接 deferred：构造时即建立，保证轻应用收到 hello 也能 resolve（无需显式 connect）
         this._connectDeferred = deferred();
         this._connectPromise = this._connectDeferred.promise.then((peerId) => {
@@ -181,6 +203,12 @@ export default class LightAppBridge {
         this._startListener(); // 绑定消息监听（waltz 或定义 handleMessageFromNative）
         this.connect(); // 构造即自动发起握手（内部会等监听就绪）
     }
+    /** debug 日志（options.debug 开启时打印，前缀带角色便于双端对照） */
+    _log(...args) {
+        if (!this._debug)
+            return;
+        console.log(`[LightAppBridge:${this.role}]`, ...args);
+    }
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     _checkDeps() {
         const w = window;
@@ -204,7 +232,7 @@ export default class LightAppBridge {
         })
             .catch((e) => {
             // 理论上不会发生（无 waltz 时必走定义路径），保险起见让连接失败并给出原因
-            this._connectDeferred.reject(new Error('LightAppBridge 监听后端绑定失败 (' +
+            this._failConnect(new Error('LightAppBridge 监听后端绑定失败 (' +
                 (e && e.message ? e.message : String(e)) + ')'));
         });
     }
@@ -216,8 +244,12 @@ export default class LightAppBridge {
     _onMessage(msg) {
         const envelope = msg.envelope;
         const fromId = msg.fromWebContentsId;
-        if (!isBridgeMsg(envelope))
+        if (!isBridgeMsg(envelope)) {
+            this._log('recv← 忽略非本SDK消息: from=' + fromId);
             return;
+        }
+        this._log('recv← type=' + envelope.type + ' id=' + envelope.id +
+            ' from=' + fromId + ' data=' + debugPayload(envelope.data));
         switch (envelope.type) {
             case 'hello':
                 this._onHello(fromId);
@@ -236,16 +268,27 @@ export default class LightAppBridge {
     }
     // —— 连接 / 握手 —— //
     /**
-     * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
+     * 建立连接（握手）。构造时已自动调用，通常无需手动调。
+     *   - 已连接 / 握手进行中：幂等，返回同一个 Promise
+     *   - 上次握手失败：重新发起（内部自动重置状态，无需重建实例——
+     *     典型场景：插件先启动、轻应用窗口尚未打开导致超时，对端就绪后再次 connect 即可）
+     *   - 实例已销毁：reject
+     * 行为：
      *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack 或超时）
-     *   - 轻应用：被动等待 hello（持续监听，不超时——插件可能任意晚才发起连接）
-     * 多次调用幂等，返回同一个连接 Promise。
+     *   - 轻应用：被动等待 hello（持续监听，不超时）
      * @returns 对端 webContentsId
      */
     connect() {
         var _a;
-        if (this._connectStarted)
+        if (this._destroyed) {
+            return Promise.reject(new Error('实例已销毁，请重建实例'));
+        }
+        if (this._connected)
             return this._connectPromise;
+        if (this._connectStarted && !this._connectFailed)
+            return this._connectPromise;
+        // 首次调用，或上次握手失败：重置连接状态重新发起
+        this._resetConnectState();
         this._connectStarted = true;
         // 等监听后端绑定完成后再握手，避免对端的 ack/hello 在监听绑定前到达而丢失
         const listenerReady = (_a = this._listenerReady) !== null && _a !== void 0 ? _a : Promise.resolve();
@@ -254,7 +297,7 @@ export default class LightAppBridge {
         if (this.role === 'plugin') {
             this._handshakeTimer = setTimeout(() => {
                 if (!this._connected) {
-                    this._connectDeferred.reject(new Error(`握手超时 (${this.handshakeTimeout}ms)，对端未响应`));
+                    this._failConnect(new Error(`握手超时 (${this.handshakeTimeout}ms)，对端未响应`));
                     this._clearHelloTimer();
                 }
             }, this.handshakeTimeout);
@@ -280,27 +323,54 @@ export default class LightAppBridge {
             }
             // lightapp 被动等待 hello（listener 已绑定），收到后在 _onHello 中回 ack 并 resolve
         })
-            .catch((e) => this._connectDeferred.reject(e));
+            .catch((e) => this._failConnect(e));
         return this._connectPromise;
     }
+    /** 重置连接状态（用于首次握手或失败后重连） */
+    _resetConnectState() {
+        this._connectDeferred = deferred();
+        this._connectPromise = this._connectDeferred.promise.then((peerId) => {
+            this._onConnected(peerId);
+            return peerId;
+        });
+        this._connectFailed = false;
+        this._connectStarted = false;
+        this._clearHelloTimer();
+        if (this._handshakeTimer) {
+            clearTimeout(this._handshakeTimer);
+            this._handshakeTimer = null;
+        }
+    }
+    /** 连接失败：标记失败并 reject（再次 connect 可重试） */
+    _failConnect(e) {
+        if (this._destroyed)
+            return;
+        this._connectFailed = true;
+        this._log('✗ 握手失败: ' + (e && e.message ? e.message : String(e)));
+        this._connectDeferred.reject(e instanceof Error ? e : new Error(String(e)));
+    }
     /** 发送 hello（携带自身 webContentsId） */
     _sendHello() {
         if (this._target == null)
             return;
+        this._helloCount++;
+        this._log('hello→ 目标=' + this._target + (this._helloCount > 1 ? ' (重试#' + this._helloCount + ')' : ''));
         this._send(this._target, this._envelope('hello', { from: this.getId() }));
     }
     /** 收到 hello（轻应用侧）：记录对端、回 ack、完成握手 */
     _onHello(fromId) {
-        if (fromId != null)
-            this._recordPeer(fromId);
+        if (fromId == null)
+            return; // 无法定位对端则忽略（真实环境该字段恒有值），握手不完成
+        this._recordPeer(fromId);
         // 回 ack，携带自身 webContentsId
-        if (fromId != null)
-            this._send(fromId, this._envelope('ack', { from: this.getId() }));
+        this._send(fromId, this._envelope('ack', { from: this.getId() }));
         // 握手完成（resolve 幂等，重复 hello 只回 ack）
         this._connectDeferred.resolve(fromId);
     }
     /** 收到 ack（插件侧）：确认连接 */
     _onAck(fromId) {
+        if (fromId == null)
+            return; // 无法定位对端则忽略
         this._recordPeer(fromId);
         this._connectDeferred.resolve(fromId);
     }
@@ -310,6 +380,7 @@ export default class LightAppBridge {
     }
     _onConnected(peerId) {
         this._connected = true;
+        this._log('✓ 连接建立: 对端=' + peerId + (this._helloCount > 1 ? ' (hello共' + this._helloCount + '次)' : ''));
         this._clearHelloTimer();
         if (this._handshakeTimer) {
             clearTimeout(this._handshakeTimer);
@@ -362,19 +433,24 @@ export default class LightAppBridge {
         Promise.allSettled(results).then((settled) => {
             for (const s of settled) {
                 if (s.status === 'fulfilled' && s.value !== undefined) {
+                    this._log('res→ id=' + id + ' data=' + debugPayload(s.value));
                     this._send(this._peer, this._envelope('res', s.value, id));
                     return;
                 }
             }
+            this._log('✗ req 无可回复值(回调全空/异常): id=' + id);
         });
     }
     /** 收到 res：按 id 唤醒等待中的 send */
     _serveRes(envelope) {
         const p = this._pending.get(envelope.id);
-        if (!p)
+        if (!p) {
+            this._log('recv← res 无等待者(可能已超时): id=' + envelope.id);
             return;
+        }
         clearTimeout(p.timer);
         this._pending.delete(envelope.id);
+        this._log('✓ 收到响应 id=' + envelope.id + ' data=' + debugPayload(envelope.data));
         p.resolve(envelope.data);
     }
     /** 底层发送：把信封投递到指定 webContentsId */
@@ -402,14 +478,18 @@ export default class LightAppBridge {
      * @returns 对端回调返回的数据
      */
     send(data, options = {}) {
+        if (this._destroyed)
+            return Promise.reject(new Error('实例已销毁'));
         const timeout = options.timeout != null ? options.timeout : this.timeout;
         return this.ready().then((targetId) => {
             const id = genId();
             const envelope = this._envelope('req', data, id);
+            this._log('send→ id=' + id + ' 目标=' + targetId + ' data=' + debugPayload(data));
             return new Promise((resolve, reject) => {
                 const timer = setTimeout(() => {
                     if (this._pending.has(id)) {
                         this._pending.delete(id);
+                        this._log('✗ 超时 id=' + id + ' (' + timeout + 'ms 无响应)');
                         reject(new Error(`请求超时 (${timeout}ms)`));
                     }
                 }, timeout);
@@ -437,8 +517,12 @@ export default class LightAppBridge {
                 this._messageHandlers.splice(i, 1);
         };
     }
-    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试 */
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试。销毁后实例不可再用 */
     destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        this._log('销毁实例: 未完成请求=' + this._pending.size);
         if (this._unlisten) {
             try {
                 this._unlisten();
@@ -451,6 +535,8 @@ export default class LightAppBridge {
             clearTimeout(this._handshakeTimer);
             this._handshakeTimer = null;
         }
+        // 进行中的握手直接失败（已 resolve 的话 reject 是 no-op）
+        this._connectDeferred.reject(new Error('实例已销毁'));
         // 拒绝所有未完成的请求
         this._pending.forEach((p) => {
             clearTimeout(p.timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhh96/light-app-bridge",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "type": "module",
   "description": "招商随行（WorkLink）插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK",
   "main": "./dist/index.js",