937 lines
24 KiB
Markdown
937 lines
24 KiB
Markdown
# 通用工具 API
|
||
|
||
<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)
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
|
||
这是一个功能丰富的 JavaScript 工具包，提供了多种实用的工具函数和组件，主要用于 Web 应用开发中的常见需求。该工具包包含了字符串处理、数据类型检查、URL 操作、加密解密、存储管理、HTTP 请求等功能模块。
|
||
|
||
主要特性：
|
||
- **字符串处理工具**：URL 参数解析、空值判断、JSON 解析、字符串替换、结尾判断等
|
||
- **加密解密功能**：基于 SM4 算法的加密解密工具
|
||
- **存储管理**：本地存储封装，支持对象序列化
|
||
- **HTTP 请求工具**：基于 umi-request 的网络请求封装
|
||
- **全局配置管理**：统一的配置管理和环境检测
|
||
|
||
## 项目结构
|
||
|
||
该项目采用模块化的组织方式，主要分为以下目录结构：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "项目根目录"
|
||
Root[index.js<br/>主入口文件]
|
||
Package[package.json<br/>项目配置]
|
||
Readme[README.md<br/>使用说明]
|
||
end
|
||
subgraph "src/ 工具源码目录"
|
||
Utils[src/utils/<br/>通用工具模块]
|
||
Https[src/https/<br/>HTTP 工具模块]
|
||
end
|
||
subgraph "Utils 模块"
|
||
Common[TsCommon.js<br/>通用工具]
|
||
Crypto[TsCrypto.js<br/>加密工具]
|
||
SM4[TsSM4.js<br/>SM4 算法实现]
|
||
Storage[TsStorage.js<br/>存储工具]
|
||
Config[TsGlobalConfig.js<br/>全局配置]
|
||
end
|
||
subgraph "Https 模块"
|
||
HttpUtil[TsHttpUtil.js<br/>HTTP 请求工具]
|
||
end
|
||
Root --> Utils
|
||
Root --> Https
|
||
Utils --> Common
|
||
Utils --> Crypto
|
||
Utils --> SM4
|
||
Utils --> Storage
|
||
Utils --> Config
|
||
Https --> HttpUtil
|
||
```
|
||
|
||
**图表来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||
- [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)
|
||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||
|
||
**章节来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [package.json:1-24](file://package.json#L1-L24)
|
||
|
||
## 核心组件
|
||
|
||
该工具包的核心由六个主要模块组成，每个模块都提供特定的功能领域：
|
||
|
||
### 主要模块概览
|
||
|
||
| 模块名称 | 文件路径 | 功能描述 |
|
||
|---------|----------|----------|
|
||
| TsCommon | src/utils/TsCommon.js | 通用工具函数集合 |
|
||
| TsCrypto | src/utils/TsCrypto.js | 加密解密工具 |
|
||
| TsSM4 | src/utils/TsSM4.js | SM4 算法实现 |
|
||
| TsStorage | src/utils/TsStorage.js | 本地存储管理 |
|
||
| TsGlobalConfig | src/utils/TsGlobalConfig.js | 全局配置管理 |
|
||
| TsHttpUtil | src/https/TsHttpUtil.js | HTTP 请求封装 |
|
||
|
||
### 模块依赖关系
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "外部依赖"
|
||
Umi[umi-request<br/>网络请求库]
|
||
Base64[base64-js<br/>Base64 编解码]
|
||
end
|
||
subgraph "内部模块"
|
||
Common[TsCommon]
|
||
Crypto[TsCrypto]
|
||
SM4[TsSM4]
|
||
Storage[TsStorage]
|
||
Config[TsGlobalConfig]
|
||
HttpUtil[TsHttpUtil]
|
||
end
|
||
HttpUtil --> Storage
|
||
HttpUtil --> Common
|
||
HttpUtil --> Crypto
|
||
HttpUtil --> Config
|
||
Crypto --> SM4
|
||
Crypto --> Config
|
||
Storage --> Common
|
||
SM4 --> Base64
|
||
HttpUtil --> Umi
|
||
```
|
||
|
||
**图表来源**
|
||
- [package.json:19-22](file://package.json#L19-L22)
|
||
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
|
||
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
|
||
|
||
**章节来源**
|
||
- [package.json:19-22](file://package.json#L19-L22)
|
||
- [index.js:8-15](file://index.js#L8-L15)
|
||
|
||
## 架构概览
|
||
|
||
该工具包采用了分层架构设计，将不同功能领域的工具函数分离到独立的模块中，通过清晰的依赖关系实现松耦合的设计。
|
||
|
||
### 整体架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "应用层"
|
||
App[业务应用]
|
||
end
|
||
subgraph "工具层"
|
||
HttpLayer[HTTP 层<br/>TsHttpUtil]
|
||
CryptoLayer[加密层<br/>TsCrypto + TsSM4]
|
||
StorageLayer[存储层<br/>TsStorage]
|
||
CommonLayer[通用层<br/>TsCommon]
|
||
end
|
||
subgraph "基础设施层"
|
||
Network[umi-request]
|
||
CryptoLib[SM4 算法]
|
||
StorageAPI[localStorage]
|
||
Encoding[base64-js]
|
||
end
|
||
App --> HttpLayer
|
||
HttpLayer --> CryptoLayer
|
||
HttpLayer --> StorageLayer
|
||
HttpLayer --> CommonLayer
|
||
CryptoLayer --> CryptoLib
|
||
CryptoLayer --> Encoding
|
||
StorageLayer --> StorageAPI
|
||
HttpLayer --> Network
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||
|
||
### 数据流处理流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as 应用客户端
|
||
participant HttpUtil as HTTP 工具
|
||
participant Crypto as 加密模块
|
||
participant Storage as 存储模块
|
||
participant Server as 服务器
|
||
Client->>HttpUtil : 发送请求
|
||
HttpUtil->>Storage : 获取用户令牌
|
||
Storage-->>HttpUtil : 返回令牌
|
||
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:13-15](file://src/utils/TsStorage.js#L13-L15)
|
||
|
||
## 详细组件分析
|
||
|
||
### TsCommon 通用工具模块
|
||
|
||
TsCommon 模块提供了基础的工具函数，涵盖了字符串处理、数据类型检查、URL 操作等多个方面。
|
||
|
||
#### 核心 API 接口
|
||
|
||
##### getParamFormUrl - URL 参数解析
|
||
|
||
**方法签名**: `getParamFormUrl(key, host)`
|
||
|
||
**参数说明**:
|
||
- `key`: string - 要获取的 URL 参数键名
|
||
- `host`: string (可选) - 目标 URL 字符串，默认使用当前页面 URL
|
||
|
||
**返回值**: string - 匹配参数的值，未找到时返回空字符串
|
||
|
||
**使用场景**:
|
||
- 从 URL 中提取查询参数
|
||
- 处理页面分享链接中的参数
|
||
- 解析路由参数
|
||
|
||
**参数验证规则**:
|
||
- 支持任意字符串作为参数键
|
||
- host 参数可选，不传入时使用当前页面 URL
|
||
|
||
**边界条件处理**:
|
||
- URL 中无问号或无查询参数时返回空字符串
|
||
- 参数值包含特殊字符时自动解码
|
||
- URL 格式不正确时捕获异常并返回空字符串
|
||
|
||
##### isEmpty - 空值判断
|
||
|
||
**方法签名**: `isEmpty(value)`
|
||
|
||
**参数说明**:
|
||
- `value`: any - 要检查的值
|
||
|
||
**返回值**: boolean - 值为 undefined、null 或空字符串时返回 true
|
||
|
||
**使用场景**:
|
||
- 表单验证
|
||
- 数据预处理
|
||
- 条件判断
|
||
|
||
**参数验证规则**:
|
||
- 接受任意类型的参数
|
||
- 严格比较空值类型
|
||
|
||
##### parseJSON - JSON 解析
|
||
|
||
**方法签名**: `parseJSON(value, def)`
|
||
|
||
**参数说明**:
|
||
- `value`: string - 要解析的 JSON 字符串
|
||
- `def`: any (可选) - 默认返回值，默认为空对象 {}
|
||
|
||
**返回值**: any - 解析后的对象或默认值
|
||
|
||
**使用场景**:
|
||
- 安全地解析 JSON 字符串
|
||
- 处理可能损坏的 JSON 数据
|
||
- 提供默认值机制
|
||
|
||
**参数验证规则**:
|
||
- 第二个参数为可选，默认值为空对象
|
||
- 解析失败时返回默认值
|
||
|
||
**边界条件处理**:
|
||
- JSON 格式错误时捕获异常
|
||
- 解析结果为空时使用默认值
|
||
|
||
##### split - 字符串分割
|
||
|
||
**方法签名**: `split(obj, seq)`
|
||
|
||
**参数说明**:
|
||
- `obj`: string - 要分割的字符串
|
||
- `seq`: string (可选) - 分隔符，默认为逗号
|
||
|
||
**返回值**: string[] - 分割后的字符串数组
|
||
|
||
**使用场景**:
|
||
- 处理逗号分隔的列表
|
||
- 解析配置字符串
|
||
- 数据格式转换
|
||
|
||
**参数验证规则**:
|
||
- 支持任意字符串作为输入
|
||
- 分隔符可自定义
|
||
|
||
**边界条件处理**:
|
||
- 输入为 falsy 值时返回空数组
|
||
- 空字符串返回包含空字符串的数组
|
||
|
||
##### isDevelopment - 环境检测
|
||
|
||
**方法签名**: `isDevelopment()`
|
||
|
||
**参数说明**: 无
|
||
|
||
**返回值**: boolean - 当前环境为 development 时返回 true
|
||
|
||
**使用场景**:
|
||
- 开发模式下的调试输出
|
||
- 环境相关的功能开关
|
||
- 测试环境配置
|
||
|
||
**参数验证规则**:
|
||
- 依赖 Node.js 的环境变量
|
||
|
||
##### replaceAll - 全部替换
|
||
|
||
**方法签名**: `replaceAll(string, s1, s2)`
|
||
|
||
**参数说明**:
|
||
- `string`: string - 原始字符串
|
||
- `s1`: string - 要替换的子字符串
|
||
- `s2`: string - 替换后的字符串
|
||
|
||
**返回值**: string - 替换后的字符串
|
||
|
||
**使用场景**:
|
||
- 批量字符串替换
|
||
- 文本格式化
|
||
- 数据清洗
|
||
|
||
**参数验证规则**:
|
||
- 支持正则表达式的特殊字符
|
||
- 使用全局标志进行完全替换
|
||
|
||
##### endWith - 结尾判断
|
||
|
||
**方法签名**: `endWith(string, endStr)`
|
||
|
||
**参数说明**:
|
||
- `string`: string - 要检查的字符串
|
||
- `endStr`: string - 结尾字符串
|
||
|
||
**返回值**: boolean - 字符串以指定结尾时返回 true
|
||
|
||
**使用场景**:
|
||
- 文件扩展名检查
|
||
- URL 路径处理
|
||
- 字符串格式验证
|
||
|
||
**参数验证规则**:
|
||
- 支持空字符串作为输入
|
||
- 不区分大小写
|
||
|
||
**章节来源**
|
||
- [TsCommon.js:4-18](file://src/utils/TsCommon.js#L4-L18)
|
||
- [TsCommon.js:25-27](file://src/utils/TsCommon.js#L25-L27)
|
||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||
- [TsCommon.js:51-56](file://src/utils/TsCommon.js#L51-L56)
|
||
- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)
|
||
- [TsCommon.js:74-76](file://src/utils/TsCommon.js#L74-L76)
|
||
- [TsCommon.js:84-87](file://src/utils/TsCommon.js#L84-L87)
|
||
|
||
### TsCrypto 加密工具模块
|
||
|
||
TsCrypto 模块提供了基于 SM4 算法的加密解密功能，封装了底层的加密细节。
|
||
|
||
#### 核心 API 接口
|
||
|
||
##### 构造函数
|
||
|
||
**方法签名**: `new TsCrypto()`
|
||
|
||
**参数说明**: 无
|
||
|
||
**初始化过程**:
|
||
- 从全局配置获取 Base64 密钥
|
||
- 创建 SM4 实例（ECB 模式）
|
||
- 设置密文类型为 Base64
|
||
|
||
##### encrypt - 数据加密
|
||
|
||
**方法签名**: `encrypt(content)`
|
||
|
||
**参数说明**:
|
||
- `content`: string | any - 要加密的内容
|
||
|
||
**返回值**: string - 加密后的 Base64 字符串
|
||
|
||
**使用场景**:
|
||
- 敏感数据传输加密
|
||
- API 请求体加密
|
||
- 数据安全存储
|
||
|
||
**参数验证规则**:
|
||
- 自动将非字符串内容转换为 JSON 字符串
|
||
- 依赖 SM4 算法进行加密
|
||
|
||
##### decrypt - 数据解密
|
||
|
||
**方法签名**: `decrypt(base64)`
|
||
|
||
**参数说明**:
|
||
- `base64`: string - Base64 编码的密文
|
||
|
||
**返回值**: string - 解密后的原始内容
|
||
|
||
**使用场景**:
|
||
- 解密服务器返回的加密数据
|
||
- 数据恢复和验证
|
||
- 安全通信
|
||
|
||
**参数验证规则**:
|
||
- 接收 Base64 编码的密文
|
||
- 返回原始明文内容
|
||
|
||
**章节来源**
|
||
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
|
||
|
||
### TsSM4 SM4 算法实现
|
||
|
||
TsSM4 是一个完整的 SM4 对称加密算法实现，支持 ECB 和 CBC 两种工作模式。
|
||
|
||
#### 核心 API 接口
|
||
|
||
##### 构造函数
|
||
|
||
**方法签名**: `new TsSM4(config)`
|
||
|
||
**参数说明**:
|
||
- `config`: object - 配置对象
|
||
- `keyBuffer`: Uint8Array - 16 字节密钥缓冲区
|
||
- `mode`: string - 加密模式，'cbc' 或 'ecb'，默认 'cbc'
|
||
- `outType`: string - 输出类型，'base64' 或 'text'，默认 'base64'
|
||
|
||
**参数验证规则**:
|
||
- 密钥长度必须为 16 字节
|
||
- IV（初始化向量）长度必须为 16 字节（CBC 模式）
|
||
- 支持的模式：'cbc'、'ecb'
|
||
- 支持的输出类型：'base64'、'text'
|
||
|
||
##### encrypt - 数据加密
|
||
|
||
**方法签名**: `encrypt(plaintext)`
|
||
|
||
**参数说明**:
|
||
- `plaintext`: string - 要加密的明文
|
||
|
||
**返回值**: string - 加密后的密文
|
||
|
||
**使用场景**:
|
||
- 数据加密传输
|
||
- 密钥生成和管理
|
||
- 安全通信协议
|
||
|
||
**参数验证规则**:
|
||
- 自动进行 PKCS#7 填充
|
||
- 支持 UTF-8 编码
|
||
- 根据模式选择加密算法
|
||
|
||
##### decrypt - 数据解密
|
||
|
||
**方法签名**: `decrypt(ciphertext)`
|
||
|
||
**参数说明**:
|
||
- `ciphertext`: string - 要解密的密文
|
||
|
||
**返回值**: string - 解密后的明文
|
||
|
||
**使用场景**:
|
||
- 数据解密和验证
|
||
- 安全通信解码
|
||
- 数据恢复
|
||
|
||
**参数验证规则**:
|
||
- 支持 Base64 和文本两种输入格式
|
||
- 自动移除 PKCS#7 填充
|
||
- 支持 UTF-8 编码
|
||
|
||
#### SM4 算法流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([开始加密]) --> Prepare["准备明文字节流<br/>UTF-8 编码"]
|
||
Prepare --> Padding["PKCS#7 填充<br/>16 字节对齐"]
|
||
Padding --> Mode{"选择模式"}
|
||
Mode --> |CBC| CBCInit["CBC 模式初始化<br/>IV = 16 字节"]
|
||
Mode --> |ECB| ECBInit["ECB 模式初始化<br/>无 IV"]
|
||
CBCInit --> BlockLoop["按块处理<br/>16 字节/块"]
|
||
ECBInit --> BlockLoop
|
||
BlockLoop --> XOR["与前一块密文异或<br/>(CBC)"]
|
||
XOR --> Round["32 轮加密循环"]
|
||
Round --> Output["输出密文字节流"]
|
||
Output --> Type{"输出类型"}
|
||
Type --> |Base64| Base64["Base64 编码"]
|
||
Type --> |Text| Text["UTF-8 解码"]
|
||
Base64 --> End([结束])
|
||
Text --> End
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||
- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
|
||
|
||
**章节来源**
|
||
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
|
||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||
- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
|
||
|
||
### TsStorage 存储工具模块
|
||
|
||
TsStorage 模块提供了本地存储的封装，支持对象的序列化和反序列化。
|
||
|
||
#### 核心 API 接口
|
||
|
||
##### save - 保存数据
|
||
|
||
**方法签名**: `save(key, value)`
|
||
|
||
**参数说明**:
|
||
- `key`: string - 存储键名
|
||
- `value`: any - 要保存的值
|
||
|
||
**返回值**: void
|
||
|
||
**使用场景**:
|
||
- 用户偏好设置保存
|
||
- 临时数据缓存
|
||
- 应用状态持久化
|
||
|
||
**参数验证规则**:
|
||
- 键名必须为字符串
|
||
- 值会被 JSON 序列化
|
||
|
||
##### get - 获取数据
|
||
|
||
**方法签名**: `get(key, def)`
|
||
|
||
**参数说明**:
|
||
- `key`: string - 存储键名
|
||
- `def`: any (可选) - 默认返回值，默认为空字符串
|
||
|
||
**返回值**: any - 存储的值或默认值
|
||
|
||
**使用场景**:
|
||
- 用户数据读取
|
||
- 应用状态恢复
|
||
- 配置信息获取
|
||
|
||
**参数验证规则**:
|
||
- 键名必须为字符串
|
||
- 支持默认值机制
|
||
|
||
##### saveUserToken - 保存用户令牌
|
||
|
||
**方法签名**: `saveUserToken(token)`
|
||
|
||
**参数说明**:
|
||
- `token`: string - 用户令牌
|
||
|
||
**返回值**: void
|
||
|
||
**使用场景**:
|
||
- 用户登录状态管理
|
||
- 认证信息存储
|
||
- 会话管理
|
||
|
||
##### getUserToken - 获取用户令牌
|
||
|
||
**方法签名**: `getUserToken()`
|
||
|
||
**参数说明**: 无
|
||
|
||
**返回值**: string - 用户令牌或空字符串
|
||
|
||
**使用场景**:
|
||
- 请求头认证
|
||
- 用户状态检查
|
||
- 权限验证
|
||
|
||
##### saveEncryptBody - 设置加密开关
|
||
|
||
**方法签名**: `saveEncryptBody(bool)`
|
||
|
||
**参数说明**:
|
||
- `bool`: boolean - 加密开关，默认 true
|
||
|
||
**返回值**: void
|
||
|
||
**使用场景**:
|
||
- 加密功能配置
|
||
- 安全策略设置
|
||
- 性能权衡
|
||
|
||
##### getEncryptBody - 获取加密开关
|
||
|
||
**方法签名**: `getEncryptBody()`
|
||
|
||
**参数说明**: 无
|
||
|
||
**返回值**: boolean - 加密开关状态
|
||
|
||
**使用场景**:
|
||
- 加密功能状态检查
|
||
- 请求前状态确认
|
||
- 安全策略验证
|
||
|
||
**章节来源**
|
||
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||
- [TsStorage.js:9-23](file://src/utils/TsStorage.js#L9-L23)
|
||
|
||
### TsGlobalConfig 全局配置模块
|
||
|
||
TsGlobalConfig 模块提供了统一的配置管理功能，支持运行时配置更新。
|
||
|
||
#### 核心 API 接口
|
||
|
||
##### getConfig - 获取配置
|
||
|
||
**方法签名**: `getConfig()`
|
||
|
||
**参数说明**: 无
|
||
|
||
**返回值**: object - 当前配置对象
|
||
|
||
**配置项说明**:
|
||
- `base64Key`: string - Base64 编码的密钥，默认值为 "WmdUzPJXbngVNiaSsQrihg=="
|
||
- `prefix`: string | function - API 前缀，可以是字符串或函数
|
||
- `onHttpError`: function - HTTP 错误回调函数
|
||
- `httpParams`: function - HTTP 参数处理器
|
||
|
||
##### setConfig - 设置配置
|
||
|
||
**方法签名**: `setConfig(obj)`
|
||
|
||
**参数说明**:
|
||
- `obj`: object - 要合并的配置对象
|
||
|
||
**返回值**: void
|
||
|
||
**使用场景**:
|
||
- 应用启动时的配置初始化
|
||
- 运行时配置动态更新
|
||
- 环境相关的配置切换
|
||
|
||
**参数验证规则**:
|
||
- 支持部分配置项的更新
|
||
- 使用对象合并的方式更新配置
|
||
|
||
**章节来源**
|
||
- [TsGlobalConfig.js:5-29](file://src/utils/TsGlobalConfig.js#L5-L29)
|
||
|
||
### TsHttpUtil HTTP 请求工具
|
||
|
||
TsHttpUtil 模块基于 umi-request 提供了增强的 HTTP 请求功能，集成了加密解密、参数处理、错误处理等功能。
|
||
|
||
#### 核心 API 接口
|
||
|
||
##### req - 通用请求方法
|
||
|
||
**方法签名**: `req(url, options)`
|
||
|
||
**参数说明**:
|
||
- `url`: string - 请求地址
|
||
- `options`: object - 请求选项
|
||
- `method`: string - HTTP 方法，默认 'GET'
|
||
- `params`: object - 查询参数
|
||
- `data`: object - 请求体数据
|
||
- `headers`: object - 请求头
|
||
- `rawResponse`: boolean - 是否返回原始响应
|
||
|
||
**返回值**: Promise<object> - 处理后的响应数据
|
||
|
||
**使用场景**:
|
||
- 统一的 HTTP 请求入口
|
||
- 复杂请求的参数处理
|
||
- 响应数据的统一格式化
|
||
|
||
##### get - GET 请求
|
||
|
||
**方法签名**: `get(url, params, options)`
|
||
|
||
**参数说明**:
|
||
- `url`: string - 请求地址
|
||
- `params`: object - 查询参数，默认 {}
|
||
- `options`: object - 请求选项，默认 {}
|
||
|
||
**返回值**: Promise<object> - 响应数据
|
||
|
||
**使用场景**:
|
||
- 数据获取请求
|
||
- 列表查询
|
||
- 资源读取
|
||
|
||
##### post - POST 请求
|
||
|
||
**方法签名**: `post(url, data, options)`
|
||
|
||
**参数说明**:
|
||
- `url`: string - 请求地址
|
||
- `data`: object - 请求体数据，默认 {}
|
||
- `options`: object - 请求选项，默认 {}
|
||
|
||
**返回值**: Promise<object> - 响应数据
|
||
|
||
**使用场景**:
|
||
- 数据创建
|
||
- 表单提交
|
||
- 资源更新
|
||
|
||
##### form - 表单提交
|
||
|
||
**方法签名**: `form(url, data, options)`
|
||
|
||
**参数说明**:
|
||
- `url`: string - 请求地址
|
||
- `data`: object - 表单数据，默认 {}
|
||
- `options`: object - 请求选项，默认 {}
|
||
|
||
**返回值**: Promise<object> - 响应数据
|
||
|
||
**使用场景**:
|
||
- 文件上传
|
||
- 表单数据提交
|
||
- 多部分数据传输
|
||
|
||
#### HTTP 请求处理流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as 客户端
|
||
participant HttpUtil as HTTP 工具
|
||
participant Config as 配置管理
|
||
participant Storage as 存储模块
|
||
participant Crypto as 加密模块
|
||
participant Request as 网络请求
|
||
Client->>HttpUtil : 发送请求
|
||
HttpUtil->>Config : 获取配置前缀
|
||
Config-->>HttpUtil : 返回前缀
|
||
HttpUtil->>HttpUtil : 处理分页参数
|
||
HttpUtil->>HttpUtil : 处理相等条件
|
||
HttpUtil->>Config : 获取额外参数
|
||
Config-->>HttpUtil : 返回额外参数
|
||
HttpUtil->>Storage : 获取用户令牌
|
||
Storage-->>HttpUtil : 返回令牌
|
||
HttpUtil->>Crypto : 加密请求体(可选)
|
||
Crypto-->>HttpUtil : 返回加密结果
|
||
HttpUtil->>Request : 发送网络请求
|
||
Request-->>HttpUtil : 返回响应
|
||
HttpUtil->>HttpUtil : 检查响应状态
|
||
HttpUtil->>Crypto : 解密响应(可选)
|
||
Crypto-->>HttpUtil : 返回解密结果
|
||
HttpUtil-->>Client : 返回处理后的数据
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
|
||
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
|
||
|
||
**章节来源**
|
||
- [TsHttpUtil.js:99-171](file://src/https/TsHttpUtil.js#L99-L171)
|
||
|
||
## 依赖分析
|
||
|
||
该工具包的依赖关系相对简单，主要依赖于两个外部库和内部模块间的协作。
|
||
|
||
### 外部依赖
|
||
|
||
| 依赖名称 | 版本 | 用途 |
|
||
|---------|------|------|
|
||
| base64-js | 1.5.1 | Base64 编解码 |
|
||
| umi-request | 1.4.0 | HTTP 请求封装 |
|
||
|
||
### 内部模块依赖
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "主入口"
|
||
Index[index.js]
|
||
end
|
||
subgraph "工具模块"
|
||
Common[TsCommon]
|
||
Crypto[TsCrypto]
|
||
SM4[TsSM4]
|
||
Storage[TsStorage]
|
||
Config[TsGlobalConfig]
|
||
end
|
||
subgraph "HTTP 模块"
|
||
HttpUtil[TsHttpUtil]
|
||
end
|
||
Index --> Common
|
||
Index --> Crypto
|
||
Index --> SM4
|
||
Index --> Storage
|
||
Index --> Config
|
||
Index --> HttpUtil
|
||
HttpUtil --> Storage
|
||
HttpUtil --> Common
|
||
HttpUtil --> Crypto
|
||
HttpUtil --> Config
|
||
Crypto --> SM4
|
||
Crypto --> Config
|
||
Storage --> Common
|
||
```
|
||
|
||
**图表来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
|
||
|
||
### 依赖关系分析
|
||
|
||
该工具包采用了清晰的模块化设计，各模块职责明确：
|
||
|
||
1. **TsCommon** 作为基础工具模块，被其他所有模块依赖
|
||
2. **TsCrypto** 依赖 **TsSM4** 和 **TsGlobalConfig** 进行加密操作
|
||
3. **TsStorage** 依赖 **TsCommon** 进行 JSON 解析
|
||
4. **TsHttpUtil** 依赖所有其他模块进行完整的 HTTP 请求处理
|
||
|
||
**章节来源**
|
||
- [package.json:19-22](file://package.json#L19-L22)
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
|
||
## 性能考虑
|
||
|
||
在使用该工具包时，需要考虑以下几个方面的性能影响：
|
||
|
||
### 字符串处理性能
|
||
|
||
- **URL 参数解析**: 使用正则表达式进行匹配，对于大量参数的 URL 可能影响性能
|
||
- **字符串替换**: `replaceAll` 使用全局正则表达式，复杂字符串可能影响性能
|
||
- **JSON 解析**: 大对象的序列化和反序列化可能成为性能瓶颈
|
||
|
||
### 加密解密性能
|
||
|
||
- **SM4 算法**: 32 轮加密循环，对于大文本加密会有明显的时间开销
|
||
- **Base64 编解码**: 大数据量的编码解码会影响性能
|
||
- **内存使用**: 加密解密过程中会产生中间缓冲区
|
||
|
||
### 存储性能
|
||
|
||
- **localStorage 操作**: 大对象序列化会影响存储性能
|
||
- **频繁读写**: 高频的存储操作可能影响页面响应性
|
||
|
||
### HTTP 请求优化
|
||
|
||
- **请求合并**: 合理设计 API 接口，避免不必要的请求
|
||
- **缓存策略**: 利用浏览器缓存减少重复请求
|
||
- **批量操作**: 将多个小请求合并为批量请求
|
||
|
||
## 故障排除指南
|
||
|
||
### 常见问题及解决方案
|
||
|
||
#### 1. 加密密钥错误
|
||
|
||
**问题症状**: 加密或解密时报错，提示密钥长度不正确
|
||
|
||
**解决方案**:
|
||
- 确保密钥长度为 16 字节
|
||
- 检查 Base64 编码是否正确
|
||
- 验证密钥格式符合要求
|
||
|
||
#### 2. URL 参数解析失败
|
||
|
||
**问题症状**: `getParamFormUrl` 返回空字符串
|
||
|
||
**解决方案**:
|
||
- 检查 URL 格式是否正确
|
||
- 确认参数键名拼写正确
|
||
- 验证 URL 中是否包含查询参数
|
||
|
||
#### 3. JSON 解析异常
|
||
|
||
**问题症状**: `parseJSON` 抛出异常或返回默认值
|
||
|
||
**解决方案**:
|
||
- 检查 JSON 字符串格式
|
||
- 验证字符编码是否正确
|
||
- 确认字符串不是 null 或 undefined
|
||
|
||
#### 4. HTTP 请求失败
|
||
|
||
**问题症状**: 网络请求返回错误状态
|
||
|
||
**解决方案**:
|
||
- 检查网络连接状态
|
||
- 验证 API 地址和参数
|
||
- 查看服务器响应状态码
|
||
- 检查跨域配置
|
||
|
||
#### 5. 存储数据丢失
|
||
|
||
**问题症状**: `get` 方法返回默认值而非预期数据
|
||
|
||
**解决方案**:
|
||
- 检查浏览器存储容量限制
|
||
- 验证键名是否一致
|
||
- 确认数据格式正确
|
||
- 检查浏览器隐私模式设置
|
||
|
||
### 调试技巧
|
||
|
||
1. **启用开发模式**: 使用 `isDevelopment()` 检测当前环境
|
||
2. **日志输出**: 在关键位置添加调试信息
|
||
3. **错误捕获**: 使用 try-catch 包装敏感操作
|
||
4. **单元测试**: 为关键函数编写测试用例
|
||
|
||
**章节来源**
|
||
- [TsSM4.js:103-122](file://src/utils/TsSM4.js#L103-L122)
|
||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
|
||
|
||
## 结论
|
||
|
||
该通用工具包提供了完整的 JavaScript 工具函数集合，具有以下特点：
|
||
|
||
### 优势
|
||
|
||
1. **模块化设计**: 清晰的功能划分，便于维护和扩展
|
||
2. **安全性**: 内置加密解密功能，支持敏感数据保护
|
||
3. **易用性**: 简洁的 API 设计，易于集成到现有项目
|
||
4. **完整性**: 覆盖了 Web 开发中的常见需求
|
||
|
||
### 使用建议
|
||
|
||
1. **合理选择加密模式**: 根据安全需求选择合适的加密算法和模式
|
||
2. **注意性能影响**: 大数据量处理时要考虑性能开销
|
||
3. **错误处理**: 建立完善的错误处理机制
|
||
4. **版本兼容**: 关注依赖库的版本更新和兼容性
|
||
|
||
### 扩展方向
|
||
|
||
1. **更多加密算法**: 可以添加 AES、RSA 等其他加密算法
|
||
2. **缓存机制**: 实现更高效的缓存策略
|
||
3. **监控功能**: 添加性能监控和错误追踪
|
||
4. **国际化支持**: 支持多语言错误消息
|
||
|
||
该工具包为 JavaScript 开发提供了坚实的基础工具集，能够有效提升开发效率和代码质量。 |