@jhh96/light-app-bridge 1.0.6 → 1.1.0

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 {
@@ -72,12 +82,16 @@ export default class LightAppBridge {
     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 */

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 */
@@ -165,6 +179,7 @@ export default class LightAppBridge {
         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;
@@ -173,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) => {
@@ -183,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;
@@ -218,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);
@@ -316,12 +346,15 @@ export default class LightAppBridge {
         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、完成握手 */
@@ -347,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);
@@ -399,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 */
@@ -445,10 +484,12 @@ export default class LightAppBridge {
         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);
@@ -481,6 +522,7 @@ export default class LightAppBridge {
         if (this._destroyed)
             return;
         this._destroyed = true;
+        this._log('销毁实例: 未完成请求=' + this._pending.size);
         if (this._unlisten) {
             try {
                 this._unlisten();

package/package.json

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