Files

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

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

18 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) - [TsCrypto.js](file://src/utils/TsCrypto.js) - [TsSM4.js](file://src/utils/TsSM4.js) - [TsStorage.js](file://src/utils/TsStorage.js) - [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js) - [TsHttpUtil.js](file://src/https/TsHttpUtil.js)

简介

npm-tool 是一个企业级的 JavaScript 工具包，提供了网络请求、数据加密解密、本地存储、通用工具函数等功能。该工具包采用模块化设计，支持多种加密模式和灵活的配置选项，适用于各种 Web 应用场景。

本指南旨在帮助开发者快速识别和解决使用 npm-tool 时可能遇到的各种问题，提供系统性的调试方法和最佳实践建议。

项目结构

graph TB
subgraph "项目根目录"
A[index.js]
B[package.json]
C[README.md]
end
subgraph "src/utils"
D[TsCommon.js]
E[TsCrypto.js]
F[TsSM4.js]
G[TsStorage.js]
H[TsGlobalConfig.js]
end
subgraph "src/https"
I[TsHttpUtil.js]
end
A --> D
A --> E
A --> F
A --> G
A --> H
A --> I
E --> F
E --> H
I --> G
I --> D
I --> E
I --> H

图表来源

章节来源

核心组件

npm-tool 包含以下核心组件：

网络请求组件 (TsHttpUtil)

基于 umi-request 的 HTTP 客户端
支持 GET、POST、表单提交等多种请求方式
内置加密解密功能
统一的错误处理机制

数据加密组件 (TsCrypto)

基于 SM4 算法的对称加密
支持 ECB 和 CBC 模式
Base64 编码支持

存储组件 (TsStorage)

基于 localStorage 的数据持久化
支持用户 Token 管理
加密开关控制

通用工具组件 (TsCommon)

URL 参数解析
数据类型判断
JSON 解析工具
环境检测

章节来源

架构概览

graph TD
subgraph "应用层"
APP[业务应用]
end
subgraph "HTTP 层"
HTTP[TsHttpUtil]
CONFIG[TsGlobalConfig]
STORAGE[TsStorage]
end
subgraph "加密层"
CRYPTO[TsCrypto]
SM4[TsSM4]
end
subgraph "工具层"
COMMON[TsCommon]
end
subgraph "外部依赖"
UMI[umi-request]
BASE64[base64-js]
end
APP --> HTTP
HTTP --> CONFIG
HTTP --> STORAGE
HTTP --> CRYPTO
CRYPTO --> SM4
HTTP --> COMMON
HTTP --> UMI
CRYPTO --> BASE64
SM4 --> BASE64
HTTP -.->|错误处理| APP
HTTP -.->|回调函数| APP

图表来源

详细组件分析

网络请求组件 (TsHttpUtil)

请求流程图

sequenceDiagram
participant Client as 应用客户端
participant HttpUtil as TsHttpUtil
participant Config as TsGlobalConfig
participant Storage as TsStorage
participant Crypto as TsCrypto
participant Request as umi-request
participant Server as 服务器
Client->>HttpUtil : 发送请求
HttpUtil->>Config : 获取全局配置
HttpUtil->>Storage : 获取用户Token
HttpUtil->>HttpUtil : 处理请求参数
alt 需要加密
HttpUtil->>Crypto : 加密请求数据
Crypto-->>HttpUtil : 返回加密结果
end
HttpUtil->>Request : 发送HTTP请求
Request->>Server : 执行请求
Server-->>Request : 返回响应
Request-->>HttpUtil : 返回响应数据
HttpUtil->>HttpUtil : 处理响应数据
alt 响应需要解密
HttpUtil->>Crypto : 解密响应数据
Crypto-->>HttpUtil : 返回解密结果
end
HttpUtil-->>Client : 返回处理后的数据

图表来源

错误处理机制

flowchart TD
Start([请求开始]) --> CheckParams["检查请求参数"]
CheckParams --> ParamsValid{"参数有效?"}
ParamsValid --> |否| ReturnError["返回参数错误"]
ParamsValid --> |是| SendRequest["发送HTTP请求"]
SendRequest --> ReceiveResponse["接收响应"]
ReceiveResponse --> ResponseType{"响应类型"}
ResponseType --> |成功| CheckCode["检查状态码"]
ResponseType --> |网络错误| NetworkError["网络错误处理"]
ResponseType --> |服务器错误| ServerError["服务器错误处理"]
CheckCode --> CodeValid{"状态码200?"}
CodeValid --> |是| CheckEncrypt{"需要解密?"}
CodeValid --> |否| HttpError["HTTP错误处理"]
CheckEncrypt --> |是| DecryptData["解密数据"]
CheckEncrypt --> |否| ReturnData["返回数据"]
DecryptData --> ParseJSON["解析JSON"]
ParseJSON --> ReturnData
ReturnError --> End([结束])
NetworkError --> End
ServerError --> End
HttpError --> End
ReturnData --> End

图表来源

章节来源

TsHttpUtil.js:1-171

加密解密组件 (TsCrypto)

加密算法流程

flowchart TD
Input[输入明文] --> ConvertUTF8["转换为UTF-8字节数组"]
ConvertUTF8 --> Padding["PKCS7填充"]
Padding --> SplitBlocks["分割为16字节块"]
SplitBlocks --> ModeSelect{"选择加密模式"}
ModeSelect --> |CBC模式| CBCProcess["CBC加密处理"]
ModeSelect --> |ECB模式| ECBProcess["ECB加密处理"]
CBCProcess --> XORChain["异或链式处理"]
XORChain --> BlockCrypt["块加密"]
BlockCrypt --> Output[输出密文]
ECBProcess --> BlockCrypt
BlockCrypt --> Output

图表来源

关键配置参数

参数名称	类型	默认值	描述
keyBuffer	Uint8Array	从base64Key转换而来	16字节密钥缓冲区
mode	string	"ecb"	加密模式 (cbc/ecb)
cipherType	string	"base64"	输出类型 (base64/text)

章节来源

存储组件 (TsStorage)

数据存储流程

flowchart TD
SaveRequest[保存请求] --> CheckValue["检查值类型"]
CheckValue --> Serialize["序列化JSON"]
Serialize --> Store["localStorage存储"]
Store --> Success[存储成功]
GetRequest[获取请求] --> Load["从localStorage加载"]
Load --> ParseJSON["解析JSON"]
ParseJSON --> CheckResult{"解析成功?"}
CheckResult --> |是| ReturnData["返回数据"]
CheckResult --> |否| ReturnDefault["返回默认值"]

图表来源

TsStorage.js:31-43

章节来源

TsStorage.js:1-55

依赖关系分析

graph LR
subgraph "核心模块"
A[index.js]
B[TsHttpUtil]
C[TsCrypto]
D[TsSM4]
E[TsStorage]
F[TsCommon]
G[TsGlobalConfig]
end
subgraph "外部依赖"
H[umi-request]
I[base64-js]
end
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
B --> C
B --> E
B --> F
B --> G
B --> H
C --> D
C --> G
C --> I
D --> I
E --> F
G --> H

图表来源

章节来源

package.json:19-22

性能考虑

网络请求性能优化

请求缓存策略
- 对于重复的 GET 请求，建议在应用层实现缓存机制
- 合理设置请求头以利用浏览器缓存
批量请求处理
- 对于多个相关的请求，考虑合并为单个请求
- 使用并发请求时注意避免过度并发导致的性能问题
数据传输优化
- 启用压缩传输（gzip/deflate）
- 减少不必要的数据传输量

加密性能优化

加密算法选择
- SM4 算法相对 AES 更快，适合大量数据加密场景
- 对于小数据量，加密开销可能超过数据本身大小
内存管理
- 注意大对象加密时的内存使用情况
- 及时释放不再使用的加密对象
异步处理
- 对于耗时的加密操作，考虑使用 Web Workers
- 避免阻塞主线程

存储性能优化

localStorage 限制
- 单个域名下约 5-10MB 存储空间
- 大量数据存储时考虑分片策略
序列化开销
- 复杂对象的 JSON 序列化可能影响性能
- 对频繁读取的数据考虑缓存策略

故障排除指南

网络请求故障排除

常见错误类型及解决方案

1. CORS 跨域问题

症状: 控制台出现跨域错误，请求被阻止
原因: 服务器未正确配置 CORS 头部
解决方案:
- 确认服务器已设置正确的 Access-Control-Allow-Origin
- 检查预检请求的处理逻辑
- 验证凭据设置 (credentials: 'include')

2. 认证失败

症状: HTTP 401 错误，用户无权限
原因: Token 过期或无效
解决方案:
- 检查用户 Token 是否正确存储
- 实现 Token 刷新机制
- 验证服务器认证配置

3. 请求超时

症状: 网络请求长时间无响应
原因: 服务器响应慢或网络问题
解决方案:
- 设置合理的超时时间
- 实现重试机制
- 检查服务器性能

4. 数据格式错误

症状: JSON 解析失败或数据格式不匹配
原因: 服务器返回数据格式不符合预期
解决方案:
- 检查服务器响应格式
- 实现数据验证和转换
- 添加容错处理

调试步骤

flowchart TD
Problem[发现网络问题] --> CheckConsole["检查浏览器控制台"]
CheckConsole --> VerifyNetwork["验证网络连接"]
VerifyNetwork --> TestEndpoint["测试目标端点"]
TestEndpoint --> InspectHeaders["检查请求/响应头"]
InspectHeaders --> ValidateData["验证数据格式"]
ValidateData --> CheckAuth["检查认证信息"]
CheckAuth --> ReviewLogs["查看服务器日志"]
ReviewLogs --> FixIssue["修复问题"]
FixIssue --> VerifyFix["验证修复效果"]

章节来源

加密解密故障排除

常见加密问题

1. 密钥长度错误

症状: 抛出 "key should be a 16 bytes string" 错误
原因: 密钥不是 16 字节长度
解决方案:
- 确保 base64Key 正确且长度为 24 字节（对应 16 字节二进制）
- 验证密钥格式和编码

2. IV 初始化向量错误

症状: 抛出 "iv error" 错误
原因: CBC 模式下的 IV 不是 16 字节
解决方案:
- 确保 IV 参数存在且长度为 16 字节
- 检查 IV 的生成和传递过程

3. 加密数据解密失败

症状: 解密后得到乱码或抛出异常
原因: 数据被篡改或密钥不匹配
解决方案:
- 验证数据完整性
- 确认使用相同的密钥和模式
- 检查 Base64 编码/解码过程

加密调试流程

flowchart TD
Start[开始加密调试] --> CheckKey["检查密钥配置"]
CheckKey --> KeyValid{"密钥有效?"}
KeyValid --> |否| FixKey["修复密钥配置"]
KeyValid --> |是| CheckMode["检查加密模式"]
CheckMode --> ModeValid{"模式正确?"}
ModeValid --> |否| FixMode["修复模式配置"]
ModeValid --> |是| TestEncrypt["测试加密功能"]
TestEncrypt --> EncryptSuccess{"加密成功?"}
EncryptSuccess --> |否| DebugEncrypt["调试加密过程"]
EncryptSuccess --> |是| TestDecrypt["测试解密功能"]
TestDecrypt --> DecryptSuccess{"解密成功?"}
DecryptSuccess --> |否| DebugDecrypt["调试解密过程"]
DecryptSuccess --> |是| Complete[完成调试]
DebugEncrypt --> FixEncrypt["修复加密问题"]
DebugDecrypt --> FixDecrypt["修复解密问题"]
FixKey --> CheckKey
FixMode --> CheckMode
FixEncrypt --> TestEncrypt
FixDecrypt --> TestDecrypt

章节来源

存储访问异常

常见存储问题

1. localStorage 访问失败

症状: 抛出 SecurityError 或 QuotaExceededError
原因: 浏览器安全策略或存储配额限制
解决方案:
- 检查浏览器隐私设置
- 清理过期的存储数据
- 实现存储容量监控

2. 数据序列化失败

症状: JSON.stringify 抛出异常
原因: 循环引用或不可序列化对象
解决方案:
- 避免存储循环引用的对象
- 使用自定义序列化方法
- 过滤不可序列化的属性

3. 数据获取为空

症状: Storage.get 返回空值或默认值
原因: 数据未正确存储或键名不匹配
解决方案:
- 验证存储键名的一致性
- 检查存储前的数据格式
- 实现数据完整性检查

存储调试方法

flowchart TD
StorageError[存储问题] --> CheckBrowser["检查浏览器兼容性"]
CheckBrowser --> VerifyStorage["验证存储可用性"]
VerifyStorage --> TestWrite["测试写入功能"]
TestWrite --> WriteSuccess{"写入成功?"}
WriteSuccess --> |否| FixWrite["修复写入问题"]
WriteSuccess --> |是| TestRead["测试读取功能"]
TestRead --> ReadSuccess{"读取成功?"}
ReadSuccess --> |否| FixRead["修复读取问题"]
ReadSuccess --> |是| CheckData["检查数据完整性"]
CheckData --> Complete[问题解决]
FixWrite --> VerifyStorage
FixRead --> TestWrite

章节来源

TsStorage.js:31-43

配置相关问题

全局配置故障排除

1. 配置项缺失

症状: 配置获取失败或返回默认值
原因: window.httpConfig 未正确初始化
解决方案:
- 确保在应用启动时调用 setConfig
- 验证配置对象的完整性
- 检查配置项的命名一致性

2. 动态配置更新失败

症状: 配置更新后仍使用旧值
原因: 配置缓存或作用域问题
解决方案:
- 确保使用最新的配置对象
- 验证配置更新的时机
- 检查配置的作用域范围

章节来源

TsGlobalConfig.js:19-29

日志记录和监控最佳实践

日志记录策略

错误日志
- 记录完整的错误堆栈信息
- 包含请求参数和响应数据
- 添加时间戳和上下文信息
性能日志
- 记录请求耗时和响应大小
- 监控加密解密性能
- 跟踪存储操作的性能
调试日志
- 在开发环境中启用详细日志
- 区分不同级别的日志信息
- 提供可配置的日志级别

监控指标

网络请求指标
- 请求成功率和失败率
- 平均响应时间和最大响应时间
- 错误类型分布统计
加密性能指标
- 加密/解密耗时统计
- 数据大小与处理时间的关系
- 内存使用情况监控
存储性能指标
- 存储操作成功率
- 数据读取/写入延迟
- 存储空间使用率

性能问题诊断和优化

网络性能诊断

请求分析
- 使用浏览器开发者工具分析网络请求
- 检查请求头和响应头的大小
- 识别慢请求和异常请求
缓存策略
- 实现合理的缓存策略
- 避免不必要的重复请求
- 优化缓存失效机制
连接池管理
- 合理管理 HTTP 连接
- 避免连接泄漏
- 优化并发请求数量

加密性能优化

算法选择
- 根据数据大小选择合适的加密算法
- 考虑硬件加速支持
- 评估加密强度与性能的平衡
内存管理
- 及时释放加密相关的内存
- 避免内存泄漏
- 监控内存使用情况
批处理优化
- 对大量数据进行批处理
- 减少加密调用次数
- 实现异步处理机制

存储性能优化

数据组织
- 合理组织存储的数据结构
- 避免过大的单个存储项
- 实现数据分片存储
访问模式优化
- 优化数据的读取和写入模式
- 实现缓存机制
- 减少存储操作的频率
容量管理
- 监控存储空间使用情况
- 实现自动清理机制
- 提供存储容量预警

结论

npm-tool 工具包提供了完整的前端开发基础设施，涵盖了网络请求、数据加密解密、本地存储和通用工具等多个方面。通过本文档提供的故障排除指南和最佳实践建议，开发者可以更有效地识别和解决使用过程中遇到的各种问题。

关键要点包括：

建立系统性的调试流程和方法
理解各组件之间的依赖关系和交互方式
实施适当的性能监控和优化策略
建立完善的错误处理和日志记录机制

对于复杂问题，建议按照本文档提供的诊断流程逐步排查，从最简单的配置问题开始，逐步深入到复杂的算法和性能问题。同时，结合实际应用场景的特点，制定相应的预防措施和应急方案。

18 KiB Raw Permalink Blame History Unescape Escape

故障排除

目录

简介

项目结构

核心组件

网络请求组件 (TsHttpUtil)

数据加密组件 (TsCrypto)

存储组件 (TsStorage)

通用工具组件 (TsCommon)

架构概览

详细组件分析

网络请求组件 (TsHttpUtil)

请求流程图

错误处理机制

加密解密组件 (TsCrypto)

加密算法流程

关键配置参数

存储组件 (TsStorage)

数据存储流程

依赖关系分析

性能考虑

网络请求性能优化

加密性能优化

存储性能优化

故障排除指南

网络请求故障排除

常见错误类型及解决方案

调试步骤

加密解密故障排除

常见加密问题

加密调试流程

存储访问异常

常见存储问题

存储调试方法

配置相关问题

全局配置故障排除

日志记录和监控最佳实践

日志记录策略

监控指标

性能问题诊断和优化

网络性能诊断

加密性能优化

存储性能优化

结论

18 KiB

Raw Permalink Blame History