feat: 添加安全日志输出，防止大响应体淹没控制台 (Issue #21)

leeguooooo · leeguooooo · commit bab9c9c9ccb2 · 2025-10-17T20:13:26.000+09:00
**核心功能**: - 新增 src/helpers/logger.js 提供 safeLogResponse 纯函数 - 响应体超过 10KB 时自动截断，保留头尾各 512 字符 - 显示大小提示和截断提示信息 **修改位置**: - background.js: 导入 helper，在响应日志和 debug_log 转发中使用 - index.js: 添加 fallback，在调试日志中使用 safeLogResponse - content-script.js: 在 helper 加载链中添加 logger.js - manifest.json: 添加 logger.js 到 web_accessible_resources **测试覆盖**: - 新增 3 个测试用例验证截断逻辑 - 71 个测试全部通过 - Lint: 0 errors **效果**: - 控制台不再被大响应体切割 - 仍能看到关键信息（头尾预览 + 大小提示） - 用户可通过提示了解如何获取完整内容 **已知限制**: - Network 面板问题未解决（Chrome 扩展架构限制） - 需要 chrome.debugger API 或自建请求历史 UI（后续优化） Addresses #21
diff --git a/.gitignore b/.gitignore
@@ -35,3 +35,4 @@ temp/
 *.crx
 key.pem
 extension.zip
+cross-request-store*.zip
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,13 @@
 
 ## [未发布]
 
-_当前没有未发布的变更_
+### 改进
+
+- **日志安全** - 控制台输出不会被大响应体淹没
+  - 新增 `src/helpers/logger.js` 提供 `safeLogResponse`
+  - background/index 使用安全日志助手，输出超过 10KB 时自动截断并提示
+  - 避免 content-script 控制台被巨型响应体切割，便于调试
+  - 新增单元测试覆盖截断逻辑，防止回归
 
 ## [4.5.0] - 2025-10-17
 
@@ -386,4 +392,3 @@ _当前没有未发布的变更_
 [4.2.0]: https://github.com/leeguooooo/cross-request-master/compare/v4.1.0...v4.2.0
 [4.1.0]: https://github.com/leeguooooo/cross-request-master/compare/v4.0.1...v4.1.0
 [4.0.1]: https://github.com/leeguooooo/cross-request-master/releases/tag/v4.0.1
-
diff --git a/background.js b/background.js
@@ -1,5 +1,60 @@
 'use strict';
 
+let safeLogResponse = null;
+
+try {
+  /* global importScripts */
+  importScripts('src/helpers/logger.js');
+  if (self.CrossRequestHelpers && self.CrossRequestHelpers.safeLogResponse) {
+    safeLogResponse = self.CrossRequestHelpers.safeLogResponse;
+  }
+} catch (helperError) {
+  console.warn('[Background] safeLogResponse helper 加载失败:', helperError);
+}
+
+if (!safeLogResponse) {
+  safeLogResponse = function (originalBody, options) {
+    const opts = options || {};
+    const maxBytes = typeof opts.maxBytes === 'number' ? opts.maxBytes : 10 * 1024;
+    const headChars = typeof opts.headChars === 'number' ? opts.headChars : 512;
+    const tailChars = typeof opts.tailChars === 'number' ? opts.tailChars : 512;
+
+    function toText(value) {
+      if (value == null) {
+        return '';
+      }
+      if (typeof value === 'string') {
+        return value;
+      }
+      try {
+        return JSON.stringify(value);
+      } catch (e) {
+        return String(value);
+      }
+    }
+
+    const text = toText(originalBody);
+    let byteLength;
+    if (typeof TextEncoder !== 'undefined') {
+      byteLength = new TextEncoder().encode(text).length;
+    } else {
+      byteLength = text.length * 2;
+    }
+
+    if (byteLength <= maxBytes) {
+      return originalBody;
+    }
+
+    return {
+      truncated: true,
+      size: byteLength + ' bytes',
+      head: text.slice(0, headChars),
+      tail: tailChars > 0 ? text.slice(-tailChars) : '',
+      hint: '响应体过大，已截断显示'
+    };
+  };
+}
+
 // 域名白名单管理
 let allowedDomains = new Set(['*']); // 默认允许所有域名，后续可以限制
 
@@ -184,13 +239,15 @@ async function handleCrossOriginRequest(request) {
     const responseBody = await response.text();
 
     // 添加调试日志
+    const safePreview = safeLogResponse(responseBody);
+
     console.log('[Background] 响应详情:', {
       url,
       status: response.status,
       statusText: response.statusText,
       contentType: responseHeaders['content-type'] || 'unknown',
       bodyLength: responseBody.length,
-      bodyPreview: responseBody.substring(0, 200)
+      bodyPreview: safePreview
     });
 
     // 同样发送到网页控制台
@@ -207,7 +264,7 @@ async function handleCrossOriginRequest(request) {
                 status: response.status,
                 contentType: responseHeaders['content-type'] || 'unknown',
                 bodyLength: responseBody.length,
-                bodyPreview: responseBody.substring(0, 200)
+                bodyPreview: safePreview
               }
             })
             .catch(() => {});
