16 KiB
16 KiB
核心模块
**本文引用的文件** - [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) - [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js) - [TsSM4.js](file://src/utils/TsSM4.js) - [TsStorage.js](file://src/utils/TsStorage.js) - [TsHttpUtil.js](file://src/https/TsHttpUtil.js)目录
简介
npm-tool 是一个专为前端应用设计的综合性工具包，提供了网络请求、数据加密、存储管理、通用工具函数等核心功能。该工具包采用模块化设计，通过清晰的职责分离和接口抽象，为开发者提供了一套完整的前端开发基础设施。
本工具包的核心设计理念包括：
- 模块化架构：每个功能模块独立封装，职责单一明确
- 可扩展性：通过配置中心支持运行时配置调整
- 安全性：内置SM4对称加密算法，保障数据传输安全
- 易用性：提供简洁的API接口，降低使用复杂度
项目结构
项目采用按功能域组织的目录结构，主要分为以下层次：
graph TB
subgraph "根目录"
Root[index.js]
Package[package.json]
Readme[README.md]
end
subgraph "源代码结构"
Utils[src/utils/]
Https[src/https/]
subgraph "工具模块"
Common[TsCommon.js]
Crypto[TsCrypto.js]
SM4[TsSM4.js]
Storage[TsStorage.js]
GlobalConfig[TsGlobalConfig.js]
end
subgraph "HTTP模块"
HttpUtil[TsHttpUtil.js]
end
end
Root --> Utils
Root --> Https
Utils --> Common
Utils --> Crypto
Utils --> SM4
Utils --> Storage
Utils --> GlobalConfig
Https --> HttpUtil
图表来源
章节来源
核心组件
npm-tool 工具包由六个核心模块组成，每个模块都有明确的职责分工：
模块职责矩阵
| 模块名称 | 主要职责 | 关键功能 | 依赖关系 |
|---|---|---|---|
| TsCommon | 通用工具函数 | 字符串处理、类型判断、URL解析 | 无 |
| TsStorage | 数据持久化 | 本地存储、用户令牌管理 | TsCommon |
| TsSM4 | SM4加密算法 | 对称加密解密、密钥管理 | base64-js |
| TsCrypto | 加密服务层 | 加密解密接口、密钥转换 | TsSM4, TsGlobalConfig |
| TsGlobalConfig | 全局配置管理 | 配置读取设置、运行时配置 | 无 |
| TsHttpUtil | HTTP请求封装 | 网络请求、参数处理、错误处理 | umi-request |
章节来源
- TsCommon.js:1-98
- TsStorage.js:1-55
- TsSM4.js:1-456
- TsCrypto.js:1-34
- TsGlobalConfig.js:1-34
- TsHttpUtil.js:1-171
架构概览
工具包采用分层架构设计，从底层到上层依次为：基础工具层、加密服务层、存储管理层、HTTP请求层。
graph TB
subgraph "应用层"
App[业务应用]
end
subgraph "HTTP请求层"
HttpUtil[TsHttpUtil]
Request[umi-request]
end
subgraph "加密服务层"
Crypto[TsCrypto]
SM4[TsSM4]
Base64[base64-js]
end
subgraph "存储管理层"
Storage[TsStorage]
LocalStorage[localStorage]
end
subgraph "配置管理层"
GlobalConfig[TsGlobalConfig]
end
subgraph "工具函数层"
Common[TsCommon]
end
App --> HttpUtil
HttpUtil --> Crypto
HttpUtil --> Storage
HttpUtil --> GlobalConfig
HttpUtil --> Request
Crypto --> SM4
Crypto --> Base64
Storage --> Common
SM4 --> Base64
图表来源
- TsHttpUtil.js:1-171
- TsCrypto.js:1-34
- TsSM4.js:1-456
- TsStorage.js:1-55
- TsGlobalConfig.js:1-34
- TsCommon.js:1-98
详细组件分析
TsCommon 通用工具模块
TsCommon 模块提供了一系列基础的工具函数，涵盖了字符串处理、类型判断、URL解析等常用功能。
核心功能特性
classDiagram
class TsCommon {
+getParamFormUrl(key, host) string
+isEmpty(value) boolean
+parseJSON(value, def) any
+split(obj, seq) string[]
+isDevelopment() boolean
+replaceAll(string, s1, s2) string
+endWith(string, endStr) boolean
}
note for TsCommon "提供基础工具函数<br/>字符串处理<br/>类型判断<br/>URL解析"
图表来源
设计模式与实现要点
- 纯函数设计：所有函数都是无状态的纯函数，便于测试和复用
- 容错处理：对可能的异常情况进行了充分的try-catch处理
- 类型安全：通过严格的参数验证确保函数的健壮性
章节来源
TsStorage 存储模块
TsStorage 模块基于 localStorage 实现了数据持久化功能，特别针对用户令牌和配置信息进行了优化。
数据存储策略
flowchart TD
Start([存储请求]) --> CheckType{"检查数据类型"}
CheckType --> |对象| Serialize["JSON序列化"]
CheckType --> |基本类型| Direct["直接存储"]
Serialize --> Wrap["包装为{data: value}"]
Direct --> Wrap
Wrap --> Save["localStorage.setItem"]
Save --> End([存储完成])
subgraph "读取流程"
LoadStart([读取请求]) --> GetItem["localStorage.getItem"]
GetItem --> Parse["JSON.parse"]
Parse --> Extract["提取data字段"]
Extract --> LoadEnd([返回数据])
end
图表来源
特殊功能设计
- 用户令牌管理：专门的token存储接口，简化了认证流程
- 加密开关控制：支持动态启用/禁用数据加密
- 默认值处理：提供灵活的默认值机制
章节来源
TsSM4 加密算法模块
TsSM4 模块实现了国家商用密码标准 SM4 的完整算法，支持ECB和CBC两种加密模式。
SM4算法实现架构
classDiagram
class TsSM4 {
-key Uint8Array
-iv Uint8Array
-mode string
-cipherType string
-encryptRoundKeys Uint32Array
-decryptRoundKeys Uint32Array
+constructor(config)
+encrypt(plaintext) string
+decrypt(ciphertext) string
-doBlockCrypt(blockData, roundKeys) Uint32Array
-spawnEncryptRoundKeys() void
-padding(originalBuffer) Uint8Array
-dePadding(paddedBuffer) Uint8Array
}
class Crypt {
+stringToArrayBufferInUtf8(str) Uint8Array
+utf8ArrayBufferToString(buffer) string
+arrayBufferToBase64(buffer) string
+base64ToArrayBuffer(base64) Uint8Array
}
TsSM4 --> Crypt : "使用"
图表来源
加密算法特性
- 双模式支持：同时支持ECB和CBC加密模式
- 密钥管理：自动密钥扩展和轮转密钥生成
- 填充机制：实现PKCS#7填充标准
- 编码转换：支持Base64和文本两种输出格式
章节来源
TsCrypto 加密服务模块
TsCrypto 作为加密服务层，提供了统一的加密解密接口，并与全局配置系统集成。
加密服务架构
sequenceDiagram
participant Client as 客户端
participant Crypto as TsCrypto
participant SM4 as TsSM4
participant Config as TsGlobalConfig
Client->>Crypto : encrypt(content)
Crypto->>Config : getConfig()
Config-->>Crypto : base64Key
Crypto->>SM4 : new SM4(config)
Crypto->>SM4 : encrypt(content)
SM4-->>Crypto : encryptedData
Crypto-->>Client : 返回加密结果
图表来源
服务设计特点
- 配置驱动：通过全局配置管理密钥和加密参数
- 接口统一：提供简洁的加密解密API
- 依赖注入：通过构造函数注入底层加密实现
章节来源
TsGlobalConfig 全局配置模块
TsGlobalConfig 提供了全局配置管理功能，支持运行时配置更新和默认配置机制。
配置管理流程
flowchart TD
Init([初始化]) --> LoadDefault["加载默认配置"]
LoadDefault --> CheckWindow{"检查window.httpConfig"}
CheckWindow --> |存在| MergeConfig["合并配置"]
CheckWindow --> |不存在| UseDefault["使用默认配置"]
MergeConfig --> StoreConfig["存储到window.httpConfig"]
UseDefault --> StoreConfig
StoreConfig --> ExportConfig["导出配置接口"]
subgraph "配置更新"
Update([setConfig]) --> Merge["深度合并"]
Merge --> Store["存储到window.httpConfig"]
Store --> Notify["通知配置变更"]
end
图表来源
配置系统设计
- 默认值机制：提供完善的默认配置，确保系统稳定性
- 运行时更新：支持在应用运行时动态更新配置
- 环境适配：支持函数形式的动态配置生成
章节来源
TsHttpUtil HTTP请求模块
TsHttpUtil 是工具包的核心模块，封装了网络请求的所有细节，提供了简洁易用的API。
HTTP请求处理流程
sequenceDiagram
participant Client as 客户端
participant HttpUtil as TsHttpUtil
participant Storage as TsStorage
participant Crypto as TsCrypto
participant Request as umi-request
participant Server as 服务器
Client->>HttpUtil : post(url, data)
HttpUtil->>HttpUtil : dealParamsBody(options)
HttpUtil->>Storage : getEncryptBody()
Storage-->>HttpUtil : 加密开关状态
HttpUtil->>Crypto : encrypt(JSON.stringify(data))
Crypto-->>HttpUtil : 加密后的数据
HttpUtil->>Request : request(url, options)
Request->>Server : HTTP请求
Server-->>Request : 响应数据
Request-->>HttpUtil : 响应对象
HttpUtil->>HttpUtil : 处理响应数据
HttpUtil-->>Client : {data, recordsTotal}
图表来源
请求处理核心逻辑
- 参数预处理：统一处理分页参数、equals条件等特殊需求
- 动态前缀：支持根据URL动态生成API前缀
- 加密处理：根据配置自动对请求体进行加密
- 响应解密：自动解密服务器返回的加密数据
- 错误处理：统一的错误处理和状态码映射
章节来源
依赖分析
工具包的依赖关系体现了清晰的分层架构和模块化设计原则。
graph TB
subgraph "外部依赖"
UmiRequest[umi-request@1.4.0]
Base64Js[base64-js@1.5.1]
end
subgraph "内部模块依赖"
index[index.js]
subgraph "HTTP模块"
TsHttpUtil
TsStorage
TsCrypto
TsGlobalConfig
end
subgraph "工具模块"
TsCommon
TsSM4
end
end
index --> TsHttpUtil
index --> TsCommon
index --> TsStorage
index --> TsSM4
index --> TsCrypto
index --> TsGlobalConfig
TsHttpUtil --> UmiRequest
TsHttpUtil --> TsStorage
TsHttpUtil --> TsCrypto
TsHttpUtil --> TsGlobalConfig
TsHttpUtil --> TsCommon
TsCrypto --> TsSM4
TsCrypto --> Base64Js
TsCrypto --> TsGlobalConfig
TsStorage --> TsCommon
TsSM4 --> Base64Js
图表来源
依赖关系分析
直接依赖
- umi-request：HTTP请求库，提供网络通信能力
- base64-js：Base64编码解码工具
间接依赖
- TsHttpUtil 依赖于所有其他模块，形成核心依赖环
- TsCrypto 依赖于TsSM4和TsGlobalConfig
- TsStorage 依赖于TsCommon
循环依赖检测
该工具包采用了良好的模块化设计，避免了循环依赖问题。TsHttpUtil虽然依赖多个模块，但这种依赖关系是单向的，符合模块化设计原则。
章节来源
性能考虑
内存使用优化
- 流式处理：TsSM4算法采用分块处理方式，避免大内存占用
- 对象复用：在加密过程中重用Uint32Array对象，减少GC压力
- 延迟初始化：TsCrypto在首次使用时才初始化SM4实例
网络性能优化
- 请求合并：TsHttpUtil支持将额外参数合并到请求中，减少请求次数
- 缓存策略：结合localStorage实现数据缓存，减少重复请求
- 异步处理：所有网络请求都采用Promise异步处理，避免阻塞主线程
加密性能优化
- 轮转密钥：TsSM4算法预先计算轮转密钥，避免重复计算
- 位运算优化：大量使用位运算替代乘除法，提高执行效率
- 内存对齐：使用TypedArray确保内存对齐，提升访问速度
故障排除指南
常见问题及解决方案
加密相关问题
问题：加密后数据无法正确解密
- 原因：密钥不匹配或加密模式不一致
- 解决方案：检查TsGlobalConfig中的base64Key配置，确认加密模式设置
问题：Base64编码异常
- 原因：输入数据包含特殊字符
- 解决方案：使用TsCommon.parseJSON进行安全解析
HTTP请求问题
问题：请求超时或失败
- 原因：umi-request配置问题或网络异常
- 解决方案：检查TsGlobalConfig中的prefix配置，确认网络连接状态
问题：响应数据格式异常
- 原因：服务器返回格式不符合预期
- 解决方案：检查TsHttpUtil的响应处理逻辑，添加适当的错误处理
存储相关问题
问题：localStorage存储失败
- 原因：浏览器隐私模式或存储空间不足
- 解决方案：添加存储容量检查和降级方案
章节来源
结论
npm-tool 工具包通过精心设计的模块化架构，为前端开发提供了完整的基础设施支持。其核心优势包括：
技术优势
- 模块化设计：每个模块职责单一，便于维护和扩展
- 安全性保障：内置SM4加密算法，提供企业级数据保护
- 易用性：提供简洁的API接口，降低学习成本
- 可配置性：通过全局配置系统支持灵活的运行时调整
架构决策
- 分层架构：从底层工具函数到上层业务封装，层次清晰
- 依赖注入：通过构造函数注入依赖，提高模块独立性
- 配置驱动：将可变因素抽象为配置，增强系统灵活性
- 错误处理：统一的错误处理机制，提升系统稳定性
最佳实践建议
- 模块组合使用：建议按照TsHttpUtil → TsCrypto → TsSM4的顺序使用加密功能
- 配置管理：通过TsGlobalConfig集中管理所有可配置项
- 错误处理：在业务层添加适当的错误处理和用户反馈
- 性能监控：定期监控加密和网络请求的性能指标
该工具包为前端开发提供了一个可靠、安全、易用的基础框架，适合在企业级应用中使用。