feat: 完善context的注释

Author: CC11001100

src/analyzer/response-analyzer.js

@@ -1,9 +1,9 @@
 /**
- * 用于解析jsonp
+ * 用于解析jsonp响应
  */
 class ResponseAnalyzer {
 
-    // 2025-01-07 21:44:27 似乎并不需要这部分逻辑了，仅从请求参数进行推测就已经足够用了
+    // TODO 2025-01-07 21:44:27 似乎并不需要这部分逻辑了，仅从请求参数进行推测就已经足够用了
 
     /**
      *
@@ -14,10 +14,9 @@ class ResponseAnalyzer {
     parseScriptContext(scriptContext) {
 
         const responseFunctionNameSymbolSet = this.extractResponseFunctionNameSymbol(scriptContext.responseContext);
-        for (let param of scriptContext.requestContext.params) {
-            if (responseFunctionNameSymbolSet.has(param.value)) {
-                param.isJsonpCallback = true;
-            }
+        const jsonpCallbackFuncName = scriptContext.requestContext.getJsonpCallbackFuncName();
+        if (!responseFunctionNameSymbolSet.has(jsonpCallbackFuncName)) {
+            // TODO 2025-01-08 00:59:45 完犊子了，发现了异常情况
         }
 
         // TODO 2024-12-20 01:52:49
@@ -60,6 +59,6 @@ class ResponseAnalyzer {
 }
 
 module.exports = {
-    JsonpCallbackFunctionAnalyzer: ResponseAnalyzer
+    ResponseAnalyzer
 }
 

src/context/request/param.js

@@ -1,39 +1,41 @@
 const {repeat} = require("../../utils/string-util");
 
 /**
- * 表示url路径中的一个参数，对于script类型的请求来说，它只有query string类型的参数，因为它无法携带请求体
+ * 表示 URL 路径中的一个参数。对于 script 类型的请求来说，它只有 query string 类型的参数，因为它无法携带请求体。
  */
 class Param {
 
     /**
+     * 构造函数，创建一个 Param 实例。
      *
-     * @param name 参数的名字
-     * @param value 参数的值
-     * @param isJsonpCallback 此参数是否是jsonp的回调函数名称，有可能会识别不准
+     * @param {string} name - 参数的名字。
+     * @param {string} value - 参数的值。
+     * @param {boolean} [isJsonpCallback=false] - 此参数是否是 JSONP 的回调函数名称。注意：有可能会识别不准。
      */
     constructor(name, value, isJsonpCallback) {
 
         // 参数名和值
         this.name = name;
         this.value = value;
 
-        // 这个参数是否是jsonp的回调函数
+        // 这个参数是否是 JSONP 的回调函数
         this.isJsonpCallback = isJsonpCallback || false;
 
-        // 此参数是jsonp的callback参数的可能性有多大
+        // 此参数是 JSONP 的 callback 参数的可能性有多大（用于评分）
         this.jsonpCallbackScore = 0;
 
     }
 
     /**
-     * 把参数转为适合人类阅读的样式
+     * 将参数转换为适合人类阅读的格式。
      *
-     * @return {string}
+     * @param {number} indent - 缩进空格数，用于格式化输出。
+     * @return {string} - 返回格式化后的参数字符串。
      */
     toHumanReadable(indent) {
         const indentString = repeat(" ", indent);
         if (this.isJsonpCallback) {
-            return `${indentString}${this.name} = ${this.value}    <---- this param is jsonp callback function name`
+            return `${indentString}${this.name} = ${this.value}    <---- this param is jsonp callback function name`;
         } else {
             return `${indentString}${this.name} = ${this.value}`;
         }
@@ -43,4 +45,4 @@ class Param {
 
 module.exports = {
     Param
-}
+};

src/context/request/request-context.js

@@ -1,44 +1,42 @@
-const {Param} = require("./param");
 const {repeat} = require("../../utils/string-util");
 
 /**
- * 用于封装请求的上下文
+ * 用于封装请求的上下文，包含从 URL 中解析出的各种信息。
  */
 class RequestContext {
 
     /**
-     * 一个请求上下文是从一个script的src的url中解析出来的
+     * 构造函数，创建一个 RequestContext 实例。
      *
-     * @param rawUrl {String} 要请求的URL的地址，到锚点这一层的
-     * @param hostname {String}
-     * @param host {String}
-     * @param port {Number}
-     * @param path {String}
-     * @param params {Array<Param>}
-     * @param hash {String}
+     * @param {string} rawUrl - 原始的 URL 地址，包含锚点部分。
+     * @param {string} hostname - 主机名（例如：example.com）。
+     * @param {string} host - 主机（包含端口号，例如：example.com:8080）。
+     * @param {number} port - 端口号。
+     * @param {string} path - URL 路径部分（例如：/path/to/resource）。
+     * @param {Array<Param>} params - URL 中的查询参数列表。
+     * @param {string} hash - URL 中的锚点部分（例如：#section1）。
      */
     constructor(rawUrl, hostname, host, port, path, params, hash) {
         this.rawUrl = rawUrl;
         this.hostname = hostname;
         this.host = host;
         this.port = port;
         this.path = path;
-        // 避免为空
+        // 避免 params 为空，初始化为空数组
         this.params = params || [];
         this.hash = hash;
     }
 
     /**
-     * 从URL解析请求上下文
+     * 从 URL 解析请求上下文。
      *
-     * @param requestUrl {String} 要被解析的URL
-     * @return {RequestContext} 返回解析好的请求上下文
+     * @param {string} requestUrl - 要被解析的 URL。
+     * @return {RequestContext} - 返回解析好的请求上下文。
      */
     static parseRequestContext(requestUrl) {
-
         const url = new URL(requestUrl);
 
-        // 解析URL上的参数
+        // 解析 URL 上的参数
         const params = [];
         url.searchParams.forEach(function (value, key) {
             const param = new Param(key, value);
@@ -55,10 +53,10 @@ class RequestContext {
     }
 
     /**
-     * 根据参数名获取参数
+     * 根据参数名获取参数对象。
      *
-     * @param paramName
-     * @return {Param|null}
+     * @param {string} paramName - 要查找的参数名。
+     * @return {Param|null} - 返回找到的参数对象，如果未找到则返回 null。
      */
     getParam(paramName) {
         for (let param of this.params) {
@@ -70,10 +68,10 @@ class RequestContext {
     }
 
     /**
-     * 根据参数名获取参数值
+     * 根据参数名获取参数值。
      *
-     * @param paramName
-     * @return {*|null}
+     * @param {string} paramName - 要查找的参数名。
+     * @return {string|null} - 返回参数的值，如果未找到则返回 null。
      */
     getParamValueByName(paramName) {
         const param = this.getParam(paramName);
@@ -85,9 +83,9 @@ class RequestContext {
     }
 
     /**
-     * 此请求是否是JSONP类型的请求
+     * 判断此请求是否是 JSONP 类型的请求。
      *
-     * @return {boolean}
+     * @return {boolean} - 如果是 JSONP 请求则返回 true，否则返回 false。
      */
     isJsonpRequest() {
         if (!this.params) {
@@ -102,9 +100,9 @@ class RequestContext {
     }
 
     /**
-     * 获取JsonP类型的请求的回调函数的名字
+     * 获取 JSONP 请求的回调函数名称。
      *
-     * @return {String}
+     * @return {string|null} - 返回 JSONP 回调函数的名称，如果未找到则返回 null。
      */
     getJsonpCallbackFuncName() {
         if (!this.params) {
@@ -119,18 +117,21 @@ class RequestContext {
     }
 
     /**
+     * 判断此请求是否是 .js 后缀的请求。
      *
-     * @return {""|boolean}
+     * @return {boolean} - 如果路径以 .js 结尾则返回 true，否则返回 false。
      */
     isJsSuffixRequest() {
-        return this.path && this.path.toLowerCase().endsWith(".js")
+        return this.path && this.path.toLowerCase().endsWith(".js");
     }
 
     /**
-     * 转成方便阅读的格式
+     * 将请求上下文转换为方便人类阅读的格式。
+     *
+     * @param {number} indent - 缩进空格数，用于格式化输出。
+     * @return {string} - 返回格式化后的字符串。
      */
     toHumanReadable(indent) {
-
         const indentSpace = repeat(" ", indent);
 
         const msgs = [];
@@ -146,17 +147,14 @@ class RequestContext {
             msgs.push(param.toHumanReadable(indent + 4));
         }
 
-
         if (this.hash) {
-            msgs.push(`${indentSpace}hash: ${this.hash}`)
+            msgs.push(`${indentSpace}hash: ${this.hash}`);
         }
 
-        return msgs.join("\n\n");
+        return msgs.join("\n");
     }
-
 }
 
 module.exports = {
     RequestContext
-}
-
+};

src/context/response/response-context.js

@@ -1,31 +1,44 @@
 /**
- * 表示一个Script类型的请求的响应
+ * 表示一个 Script 类型请求的响应，包含响应的 JavaScript 代码或 JSONP 回调参数。
  */
 class ResponseContext {
 
     /**
+     * 构造函数，创建一个 ResponseContext 实例。
      *
-     * @param responseJsCode 脚本原始的响应代码是什么
-     * @param jsonpCallbackArguments 如果是jsonp类型的请求，捕捉到的响应是什么
+     * @param {string} responseJsCode - 脚本原始的响应代码。
+     * @param {Array|null} [jsonpCallbackArguments=null] - 如果是 JSONP 类型的请求，捕捉到的响应参数。
      */
-    constructor(responseJsCode, jsonpCallbackArguments) {
+    constructor(responseJsCode, jsonpCallbackArguments = null) {
         this.responseJsCode = responseJsCode;
         this.jsonpCallbackArguments = jsonpCallbackArguments;
     }
 
     /**
+     * 从 HTMLScriptElement 解析响应上下文。
      *
-     * @param script {HTMLScriptElement}
+     * @param {HTMLScriptElement} script - 包含响应代码的 script 元素。
+     * @return {ResponseContext} - 返回解析好的响应上下文。
      */
     static parseResponseContext(script) {
         const responseJsCode = script.text;
         return new ResponseContext(responseJsCode);
     }
 
+    /**
+     * 判断此响应是否是 JSONP 类型的响应。
+     *
+     * @return {boolean} - 如果是 JSONP 响应则返回 true，否则返回 false。
+     */
     isJsonpResponse() {
         return !!this.jsonpCallbackArguments;
     }
 
+    /**
+     * 将响应上下文转换为方便人类阅读的格式。
+     *
+     * @return {string} - 返回格式化后的字符串。
+     */
     toHumanReadable() {
         const msgs = [];
         if (this.isJsonpResponse()) {
@@ -42,4 +55,4 @@ class ResponseContext {
 
 module.exports = {
     ResponseContext
-}
+};

src/context/script/script-context.js

@@ -1,30 +1,29 @@
 /**
- * 一次Script请求的上下文封装
+ * 封装一次 Script 请求的上下文，包含请求和响应的相关信息。
  */
-const {RequestContext} = require("../request/request-context");
-const {ResponseContext} = require("../response/response-context");
 const {randomId} = require("../../utils/id-util");
 
 class ScriptContext {
 
     /**
-     * script级别的上下文
+     * 构造函数，创建一个 ScriptContext 实例。
      *
-     * @param url {String}
-     * @param requestContext {RequestContext}
-     * @param responseContext {ResponseContext}
+     * @param {string} url - 请求的 URL。
+     * @param {RequestContext} requestContext - 请求上下文，包含请求的详细信息。
+     * @param {ResponseContext} responseContext - 响应上下文，包含响应的详细信息。
      */
     constructor(url, requestContext, responseContext) {
+        // 生成唯一的请求 ID
         this.requestId = "js-script-hook-" + randomId();
         this.url = url;
         this.requestContext = requestContext;
         this.responseContext = responseContext;
     }
 
     /**
-     * 判断这个请求是否是jsonp请求
+     * 判断此请求是否是 JSONP 请求。
      *
-     * @returns {boolean}
+     * @returns {boolean} - 如果是 JSONP 请求则返回 true，否则返回 false。
      */
     isJsonp() {
         if (this.requestContext && this.requestContext.isJsonpRequest()) {
@@ -37,20 +36,20 @@ class ScriptContext {
     }
 
     /**
-     * 判断是否是请求的js文件
+     * 判断此请求是否是 .js 文件请求。
      *
-     * @return {""|boolean}
+     * @return {boolean} - 如果请求的路径以 .js 结尾则返回 true，否则返回 false。
      */
     isJsSuffixRequest() {
         return this.requestContext && this.requestContext.isJsSuffixRequest();
     }
 
     /**
+     * 将 Script 上下文转换为方便人类阅读的格式。
      *
-     * @return {string}
+     * @return {string} - 返回格式化后的字符串。
      */
     toHumanReadable() {
-
         const msgs = [];
 
         if (this.requestContext) {
@@ -61,8 +60,8 @@ class ScriptContext {
         msgs.push("\n\n");
 
         if (this.responseContext) {
-            msgs.push("Response Information: ")
-            msgs.push(this.responseContext.toHumanReadable(4));
+            msgs.push("Response Information: ");
+            msgs.push(this.responseContext.toHumanReadable());
         }
 
         return msgs.join("\n\n");
@@ -72,4 +71,4 @@ class ScriptContext {
 
 module.exports = {
     ScriptContext
-}
+};