Files

曾文豪 523cc777f8 docs(readme): 重构README并补充详细文档内容

2026-04-29 11:20:18 +08:00

19 KiB

Raw Permalink Blame History

调试工具和方法

**本文档中引用的文件** - [README.md](file://README.md) - [package.json](file://package.json) - [index.js](file://index.js) - [TsCommon.js](file://src/utils/TsCommon.js) - [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js) - [TsStorage.js](file://src/utils/TsStorage.js) - [TsCrypto.js](file://src/utils/TsCrypto.js) - [TsSM4.js](file://src/utils/TsSM4.js) - [TsHttpUtil.js](file://src/https/TsHttpUtil.js)

简介

本指南专注于如何有效使用各种调试工具和技术来诊断和解决基于 Node.js 的 npm 工具包问题。该工具包提供了通用方法、网络请求、存储管理、加密解密等功能模块，涵盖了现代 Web 应用开发中的常见调试场景。

项目结构

该项目采用模块化设计，主要包含以下核心模块：

graph TB
subgraph "主入口"
Index[index.js]
end
subgraph "工具模块"
Common[TsCommon.js<br/>通用工具函数]
Crypto[TsCrypto.js<br/>加密解密]
Storage[TsStorage.js<br/>数据存储]
Config[TsGlobalConfig.js<br/>全局配置]
SM4[TsSM4.js<br/>SM4算法实现]
end
subgraph "HTTP模块"
HttpUtil[TsHttpUtil.js<br/>网络请求封装]
end
subgraph "依赖"
UmiRequest[umi-request<br/>HTTP客户端]
Base64[base64-js<br/>Base64编码]
end
Index --> Common
Index --> Crypto
Index --> Storage
Index --> Config
Index --> SM4
Index --> HttpUtil
HttpUtil --> Storage
HttpUtil --> Crypto
HttpUtil --> Config
HttpUtil --> Common
Crypto --> SM4
Crypto --> Config
Crypto --> Base64
HttpUtil --> UmiRequest

图表来源

章节来源

核心组件

通用工具模块 (TsCommon.js)

提供基础的 JavaScript 工具函数，包括：

URL 参数解析
数据类型检查
JSON 解析安全处理
字符串操作
环境检测

网络请求模块 (TsHttpUtil.js)

基于 umi-request 封装的 HTTP 客户端，支持：

自动错误处理
请求参数预处理
数据加密传输
响应数据解密
Token 自动注入

存储模块 (TsStorage.js)

本地存储管理，支持：

对象序列化存储
用户 Token 管理
加密开关控制
类型安全的数据获取

加密模块 (TsCrypto.js)

基于 SM4 算法的加密解密工具，包含：

SM4 算法实现
Base64 编码支持
动态密钥处理
加密模式配置

章节来源

架构概览

sequenceDiagram
participant Client as 客户端应用
participant HttpUtil as HTTP工具
participant Crypto as 加密模块
participant Storage as 存储模块
participant Server as 服务器
Client->>HttpUtil : 发起请求
HttpUtil->>Storage : 获取用户Token
Storage-->>HttpUtil : 返回Token
HttpUtil->>HttpUtil : 处理请求参数
HttpUtil->>Crypto : 加密请求数据(可选)
Crypto-->>HttpUtil : 返回加密结果
HttpUtil->>Server : 发送HTTP请求
Server-->>HttpUtil : 返回响应
HttpUtil->>Crypto : 解密响应数据(可选)
Crypto-->>HttpUtil : 返回解密结果
HttpUtil-->>Client : 返回处理后的数据

图表来源

详细组件分析

HTTP 请求流程分析

flowchart TD
Start([开始请求]) --> CheckPrefix["检查URL前缀配置"]
CheckPrefix --> AddPrefix["添加URL前缀"]
AddPrefix --> ParamsPrep["参数预处理"]
ParamsPrep --> CheckEncryption{"检查加密开关"}
CheckEncryption --> |开启| EncryptData["加密请求数据"]
CheckEncryption --> |关闭| SkipEncrypt["跳过加密"]
EncryptData --> AddToken["添加用户Token"]
SkipEncrypt --> AddToken
AddToken --> SendRequest["发送HTTP请求"]
SendRequest --> CheckResponse{"检查响应状态"}
CheckResponse --> |成功| DecryptData["解密响应数据(可选)"]
CheckResponse --> |失败| ErrorHandler["错误处理"]
DecryptData --> ParseJSON["解析JSON数据"]
ParseJSON --> ReturnSuccess["返回成功响应"]
ErrorHandler --> ReturnError["返回错误响应"]

图表来源

加密解密流程分析

classDiagram
class TsCrypto {
-SM4 sm4
+constructor()
+encrypt(content) String
+decrypt(base64) String
}
class TsSM4 {
-Uint8Array key
-Uint8Array iv
-String mode
-String cipherType
-Uint32Array encryptRoundKeys
-Uint32Array decryptRoundKeys
+constructor(config)
+encrypt(plaintext) String
+decrypt(ciphertext) String
-padding(buffer) Uint8Array
-dePadding(buffer) Uint8Array
}
class TsGlobalConfig {
+defaultConfig
+getConfig() Object
+setConfig(obj) void
}
TsCrypto --> TsSM4 : 使用
TsCrypto --> TsGlobalConfig : 读取配置
TsSM4 --> TsGlobalConfig : 读取密钥

图表来源

章节来源

调试工具集成指南

浏览器开发者工具调试

1. 断点设置技巧

网络请求断点：

在 TsHttpUtil.js 的 req 函数中设置断点
检查 dealParamsBody 函数中的参数处理逻辑
监控 errorHandler 函数的错误处理流程

加密解密断点：

在 TsCrypto.js 的 encrypt 和 decrypt 方法中设置断点
监控 TsSM4.js 中的加密算法执行过程
检查 Base64 编码解码的中间结果

2. 变量检查方法

关键变量监控：

window.httpConfig - 全局配置对象
localStorage - 本地存储数据
process.env.NODE_ENV - 环境变量
请求头中的 token 字段

3. 控制台调试命令

// 检查全局配置
console.log('HTTP配置:', window.httpConfig);

// 检查存储状态
console.log('用户Token:', Storage.getUserToken());
console.log('加密开关:', Storage.getEncryptBody());

// 检查请求参数
console.log('请求参数:', dealParamsBody(options));

Node.js 调试器使用

1. 启动调试会话

# 使用 inspect 模式启动
node --inspect-brk=9229 index.js

# 或者使用 nodemon 进行热重载调试
nodemon --inspect-brk=9229 index.js

2. VS Code 调试配置

创建 .vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "调试 npm 工具包",
            "program": "${workspaceFolder}/index.js",
            "args": [],
            "console": "integratedTerminal",
            "internalConsoleOptions": "neverOpen"
        }
    ]
}

