# 调试工具和方法

<cite>
**本文档中引用的文件**
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [调试工具集成指南](#调试工具集成指南)
7. [调试技术与方法](#调试技术与方法)
8. [性能监控与优化](#性能监控与优化)
9. [故障排查指南](#故障排查指南)
10. [最佳实践总结](#最佳实践总结)

## 简介

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

## 项目结构

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

```mermaid
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
```

**图表来源**
- [index.js:1-16](file://index.js#L1-L16)
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)

**章节来源**
- [index.js:1-16](file://index.js#L1-L16)
- [package.json:1-24](file://package.json#L1-L24)

## 核心组件

### 通用工具模块 (TsCommon.js)

提供基础的 JavaScript 工具函数，包括：
- URL 参数解析
- 数据类型检查
- JSON 解析安全处理
- 字符串操作
- 环境检测

### 网络请求模块 (TsHttpUtil.js)

基于 umi-request 封装的 HTTP 客户端，支持：
- 自动错误处理
- 请求参数预处理
- 数据加密传输
- 响应数据解密
- Token 自动注入

### 存储模块 (TsStorage.js)

本地存储管理，支持：
- 对象序列化存储
- 用户 Token 管理
- 加密开关控制
- 类型安全的数据获取

### 加密模块 (TsCrypto.js)

基于 SM4 算法的加密解密工具，包含：
- SM4 算法实现
- Base64 编码支持
- 动态密钥处理
- 加密模式配置

**章节来源**
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)

## 架构概览

```mermaid
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 : 返回处理后的数据
```

**图表来源**
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
- [TsStorage.js:9-15](file://src/utils/TsStorage.js#L9-L15)

## 详细组件分析

### HTTP 请求流程分析

```mermaid
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["返回错误响应"]
```

**图表来源**
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)

### 加密解密流程分析

```mermaid
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 : 读取密钥
```

**图表来源**
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)
- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)

**章节来源**
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)

## 调试工具集成指南

### 浏览器开发者工具调试

#### 1. 断点设置技巧

**网络请求断点**：
- 在 `TsHttpUtil.js` 的 `req` 函数中设置断点
- 检查 `dealParamsBody` 函数中的参数处理逻辑
- 监控 `errorHandler` 函数的错误处理流程

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

#### 2. 变量检查方法

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

#### 3. 控制台调试命令

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

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

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

### Node.js 调试器使用

#### 1. 启动调试会话

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

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

#### 2. VS Code 调试配置

创建 `.vscode/launch.json`：

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

#### 3. 条件断点设置

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

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

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

**章节来源**
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)

## 调试技术与方法

### 日志记录策略

#### 1. 结构化日志记录

```javascript
// 在关键函数中添加日志
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. 环境特定的日志级别

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

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

#### 3. 性能日志记录

```javascript
// 记录函数执行时间
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. 异步错误处理

```javascript
// 在 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. 错误边界捕获

```javascript
// 全局错误捕获
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. 调试信息收集

```javascript
// 收集调试信息的工具函数
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. 内存使用监控

```javascript
// 监控内存使用情况
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. 网络性能监控

```javascript
// 监控 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. 加密性能监控

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

**章节来源**
- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)
- [TsHttpUtil.js:7-23](file://src/https/TsHttpUtil.js#L7-L23)
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)

## 故障排查指南

### 常见问题诊断

#### 1. 网络请求问题

**问题症状**：
- 请求超时
- 401 未授权
- CORS 跨域错误

**诊断步骤**：
1. 检查 Token 是否正确设置
2. 验证 URL 前缀配置
3. 确认请求头设置
4. 检查服务器响应格式

```javascript
// 调试网络请求
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. 加密解密问题

**问题症状**：
- 解密失败
- 数据损坏
- 性能问题

**诊断步骤**：
1. 验证密钥配置
2. 检查数据格式
3. 确认加密模式
4. 监控性能指标

```javascript
// 调试加密解密
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. 存储问题

**问题症状**：
- 数据丢失
- 解析失败
- 类型不匹配

**诊断步骤**：
1. 检查 localStorage 状态
2. 验证数据序列化
3. 确认默认值处理
4. 监控存储容量

```javascript
// 调试存储操作
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. 浏览器控制台调试

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

// 执行测试
testFunction();
```

#### 2. Node.js 调试会话

```javascript
// 创建调试脚本
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. 性能分析

```javascript
// 性能基准测试
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();
```

**章节来源**
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)

## 最佳实践总结

### 系统性调试方法

#### 1. 分层调试策略

```mermaid
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. 调试效率提升技巧

**快速定位问题**：
- 使用条件断点减少调试时间
- 实施渐进式调试策略
- 建立标准化的调试流程
- 维护调试知识库

**调试报告模板**：

```markdown
# 调试报告

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

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

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

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

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

### 调试工具配置建议

#### 1. 开发环境配置

```javascript
// 开发环境调试配置
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 工具包的各种问题，提高开发效率和代码质量。