diff --git a/content-script.js b/content-script.js
@@ -111,7 +111,8 @@ const CrossRequest = {
     // 使用链式加载确保执行顺序，避免竞态条件
     const helpers = [
       'src/helpers/query-string.js',
-      'src/helpers/body-parser.js'
+      'src/helpers/body-parser.js',
+      'src/helpers/logger.js'
     ];
 
     // 链式加载 helpers，然后加载 index.js
diff --git a/index.js b/index.js
@@ -64,6 +64,51 @@
     };
   }
 
+  // Fallback: safeLogResponse
+  if (!helpers.safeLogResponse) {
+    console.warn('[Index] safeLogResponse helper 未加载，使用内联 fallback');
+    helpers.safeLogResponse = function (originalBody, options) {
+      const opts = options || {};
+      const maxBytes = typeof opts.maxBytes === 'number' ? opts.maxBytes : 10 * 1024;
+      const headChars = typeof opts.headChars === 'number' ? opts.headChars : 512;
+      const tailChars = typeof opts.tailChars === 'number' ? opts.tailChars : 512;
+
+      function toText(value) {
+        if (value == null) {
+          return '';
+        }
+        if (typeof value === 'string') {
+          return value;
+        }
+        try {
+          return JSON.stringify(value);
+        } catch (e) {
+          return String(value);
+        }
+      }
+
+      const text = toText(originalBody);
+      let byteLength;
+      if (typeof TextEncoder !== 'undefined') {
+        byteLength = new TextEncoder().encode(text).length;
+      } else {
+        byteLength = text.length * 2;
+      }
+
+      if (byteLength <= maxBytes) {
+        return originalBody;
+      }
+
+      return {
+        truncated: true,
+        size: byteLength + ' bytes',
+        head: text.slice(0, headChars),
+        tail: tailChars > 0 ? text.slice(-tailChars) : '',
+        hint: '响应体过大，已截断显示'
+      };
+    };
+  }
+
   // 创建跨域请求的 API
   const CrossRequestAPI = {
     // 请求计数器
@@ -164,7 +209,7 @@
             debugLog('[Index] response.body 已是对象，直接使用:', {
               type: typeof response.body,
               isArray: Array.isArray(response.body),
-              value: response.body
+              value: helpers.safeLogResponse(response.body)
             });
           } else if (typeof response.body === 'string') {
             // 是字符串，需要解析
@@ -189,7 +234,7 @@
             parsedData = response.body;
             debugLog('[Index] response.body 是标量值，直接使用:', {
               type: typeof response.body,
-              value: response.body
+              value: helpers.safeLogResponse(response.body)
             });
           }
         } else if (response.body === undefined || response.body === null) {
diff --git a/manifest.json b/manifest.json
@@ -37,6 +37,7 @@
       "resources": [
         "src/helpers/query-string.js",
         "src/helpers/body-parser.js",
+        "src/helpers/logger.js",
         "index.js"
       ],
       "matches": ["<all_urls>"]
diff --git a/src/helpers/logger.js b/src/helpers/logger.js
@@ -0,0 +1,101 @@
+/**
+ * Logger Helper
+ *
+ * 提供安全的日志输出函数，用于在控制台中显示大响应体时进行截断。
+ */
+
+(function (root) {
+  'use strict';
+
+  var DEFAULT_MAX_BYTES = 10 * 1024; // 10KB
+  var DEFAULT_HEAD_CHARS = 512;
+  var DEFAULT_TAIL_CHARS = 512;
+
+  function formatBytes(bytes) {
+    if (bytes < 1024) {
+      return bytes + ' B';
+    }
+    if (bytes < 1024 * 1024) {
+      return (bytes / 1024).toFixed(1) + ' KB';
+    }
+    if (bytes < 1024 * 1024 * 1024) {
+      return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+    }
+    return (bytes / (1024 * 1024 * 1024)).toFixed(1) + ' GB';
+  }
+
+  function toStringValue(value) {
+    if (value == null) {
+      return '';
+    }
+
+    if (typeof value === 'string') {
+      return value;
+    }
+
+    try {
+      return JSON.stringify(value);
+    } catch (e) {
+      try {
+        return String(value);
+      } catch (stringError) {
+        return '[无法序列化的响应体]';
+      }
+    }
+  }
+
+  function countBytes(text) {
+    if (typeof TextEncoder !== 'undefined') {
+      return new TextEncoder().encode(text).length;
+    }
+    // 退化处理：按字符长度估算
+    return text.length * 2;
+  }
+
+  /**
+   * 构造安全的日志输出
+   * @param {*} originalBody 原始响应体
+   * @param {Object} [options]
+   * @param {number} [options.maxBytes] 最大允许的字节数（默认 10KB）
+   * @param {number} [options.headChars] 截断时保留的头部字符数
+   * @param {number} [options.tailChars] 截断时保留的尾部字符数
+   * @returns {*} 原始响应体或截断后的摘要对象
+   */
+  function safeLogResponse(originalBody, options) {
+    var opts = options || {};
+    var maxBytes = typeof opts.maxBytes === 'number' ? opts.maxBytes : DEFAULT_MAX_BYTES;
+    var headChars = typeof opts.headChars === 'number' ? opts.headChars : DEFAULT_HEAD_CHARS;
+    var tailChars = typeof opts.tailChars === 'number' ? opts.tailChars : DEFAULT_TAIL_CHARS;
+
+    var textValue = toStringValue(originalBody);
+    var bytes = countBytes(textValue);
+
+    if (bytes <= maxBytes) {
+      return originalBody;
+    }
+
+    var previewHead = textValue.slice(0, headChars);
+    var previewTail = tailChars > 0 ? textValue.slice(-tailChars) : '';
+
+    return {
+      truncated: true,
+      size: formatBytes(bytes),
+      head: previewHead,
+      tail: previewTail,
+      hint: '响应体过大，已截断显示（查看 head/tail 字段获取片段）'
+    };
+  }
+
+  root.CrossRequestHelpers = root.CrossRequestHelpers || {};
+  root.CrossRequestHelpers.safeLogResponse = safeLogResponse;
+
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+      safeLogResponse: safeLogResponse,
+      __private: {
+        formatBytes: formatBytes,
+        toStringValue: toStringValue
+      }
+    };
+  }
+})(typeof window !== 'undefined' ? window : (typeof self !== 'undefined' ? self : globalThis));
diff --git a/tests/helpers.test.js b/tests/helpers.test.js
@@ -13,6 +13,7 @@
 // Import real helpers from production code
 const { bodyToString } = require('../src/helpers/body-parser.js');
 const { buildQueryString } = require('../src/helpers/query-string.js');
