516 lines
16 KiB
Markdown
516 lines
16 KiB
Markdown
# 核心模块
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
|
||
npm-tool 是一个专为前端应用设计的综合性工具包，提供了网络请求、数据加密、存储管理、通用工具函数等核心功能。该工具包采用模块化设计，通过清晰的职责分离和接口抽象，为开发者提供了一套完整的前端开发基础设施。
|
||
|
||
本工具包的核心设计理念包括：
|
||
- **模块化架构**：每个功能模块独立封装，职责单一明确
|
||
- **可扩展性**：通过配置中心支持运行时配置调整
|
||
- **安全性**：内置SM4对称加密算法，保障数据传输安全
|
||
- **易用性**：提供简洁的API接口，降低使用复杂度
|
||
|
||
## 项目结构
|
||
|
||
项目采用按功能域组织的目录结构，主要分为以下层次：
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [package.json:1-24](file://package.json#L1-L24)
|
||
|
||
**章节来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [package.json:1-24](file://package.json#L1-L24)
|
||
|
||
## 核心组件
|
||
|
||
npm-tool 工具包由六个核心模块组成，每个模块都有明确的职责分工：
|
||
|
||
### 模块职责矩阵
|
||
|
||
| 模块名称 | 主要职责 | 关键功能 | 依赖关系 |
|
||
|---------|----------|----------|----------|
|
||
| TsCommon | 通用工具函数 | 字符串处理、类型判断、URL解析 | 无 |
|
||
| TsStorage | 数据持久化 | 本地存储、用户令牌管理 | TsCommon |
|
||
| TsSM4 | SM4加密算法 | 对称加密解密、密钥管理 | base64-js |
|
||
| TsCrypto | 加密服务层 | 加密解密接口、密钥转换 | TsSM4, TsGlobalConfig |
|
||
| TsGlobalConfig | 全局配置管理 | 配置读取设置、运行时配置 | 无 |
|
||
| TsHttpUtil | HTTP请求封装 | 网络请求、参数处理、错误处理 | umi-request |
|
||
|
||
**章节来源**
|
||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||
|
||
## 架构概览
|
||
|
||
工具包采用分层架构设计，从底层到上层依次为：基础工具层、加密服务层、存储管理层、HTTP请求层。
|
||
|
||
```mermaid
|
||
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](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)
|
||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||
|
||
## 详细组件分析
|
||
|
||
### TsCommon 通用工具模块
|
||
|
||
TsCommon 模块提供了一系列基础的工具函数，涵盖了字符串处理、类型判断、URL解析等常用功能。
|
||
|
||
#### 核心功能特性
|
||
|
||
```mermaid
|
||
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解析"
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||
|
||
#### 设计模式与实现要点
|
||
|
||
- **纯函数设计**：所有函数都是无状态的纯函数，便于测试和复用
|
||
- **容错处理**：对可能的异常情况进行了充分的try-catch处理
|
||
- **类型安全**：通过严格的参数验证确保函数的健壮性
|
||
|
||
**章节来源**
|
||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||
|
||
### TsStorage 存储模块
|
||
|
||
TsStorage 模块基于 localStorage 实现了数据持久化功能，特别针对用户令牌和配置信息进行了优化。
|
||
|
||
#### 数据存储策略
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsStorage.js:26-44](file://src/utils/TsStorage.js#L26-L44)
|
||
|
||
#### 特殊功能设计
|
||
|
||
- **用户令牌管理**：专门的token存储接口，简化了认证流程
|
||
- **加密开关控制**：支持动态启用/禁用数据加密
|
||
- **默认值处理**：提供灵活的默认值机制
|
||
|
||
**章节来源**
|
||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||
|
||
### TsSM4 加密算法模块
|
||
|
||
TsSM4 模块实现了国家商用密码标准 SM4 的完整算法，支持ECB和CBC两种加密模式。
|
||
|
||
#### SM4算法实现架构
|
||
|
||
```mermaid
|
||
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 : "使用"
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)
|
||
|
||
#### 加密算法特性
|
||
|
||
- **双模式支持**：同时支持ECB和CBC加密模式
|
||
- **密钥管理**：自动密钥扩展和轮转密钥生成
|
||
- **填充机制**：实现PKCS#7填充标准
|
||
- **编码转换**：支持Base64和文本两种输出格式
|
||
|
||
**章节来源**
|
||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||
|
||
### TsCrypto 加密服务模块
|
||
|
||
TsCrypto 作为加密服务层，提供了统一的加密解密接口，并与全局配置系统集成。
|
||
|
||
#### 加密服务架构
|
||
|
||
```mermaid
|
||
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 : 返回加密结果
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
|
||
|
||
#### 服务设计特点
|
||
|
||
- **配置驱动**：通过全局配置管理密钥和加密参数
|
||
- **接口统一**：提供简洁的加密解密API
|
||
- **依赖注入**：通过构造函数注入底层加密实现
|
||
|
||
**章节来源**
|
||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||
|
||
### TsGlobalConfig 全局配置模块
|
||
|
||
TsGlobalConfig 提供了全局配置管理功能，支持运行时配置更新和默认配置机制。
|
||
|
||
#### 配置管理流程
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsGlobalConfig.js:15-29](file://src/utils/TsGlobalConfig.js#L15-L29)
|
||
|
||
#### 配置系统设计
|
||
|
||
- **默认值机制**：提供完善的默认配置，确保系统稳定性
|
||
- **运行时更新**：支持在应用运行时动态更新配置
|
||
- **环境适配**：支持函数形式的动态配置生成
|
||
|
||
**章节来源**
|
||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||
|
||
### TsHttpUtil HTTP请求模块
|
||
|
||
TsHttpUtil 是工具包的核心模块，封装了网络请求的所有细节，提供了简洁易用的API。
|
||
|
||
#### HTTP请求处理流程
|
||
|
||
```mermaid
|
||
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}
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
|
||
|
||
#### 请求处理核心逻辑
|
||
|
||
- **参数预处理**：统一处理分页参数、equals条件等特殊需求
|
||
- **动态前缀**：支持根据URL动态生成API前缀
|
||
- **加密处理**：根据配置自动对请求体进行加密
|
||
- **响应解密**：自动解密服务器返回的加密数据
|
||
- **错误处理**：统一的错误处理和状态码映射
|
||
|
||
**章节来源**
|
||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||
|
||
## 依赖分析
|
||
|
||
工具包的依赖关系体现了清晰的分层架构和模块化设计原则。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [package.json:19-22](file://package.json#L19-L22)
|
||
- [index.js:1-6](file://index.js#L1-L6)
|
||
|
||
### 依赖关系分析
|
||
|
||
#### 直接依赖
|
||
- **umi-request**：HTTP请求库，提供网络通信能力
|
||
- **base64-js**：Base64编码解码工具
|
||
|
||
#### 间接依赖
|
||
- **TsHttpUtil** 依赖于所有其他模块，形成核心依赖环
|
||
- **TsCrypto** 依赖于TsSM4和TsGlobalConfig
|
||
- **TsStorage** 依赖于TsCommon
|
||
|
||
#### 循环依赖检测
|
||
该工具包采用了良好的模块化设计，避免了循环依赖问题。TsHttpUtil虽然依赖多个模块，但这种依赖关系是单向的，符合模块化设计原则。
|
||
|
||
**章节来源**
|
||
- [package.json:19-22](file://package.json#L19-L22)
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
|
||
## 性能考虑
|
||
|
||
### 内存使用优化
|
||
|
||
1. **流式处理**：TsSM4算法采用分块处理方式，避免大内存占用
|
||
2. **对象复用**：在加密过程中重用Uint32Array对象，减少GC压力
|
||
3. **延迟初始化**：TsCrypto在首次使用时才初始化SM4实例
|
||
|
||
### 网络性能优化
|
||
|
||
1. **请求合并**：TsHttpUtil支持将额外参数合并到请求中，减少请求次数
|
||
2. **缓存策略**：结合localStorage实现数据缓存，减少重复请求
|
||
3. **异步处理**：所有网络请求都采用Promise异步处理，避免阻塞主线程
|
||
|
||
### 加密性能优化
|
||
|
||
1. **轮转密钥**：TsSM4算法预先计算轮转密钥，避免重复计算
|
||
2. **位运算优化**：大量使用位运算替代乘除法，提高执行效率
|
||
3. **内存对齐**：使用TypedArray确保内存对齐，提升访问速度
|
||
|
||
## 故障排除指南
|
||
|
||
### 常见问题及解决方案
|
||
|
||
#### 加密相关问题
|
||
|
||
**问题**：加密后数据无法正确解密
|
||
- **原因**：密钥不匹配或加密模式不一致
|
||
- **解决方案**：检查TsGlobalConfig中的base64Key配置，确认加密模式设置
|
||
|
||
**问题**：Base64编码异常
|
||
- **原因**：输入数据包含特殊字符
|
||
- **解决方案**：使用TsCommon.parseJSON进行安全解析
|
||
|
||
#### HTTP请求问题
|
||
|
||
**问题**：请求超时或失败
|
||
- **原因**：umi-request配置问题或网络异常
|
||
- **解决方案**：检查TsGlobalConfig中的prefix配置，确认网络连接状态
|
||
|
||
**问题**：响应数据格式异常
|
||
- **原因**：服务器返回格式不符合预期
|
||
- **解决方案**：检查TsHttpUtil的响应处理逻辑，添加适当的错误处理
|
||
|
||
#### 存储相关问题
|
||
|
||
**问题**：localStorage存储失败
|
||
- **原因**：浏览器隐私模式或存储空间不足
|
||
- **解决方案**：添加存储容量检查和降级方案
|
||
|
||
**章节来源**
|
||
- [TsHttpUtil.js:25-35](file://src/https/TsHttpUtil.js#L25-L35)
|
||
- [TsCrypto.js:15-30](file://src/utils/TsCrypto.js#L15-L30)
|
||
- [TsStorage.js:26-44](file://src/utils/TsStorage.js#L26-L44)
|
||
|
||
## 结论
|
||
|
||
npm-tool 工具包通过精心设计的模块化架构，为前端开发提供了完整的基础设施支持。其核心优势包括：
|
||
|
||
### 技术优势
|
||
|
||
1. **模块化设计**：每个模块职责单一，便于维护和扩展
|
||
2. **安全性保障**：内置SM4加密算法，提供企业级数据保护
|
||
3. **易用性**：提供简洁的API接口，降低学习成本
|
||
4. **可配置性**：通过全局配置系统支持灵活的运行时调整
|
||
|
||
### 架构决策
|
||
|
||
1. **分层架构**：从底层工具函数到上层业务封装，层次清晰
|
||
2. **依赖注入**：通过构造函数注入依赖，提高模块独立性
|
||
3. **配置驱动**：将可变因素抽象为配置，增强系统灵活性
|
||
4. **错误处理**：统一的错误处理机制，提升系统稳定性
|
||
|
||
### 最佳实践建议
|
||
|
||
1. **模块组合使用**：建议按照TsHttpUtil → TsCrypto → TsSM4的顺序使用加密功能
|
||
2. **配置管理**：通过TsGlobalConfig集中管理所有可配置项
|
||
3. **错误处理**：在业务层添加适当的错误处理和用户反馈
|
||
4. **性能监控**：定期监控加密和网络请求的性能指标
|
||
|
||
该工具包为前端开发提供了一个可靠、安全、易用的基础框架，适合在企业级应用中使用。 |