3. 条件断点设置

在 Node.js 中可以设置更精确的断点条件：

// 在加密函数中设置条件断点
if (typeof content === 'object') {
    debugger; // 仅当内容为对象时触发
}

// 在特定 URL 时断点
if (url.includes('api')) {
    debugger; // 仅在 API 请求时触发
}

章节来源

调试技术与方法

日志记录策略

1. 结构化日志记录

// 在关键函数中添加日志
function debugLog(operation, data, result) {
    console.log(`[${new Date().toISOString()}] ${operation}`, {
        data: JSON.stringify(data),
        result: JSON.stringify(result),
        stack: new Error().stack
    });
}

// 使用示例
debugLog('HTTP请求', {url, options}, response);

2. 环境特定的日志级别

// 开发环境启用详细日志
if (Common.isDevelopment()) {
    console.debug('详细调试信息');
    console.trace('调用栈跟踪');
}

// 生产环境限制日志输出
console.warn('警告信息');
console.error('错误信息');

3. 性能日志记录

// 记录函数执行时间
function performanceLog(funcName, callback) {
    const start = performance.now();
    try {
        const result = callback();
        const end = performance.now();
        console.log(`${funcName} 执行时间: ${end - start}ms`);
        return result;
    } catch (error) {
        const end = performance.now();
        console.error(`${funcName} 执行失败: ${end - start}ms`, error);
        throw error;
    }
}

错误追踪方法

1. 异步错误处理

// 在 Promise 中添加错误处理
async function safeRequest(url, options) {
    try {
        const response = await req(url, options);
        return response;
    } catch (error) {
        console.error('请求失败:', {
            url,
            error: error.message,
            stack: error.stack,
            timestamp: new Date()
        });
        throw error;
    }
}

2. 错误边界捕获

// 全局错误捕获
process.on('unhandledRejection', (reason, promise) => {
    console.error('未处理的 Promise 拒绝:', {
        reason: reason.message,
        stack: reason.stack,
        promise: promise
    });
});

process.on('uncaughtException', (error) => {
    console.error('未捕获的异常:', {
        error: error.message,
        stack: error.stack,
        timestamp: new Date()
    });
});

3. 调试信息收集

// 收集调试信息的工具函数
function collectDebugInfo() {
    return {
        timestamp: new Date(),
        environment: process.env.NODE_ENV,
        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'Node.js',
        memory: process.memoryUsage(),
        config: {
            httpConfig: window.httpConfig,
            encryptBody: Storage.getEncryptBody()
        }
    };
}