+const { safeLogResponse } = require('../src/helpers/logger.js');
 
 describe('bodyToString helper', () => {
 
@@ -464,3 +465,28 @@ describe('GET request parameter handling', () => {
     });
 });
 
+describe('safeLogResponse helper', () => {
+    test('should return original body when below threshold', () => {
+        const small = 'hello world';
+        const result = safeLogResponse(small, { maxBytes: 100 });
+        expect(result).toBe(small);
+    });
+
+    test('should truncate large string responses', () => {
+        const large = 'a'.repeat(20 * 1024); // 20KB
+        const result = safeLogResponse(large, { maxBytes: 10 * 1024, headChars: 100, tailChars: 50 });
+        expect(result).toHaveProperty('truncated', true);
+        expect(result).toHaveProperty('size');
+        expect(result.head.length).toBe(100);
+        expect(result.tail.length).toBe(50);
+    });
+
+    test('should stringify objects and truncate', () => {
+        const payload = { data: 'x'.repeat(15 * 1024) };
+        const result = safeLogResponse(payload, { maxBytes: 10 * 1024, headChars: 50, tailChars: 50 });
+        expect(result.truncated).toBe(true);
+        expect(typeof result.head).toBe('string');
+        expect(typeof result.tail).toBe('string');
+        expect(result.hint).toContain('截断');
+    });
+});
