# 核心模块

<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. **性能监控**：定期监控加密和网络请求的性能指标

该工具包为前端开发提供了一个可靠、安全、易用的基础框架，适合在企业级应用中使用。