feat: 完善debugger的注释

CC11001100 · CC11001100 · commit 0dea2aac5c95 · 2025-01-08T01:07:37.000+08:00
diff --git a/src/debugger/debugger-tester.js b/src/debugger/debugger-tester.js
@@ -1,38 +1,40 @@
+/**
+ * 用于测试是否命中断点的工具类，支持对请求和响应的断点测试。
+ */
 class DebuggerTester {
 
     /**
+     * 测试是否命中断点。
      *
-     * 测试是否命中断点
-     *
-     * @param globalConfig
-     * @param debuggerConfig
-     * @param scriptContext {ScriptContext}
-     * @return {boolean}
+     * @param {Object} globalConfig - 全局配置对象，包含断点的全局设置。
+     * @param {Object} debuggerConfig - 断点配置对象，包含断点的具体设置。
+     * @param {ScriptContext} scriptContext - 脚本上下文对象，包含请求和响应的详细信息。
+     * @return {boolean} - 如果命中断点则返回 true，否则返回 false。
      */
     test(globalConfig, debuggerConfig, scriptContext) {
 
-        // 首先URL要能够匹配得上
+        // 首先 URL 要能够匹配得上
         if (!this.testUrlPattern(debuggerConfig.urlPatternType, debuggerConfig.urlPattern, scriptContext.url)) {
             return false;
         }
 
-        // 支持忽略js文件请求
+        // 支持忽略 .js 文件请求
         if (globalConfig.isIgnoreJsSuffixRequest && scriptContext.isJsSuffixRequest()) {
             return false;
         }
 
-        // 忽略不是jsonp的请求
+        // 忽略不是 JSONP 的请求
         if (globalConfig.isIgnoreNotJsonpRequest && !scriptContext.isJsonp()) {
             return false;
         }
 
         // 请求断点
         if (debuggerConfig.enableRequestDebugger) {
             // 把一些相关的上下文赋值到变量方便断点命中这里的时候观察
-            // _scriptContext中存放的是与当前的script请求相关的一些上下文信息
+            // _scriptContext 中存放的是与当前的 script 请求相关的一些上下文信息
             const _scriptContext = scriptContext;
-            const humanReadableScriptInformation = scriptContext.toHumanReadable()
-            debugger;
+            const humanReadableScriptInformation = scriptContext.toHumanReadable();
+            debugger; // 断点调试
         }
 
         return true;
@@ -41,12 +43,12 @@ class DebuggerTester {
     // ---------------------------------------------------------------------------------------------------------------------
 
     /**
-     * 测试请求的URL是否匹配
+     * 测试请求的 URL 是否匹配断点的 URL 模式。
      *
-     * @param urlPatternType 界面上配置的匹配类型
-     * @param urlPattern 界面配置的匹配类型对应的值
-     * @param url {String} 要测试匹配的URL
-     * @return {boolean} 是否匹配得上
+     * @param {string} urlPatternType - URL 匹配模式类型（例如："equals-string"、"contains-string" 等）。
+     * @param {string | RegExp} urlPattern - URL 匹配模式的值。
+     * @param {string} url - 要测试匹配的 URL。
+     * @return {boolean} - 如果 URL 匹配模式则返回 true，否则返回 false。
      */
     testUrlPattern(urlPatternType, urlPattern, url) {
 
@@ -58,14 +60,6 @@ class DebuggerTester {
             return true;
         }
 
-        // if (typeof urlPattern === "string") {
-        //     return urlPattern.indexOf(url) !== -1;
-        // } else if (urlPattern instanceof RegExp) {
-        //     return urlPattern.test(url);
-        // } else {
-        //     return false;
-        // }
-
         switch (urlPatternType) {
             case "equals-string":
                 return this.testUrlPatternForEquals(urlPattern, url);
@@ -82,67 +76,77 @@ class DebuggerTester {
     }
 
     /**
-     * 完全匹配
+     * 测试 URL 是否完全匹配给定的模式。
      *
-     * @param urlPattern
-     * @param url
-     * @return {*}
+     * @param {string} urlPattern - 要匹配的 URL 模式。
+     * @param {string} url - 要测试的 URL。
+     * @return {boolean} - 如果 URL 完全匹配模式则返回 true，否则返回 false。
      */
     testUrlPatternForEquals(urlPattern, url) {
-        return url.equals(urlPattern);
+        return url === urlPattern;
     }
 
     /**
-     * 包含给定的关键字
+     * 测试 URL 是否包含给定的关键字。
      *
-     * @param urlPattern
-     * @param url
-     * @return {boolean}
+     * @param {string} urlPattern - 要匹配的关键字。
+     * @param {string} url - 要测试的 URL。
+     * @return {boolean} - 如果 URL 包含关键字则返回 true，否则返回 false。
      */
     testUrlPatternForContains(urlPattern, url) {
         return url.indexOf(urlPattern) !== -1;
     }
 
     /**
-     * 正则表达式方式匹配
+     * 测试 URL 是否匹配给定的正则表达式。
      *
-     * @param urlPattern
-     * @param url
-     * @return {boolean}
+     * @param {string} urlPattern - 要匹配的正则表达式。
+     * @param {string} url - 要测试的 URL。
+     * @return {boolean} - 如果 URL 匹配正则表达式则返回 true，否则返回 false。
      */
     testUrlPatternForMatchRegexp(urlPattern, url) {
         try {
             return new RegExp(urlPattern).test(url);
         } catch (e) {
             console.error(e);
+            return false;
         }
     }
 
     /**
-     * 直接匹配所有
-     * @param urlPattern
-     * @param url
-     * @return {boolean}
+     * 匹配所有 URL（始终返回 true）。
+     *
+     * @param {string} urlPattern - 忽略此参数。
+     * @param {string} url - 忽略此参数。
+     * @return {boolean} - 始终返回 true。
      */
     testUrlPatternForMatchAll(urlPattern, url) {
         return true;
     }
 
     // ---------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * 测试响应是否命中断点。
+     *
+     * @param {Object} globalConfig - 全局配置对象，包含断点的全局设置。
+     * @param {Object} debuggerConfig - 断点配置对象，包含断点的具体设置。
+     * @param {ScriptContext} scriptContext - 脚本上下文对象，包含请求和响应的详细信息。
+     * @return {boolean} - 如果命中断点则返回 true，否则返回 false。
+     */
     testForResponse(globalConfig, debuggerConfig, scriptContext) {
 
-        // 首先URL要能够匹配得上
+        // 首先 URL 要能够匹配得上
         if (!this.testUrlPattern(debuggerConfig.urlPatternType, debuggerConfig.urlPattern, scriptContext.url)) {
             return false;
         }
 
-        // 支持忽略js文件请求
+        // 支持忽略 .js 文件请求
         if (globalConfig.isIgnoreJsSuffixRequest && scriptContext.isJsSuffixRequest()) {
             return false;
         }
 
-        // 忽略不是jsonp的请求
+        // 忽略不是 JSONP 的请求
         if (globalConfig.isIgnoreNotJsonpRequest && !scriptContext.isJsonp()) {
             return false;
         }
@@ -152,20 +156,20 @@ class DebuggerTester {
     }
 
     /**
-     * 判断是否需要打印到控制台上
+     * 判断是否需要将信息打印到控制台。
      *
-     * @param globalConfig
-     * @param scriptContext
-     * @return {boolean}
+     * @param {Object} globalConfig - 全局配置对象，包含断点的全局设置。
+     * @param {ScriptContext} scriptContext - 脚本上下文对象，包含请求和响应的详细信息。
+     * @return {boolean} - 如果需要打印到控制台则返回 true，否则返回 false。
      */
     isNeedPrintToConsole(globalConfig, scriptContext) {
 
-        // 忽略js文件请求
+        // 忽略 .js 文件请求
         if (globalConfig.isIgnoreJsSuffixRequest && scriptContext.isJsSuffixRequest()) {
             return false;
         }
 
-        // 忽略不是jsonp的请求
+        // 忽略不是 JSONP 的请求
         if (globalConfig.isIgnoreNotJsonpRequest && !scriptContext.isJsonp()) {
             return false;
         }
@@ -177,5 +181,4 @@ class DebuggerTester {
 
 module.exports = {
     DebuggerTester
-}
-
+};
diff --git a/src/debugger/debugger.js b/src/debugger/debugger.js
@@ -1,27 +1,30 @@
 /**
- * 表示一个jsonp的条件断点
+ * 表示一个 JSONP 的条件断点，用于在请求或响应处理时中断执行。
  */
 class Debugger {
 
     /**
-     * 创建一个断点
+     * 构造函数，创建一个 Debugger 实例。
      *
-     * @param id {string} 断点的唯一标识
-     * @param enable {Boolean} 此断点是否处于启用状态
-     * @param urlPatternType {String}
-     * @param urlPattern {String | RegExp} 用于与script类型的请求的URL做匹配进入断点，只有这一个是必须指定的
-     * @param enableRequestDebugger {Boolean | null} 是否开启请求断点，开启请求断点会在请求发送之前进入断点，不指定的话默认开启
-     * @param enableResponseDebugger {Boolean | null} 是否开启响应断点，开启响应断点会在响应处理之前进入断点，不指定的话默认开启
-     * @param callbackFunctionParamName {String | null} 传递jsonp回调函数名字的参数，比如 "callback"，如果不指定的话会自动推测
-     * @param comment
+     * @param {string} id - 断点的唯一标识。
+     * @param {boolean} enable - 此断点是否处于启用状态。
+     * @param {string} urlPatternType - URL 匹配模式类型（例如：字符串或正则表达式）。
+     * @param {string | RegExp} urlPattern - 用于与 script 类型请求的 URL 做匹配，只有这个是必须指定的。
+     * @param {boolean} [enableRequestDebugger=true] - 是否开启请求断点。开启后会在请求发送之前进入断点。如果不指定，默认开启。
+     * @param {boolean} [enableResponseDebugger=true] - 是否开启响应断点。开启后会在响应处理之前进入断点。如果不指定，默认开启。
+     * @param {string | null} [callbackFunctionParamName=null] - 传递 JSONP 回调函数名称的参数（例如："callback"）。如果不指定，会自动推测。
+     * @param {string | null} [comment=null] - 断点的注释或描述信息。
      */
-    constructor(id, enable,
-                urlPatternType,
-                urlPattern,
-                enableRequestDebugger = true,
-                enableResponseDebugger = true,
-                callbackFunctionParamName,
-                comment) {
+    constructor(
+        id,
+        enable,
+        urlPatternType,
+        urlPattern,
+        enableRequestDebugger = true,
+        enableResponseDebugger = true,
+        callbackFunctionParamName = null,
+        comment = null
+    ) {
         this.id = id;
         this.enable = enable;
         this.urlPatternType = urlPatternType;
@@ -36,4 +39,4 @@ class Debugger {
 
 module.exports = {
     Debugger
-}
+};