性能监控技巧

1. 内存使用监控

// 监控内存使用情况
function monitorMemory() {
    const usage = process.memoryUsage();
    console.log('内存使用:', {
        rss: `${Math.round(usage.rss / 1024 / 1024)} MB`,
        heapTotal: `${Math.round(usage.heapTotal / 1024 / 1024)} MB`,
        heapUsed: `${Math.round(usage.heapUsed / 1024 / 1024)} MB`
    });
}

// 定期监控
setInterval(monitorMemory, 5000);

2. 网络性能监控

// 监控 HTTP 请求性能
function monitorHttpRequest(url, startTime, endTime, status) {
    const duration = endTime - startTime;
    console.log('HTTP 请求性能:', {
        url,
        duration: `${duration}ms`,
        status,
        timestamp: new Date()
    });
    
    // 性能阈值告警
    if (duration > 3000) {
        console.warn(`慢请求警告: ${url} (${duration}ms)`);
    }
}

3. 加密性能监控

// 监控加密解密性能
function monitorCryptoOperation(operation, dataLength, startTime, endTime) {
    const duration = endTime - startTime;
    console.log(`${operation} 性能:`, {
        dataLength: `${dataLength} 字节`,
        duration: `${duration}ms`,
        throughput: `${(dataLength / duration).toFixed(2)} 字节/ms`
    });
}

章节来源

故障排查指南

常见问题诊断

1. 网络请求问题

问题症状：

请求超时
401 未授权
CORS 跨域错误

诊断步骤：

检查 Token 是否正确设置
验证 URL 前缀配置
确认请求头设置
检查服务器响应格式

// 调试网络请求
function debugNetworkRequest(url, options) {
    console.log('请求详情:', {
        url: url,
        options: JSON.stringify(options),
        token: Storage.getUserToken(),
        config: GlobalConfig.getConfig()
    });
    
    return req(url, options)
        .catch(error => {
            console.error('请求失败:', {
                url: url,
                error: error.message,
                response: error.response,
                stack: error.stack
            });
            throw error;
        });
}

2. 加密解密问题

问题症状：

解密失败
数据损坏
性能问题

诊断步骤：

验证密钥配置
检查数据格式
确认加密模式
监控性能指标

// 调试加密解密
function debugCryptoOperation(operation, data) {
    console.log(`${operation} 输入:`, {
        data: data,
        dataType: typeof data,
        dataLength: data ? data.length : 0
    });
    
    try {
        const result = operation(data);
        console.log(`${operation} 输出:`, {
            result: result,
            resultType: typeof result,
            resultLength: result ? result.length : 0
        });
        return result;
    } catch (error) {
        console.error(`${operation} 失败:`, {
            error: error.message,
            stack: error.stack
        });
        throw error;
    }
}

3. 存储问题

问题症状：

数据丢失
解析失败
类型不匹配

诊断步骤：

检查 localStorage 状态
验证数据序列化
确认默认值处理
监控存储容量

// 调试存储操作
function debugStorageOperation(operation, key, value) {
    console.log(`存储操作: ${operation}`, {
        key: key,
        value: value,
        storageSize: localStorage.length,
        storageKeys: Object.keys(localStorage)
    });
    
    try {
        const result = operation(key, value);
        console.log(`存储结果:`, {
            key: key,
            storedValue: localStorage.getItem(key),
            parsedValue: Common.parseJSON(localStorage.getItem(key))
        });
        return result;
    } catch (error) {
        console.error(`存储失败:`, {
            error: error.message,
            stack: error.stack
        });
        throw error;
    }
}

调试工具使用示例

1. 浏览器控制台调试

// 快速测试函数
function testFunction() {
    // 设置断点
    debugger;
    
    // 检查当前状态
    console.log('当前配置:', GlobalConfig.getConfig());
    console.log('用户信息:', {
        token: Storage.getUserToken(),
        encryptBody: Storage.getEncryptBody()
    });
    
    // 执行测试
    return TsCommon.isEmpty('');
}

// 执行测试
testFunction();

2. Node.js 调试会话

// 创建调试脚本
const debugScript = async () => {
    console.log('开始调试会话');
    
    // 设置断点
    debugger;
    
    // 测试加密功能
    const testData = {message: 'Hello World'};
    const encrypted = TsCrypto.encrypt(JSON.stringify(testData));
    const decrypted = TsCrypto.decrypt(encrypted);
    
    console.log('加密测试:', {
        original: testData,
        encrypted: encrypted,
        decrypted: JSON.parse(decrypted)
    });
    
    // 测试网络请求
    try {
        const response = await TsHttpUtil.get('/api/test');
        console.log('网络请求测试:', response);
    } catch (error) {
        console.error('网络请求失败:', error);
    }
};

debugScript();

3. 性能分析

// 性能基准测试
function performanceBenchmark() {
    const iterations = 1000;
    const testData = 'Test data for encryption'.repeat(100);
    
    console.time('批量加密');
    for (let i = 0; i < iterations; i++) {
        TsCrypto.encrypt(testData);
    }
    console.timeEnd('批量加密');
    
    console.time('批量解密');
    const encryptedData = TsCrypto.encrypt(testData);
    for (let i = 0; i < iterations; i++) {
        TsCrypto.decrypt(encryptedData);
    }
    console.timeEnd('批量解密');
}

performanceBenchmark();

章节来源

最佳实践总结

系统性调试方法

1. 分层调试策略

flowchart TD
Problem[问题出现] --> Identify[识别问题类型]
Identify --> Isolate[隔离问题范围]
Isolate --> Test[测试最小复现]
Test --> Debug[深入调试]
Debug --> Fix[修复问题]
Fix --> Verify[验证修复]
Verify --> Monitor[持续监控]
Identify --> |网络问题| NetworkDebug[网络调试]
Identify --> |加密问题| CryptoDebug[加密调试]
Identify --> |存储问题| StorageDebug[存储调试]
Identify --> |性能问题| PerfDebug[性能调试]
NetworkDebug --> Test
CryptoDebug --> Test
StorageDebug --> Test
PerfDebug --> Test

2. 调试工具组合使用

多工具协同调试：

浏览器开发者工具 + Node.js 调试器
控制台日志 + 断点调试
性能分析 + 内存监控
错误追踪 + 堆栈分析

3. 调试效率提升技巧

快速定位问题：

使用条件断点减少调试时间
实施渐进式调试策略
建立标准化的调试流程
维护调试知识库

调试报告模板：

# 调试报告

## 问题描述
- 问题现象：
- 影响范围：
- 复现频率：

## 调试过程
- 关键断点位置：
- 观察到的异常行为：
- 相关日志信息：

## 根因分析
- 问题原因：
- 影响因素：
- 代码路径：

## 解决方案
- 临时修复：
- 永久解决方案：
- 预防措施：

## 验证结果
- 修复验证：
- 回归测试：
- 性能影响：

调试工具配置建议

1. 开发环境配置

// 开发环境调试配置
const devConfig = {
    enableLogging: true,
    logLevel: 'debug',
    enableBreakpoints: true,
    autoReload: true,
    verboseErrors: true
};

// 生产环境调试配置
const prodConfig = {
    enableLogging: false,
    logLevel: 'error',
    enableBreakpoints: false,
    autoReload: false,
    verboseErrors: false
};

2. 调试工具推荐

必备工具：

浏览器开发者工具
VS Code 调试器
Node.js Inspector
Chrome DevTools
Postman/Fiddler

高级工具：

Performance Profiler
Memory Profiler
Network Monitor
Console Logger

通过遵循这些调试工具和方法指南，开发者可以更高效地诊断和解决基于该 npm 工具包的各种问题，提高开发效率和代码质量。

19 KiB Raw Permalink Blame History Unescape Escape

调试工具和方法

目录

简介

项目结构

核心组件

通用工具模块 (TsCommon.js)

网络请求模块 (TsHttpUtil.js)

存储模块 (TsStorage.js)

加密模块 (TsCrypto.js)

架构概览

详细组件分析

HTTP 请求流程分析

加密解密流程分析

调试工具集成指南

浏览器开发者工具调试

1. 断点设置技巧

2. 变量检查方法

3. 控制台调试命令

Node.js 调试器使用

1. 启动调试会话

2. VS Code 调试配置

3. 条件断点设置

调试技术与方法

日志记录策略

1. 结构化日志记录

2. 环境特定的日志级别

3. 性能日志记录

错误追踪方法

1. 异步错误处理

2. 错误边界捕获

3. 调试信息收集

性能监控技巧

1. 内存使用监控

2. 网络性能监控

3. 加密性能监控

故障排查指南

常见问题诊断

1. 网络请求问题

2. 加密解密问题

3. 存储问题

调试工具使用示例

1. 浏览器控制台调试

2. Node.js 调试会话

3. 性能分析

最佳实践总结

系统性调试方法

1. 分层调试策略

2. 调试工具组合使用

3. 调试效率提升技巧

调试工具配置建议

1. 开发环境配置

2. 调试工具推荐

19 KiB

Raw Permalink Blame History