docs(readme): 重构README并补充详细文档内容
This commit is contained in:
曾文豪
726
.qoder/repowiki/zh/content/核心模块/HTTP 请求模块 (TsHttpUtil).md
Normal file
726
.qoder/repowiki/zh/content/核心模块/HTTP 请求模块 (TsHttpUtil).md
Normal file
@@ -0,0 +1,726 @@
|
||||
# HTTP 请求模块 (TsHttpUtil)
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.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)
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
HTTP 请求模块 (TsHttpUtil) 是一个基于 umi-request 的网络请求封装库，提供了统一的 HTTP 请求接口，支持 GET、POST 和 FORM 请求方法。该模块集成了参数处理、错误处理、状态码映射、响应数据处理和加密传输等功能，为应用程序提供了一套完整的网络通信解决方案。
|
||||
|
||||
该模块的主要特点包括：
|
||||
- 基于 umi-request 的现代化请求封装
|
||||
- 智能的参数处理机制（分页器转换、equals 条件处理）
|
||||
- 统一的错误处理和状态码映射
|
||||
- 可选的 SM4 加密传输支持
|
||||
- 与存储模块、加密模块和配置模块的深度集成
|
||||
|
||||
## 项目结构
|
||||
|
||||
该项目采用模块化设计，将功能按职责划分为不同的模块：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心模块"
|
||||
Http[TsHttpUtil.js<br/>HTTP请求封装]
|
||||
Crypto[TsCrypto.js<br/>加密模块]
|
||||
SM4[TsSM4.js<br/>SM4算法实现]
|
||||
end
|
||||
subgraph "工具模块"
|
||||
Common[TsCommon.js<br/>通用工具函数]
|
||||
Storage[TsStorage.js<br/>存储模块]
|
||||
Config[TsGlobalConfig.js<br/>全局配置]
|
||||
end
|
||||
subgraph "外部依赖"
|
||||
UmiRequest[umi-request<br/>HTTP客户端]
|
||||
Base64[base64-js<br/>Base64编码]
|
||||
end
|
||||
Http --> UmiRequest
|
||||
Http --> Storage
|
||||
Http --> Common
|
||||
Http --> Crypto
|
||||
Http --> Config
|
||||
Crypto --> SM4
|
||||
Crypto --> Base64
|
||||
Crypto --> Config
|
||||
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)
|
||||
|
||||
**章节来源**
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 主要导出接口
|
||||
|
||||
TsHttpUtil 模块提供了四个主要的 HTTP 请求方法：
|
||||
|
||||
1. **req()** - 通用请求方法，支持所有 HTTP 方法
|
||||
2. **get()** - GET 请求方法
|
||||
3. **post()** - POST 请求方法（JSON 格式）
|
||||
4. **form()** - 表单提交方法（application/x-www-form-urlencoded）
|
||||
|
||||
### 错误处理机制
|
||||
|
||||
模块内置了完善的错误处理系统：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Request[发起请求] --> Response{收到响应}
|
||||
Response --> |成功| CheckCode{状态码检查}
|
||||
Response --> |失败| ErrorHandler[错误处理器]
|
||||
CheckCode --> |200| ParseData[解析响应数据]
|
||||
CheckCode --> |其他| HttpError[HTTP错误处理]
|
||||
ParseData --> EncryptCheck{需要解密?}
|
||||
EncryptCheck --> |是| Decrypt[解密数据]
|
||||
EncryptCheck --> |否| ReturnData[返回数据]
|
||||
Decrypt --> ReturnData
|
||||
HttpError --> OnError[调用onHttpError回调]
|
||||
OnError --> Reject[拒绝Promise]
|
||||
ErrorHandler --> ReturnError[返回标准错误对象]
|
||||
ReturnError --> Reject
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsHttpUtil.js:25-35](file://src/https/TsHttpUtil.js#L25-L35)
|
||||
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
|
||||
|
||||
**章节来源**
|
||||
- [TsHttpUtil.js:7-23](file://src/https/TsHttpUtil.js#L7-L23)
|
||||
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
|
||||
|
||||
## 架构概览
|
||||
|
||||
### 整体架构设计
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "应用层"
|
||||
Client[业务代码]
|
||||
end
|
||||
subgraph "HTTP层"
|
||||
TsHttpUtil[TsHttpUtil]
|
||||
Request[umi-request]
|
||||
end
|
||||
subgraph "数据处理层"
|
||||
ParamsHandler[参数处理器]
|
||||
ResponseHandler[响应处理器]
|
||||
end
|
||||
subgraph "安全层"
|
||||
Crypto[加密模块]
|
||||
Storage[存储模块]
|
||||
end
|
||||
subgraph "配置层"
|
||||
GlobalConfig[全局配置]
|
||||
SM4[SM4算法]
|
||||
end
|
||||
Client --> TsHttpUtil
|
||||
TsHttpUtil --> Request
|
||||
TsHttpUtil --> ParamsHandler
|
||||
TsHttpUtil --> ResponseHandler
|
||||
ParamsHandler --> Storage
|
||||
ResponseHandler --> Crypto
|
||||
Crypto --> SM4
|
||||
TsHttpUtil --> GlobalConfig
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||||
|
||||
### 数据流处理流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端
|
||||
participant HttpUtil as TsHttpUtil
|
||||
participant ParamsHandler as 参数处理器
|
||||
participant Crypto as 加密模块
|
||||
participant Request as umi-request
|
||||
participant Server as 服务器
|
||||
Client->>HttpUtil : 发起请求
|
||||
HttpUtil->>ParamsHandler : 处理参数
|
||||
ParamsHandler->>ParamsHandler : 分页器转换
|
||||
ParamsHandler->>ParamsHandler : equals条件处理
|
||||
ParamsHandler->>ParamsHandler : 添加额外参数
|
||||
alt 需要加密
|
||||
ParamsHandler->>Crypto : 加密数据
|
||||
Crypto->>Crypto : SM4加密
|
||||
Crypto-->>ParamsHandler : 返回加密数据
|
||||
end
|
||||
ParamsHandler-->>HttpUtil : 返回处理后的参数
|
||||
HttpUtil->>Request : 发送HTTP请求
|
||||
Request->>Server : HTTP请求
|
||||
Server-->>Request : HTTP响应
|
||||
Request-->>HttpUtil : 响应数据
|
||||
alt 响应需要解密
|
||||
HttpUtil->>Crypto : 解密响应
|
||||
Crypto->>Crypto : SM4解密
|
||||
Crypto-->>HttpUtil : 返回明文数据
|
||||
end
|
||||
HttpUtil-->>Client : 返回处理后的数据
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsHttpUtil.js:46-91](file://src/https/TsHttpUtil.js#L46-L91)
|
||||
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 参数处理机制
|
||||
|
||||
#### 分页器转换
|
||||
|
||||
模块支持智能的分页器参数转换：
|
||||
|
||||
| 输入参数 | 输出参数 |
|
||||
|---------|---------|
|
||||
| pagination.pageSize | pageSize |
|
||||
| pagination.current | pageNum |
|
||||
| pagination | 删除 |
|
||||
|
||||
#### equals 条件处理
|
||||
|
||||
equals 对象会被转换为逗号分隔的字符串：
|
||||
|
||||
```javascript
|
||||
// 输入
|
||||
{ equals: { id: 1, name: 'test' } }
|
||||
|
||||
// 输出
|
||||
{ equals: "id=1,name=test" }
|
||||
```
|
||||
|
||||
#### 额外参数添加
|
||||
|
||||
根据请求类型自动添加额外参数：
|
||||
|
||||
- **GET 请求**: 合并到 `params` 对象
|
||||
- **POST 请求**: 合并到 `data` 对象
|
||||
- **表单请求**: 合并到 `data` 对象
|
||||
|
||||
**章节来源**
|
||||
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
|
||||
|
||||
### 加密传输支持
|
||||
|
||||
#### 加密配置
|
||||
|
||||
加密功能通过全局配置启用：
|
||||
|
||||
```javascript
|
||||
// 启用加密
|
||||
TsGlobalConfig.setConfig({
|
||||
encryptBody: true,
|
||||
base64Key: "your-base64-key"
|
||||
});
|
||||
```
|
||||
|
||||
#### 加密流程
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Plain[明文数据] --> JSON[JSON序列化]
|
||||
JSON --> SM4[SM4加密]
|
||||
SM4 --> Base64[Base64编码]
|
||||
Base64 --> Encrypted[加密数据]
|
||||
Encrypted --> Send[发送到服务器]
|
||||
Send --> Receive[接收响应]
|
||||
Receive --> Decrypt[SM4解密]
|
||||
Decrypt --> Parse[JSON解析]
|
||||
Parse --> Plain
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsCrypto.js:15-30](file://src/utils/TsCrypto.js#L15-L30)
|
||||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
|
||||
**章节来源**
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)
|
||||
|
||||
### 错误处理策略
|
||||
|
||||
#### 状态码映射
|
||||
|
||||
模块内置了常用 HTTP 状态码的中文描述：
|
||||
|
||||
| 状态码 | 描述 |
|
||||
|-------|------|
|
||||
| 200 | 服务器成功返回请求的数据 |
|
||||
| 201 | 新建或修改数据成功 |
|
||||
| 202 | 一个请求已经进入后台排队（异步任务） |
|
||||
| 204 | 删除数据成功 |
|
||||
| 400 | 发出的请求有错误，服务器没有进行新建或修改数据的操作 |
|
||||
| 401 | 用户没有权限（令牌、用户名、密码错误） |
|
||||
| 403 | 用户得到授权，但是访问是被禁止的 |
|
||||
| 404 | 发出的请求针对的是不存在的记录，服务器没有进行操作 |
|
||||
| 406 | 请求的格式不可得 |
|
||||
| 410 | 请求的资源被永久删除，且不会再得到的 |
|
||||
| 422 | 当创建一个对象时，发生一个验证错误 |
|
||||
| 500 | 服务器发生错误，请检查服务器 |
|
||||
| 502 | 网关错误 |
|
||||
| 503 | 服务不可用，服务器暂时过载或维护 |
|
||||
| 504 | 网关超时 |
|
||||
|
||||
#### 错误处理流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start[请求开始] --> TryRequest[尝试请求]
|
||||
TryRequest --> Success{请求成功?}
|
||||
Success --> |是| CheckStatus{状态码检查}
|
||||
Success --> |否| NetworkError[网络错误处理]
|
||||
CheckStatus --> Status200{状态码=200?}
|
||||
Status200 --> |是| ParseResponse[解析响应]
|
||||
Status200 --> |否| HttpError[HTTP错误处理]
|
||||
ParseResponse --> EncryptCheck{需要解密?}
|
||||
EncryptCheck --> |是| Decrypt[解密数据]
|
||||
EncryptCheck --> |否| ReturnSuccess[返回成功结果]
|
||||
Decrypt --> ReturnSuccess
|
||||
HttpError --> CallCallback[调用onHttpError回调]
|
||||
CallCallback --> ReturnError[返回错误对象]
|
||||
NetworkError --> ReturnError
|
||||
ReturnSuccess --> End[请求结束]
|
||||
ReturnError --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsHttpUtil.js:7-23](file://src/https/TsHttpUtil.js#L7-L23)
|
||||
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
|
||||
- [TsHttpUtil.js:117-128](file://src/https/TsHttpUtil.js#L117-L128)
|
||||
|
||||
**章节来源**
|
||||
- [TsHttpUtil.js:7-23](file://src/https/TsHttpUtil.js#L7-L23)
|
||||
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
|
||||
|
||||
### API 接口说明
|
||||
|
||||
#### get() 方法
|
||||
|
||||
**方法签名**
|
||||
```javascript
|
||||
async function get(url, params = {}, options = {})
|
||||
```
|
||||
|
||||
**参数说明**
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|
||||
|-------|------|------|--------|------|
|
||||
| url | string | 是 | - | 请求的URL地址 |
|
||||
| params | object | 否 | {} | GET请求参数 |
|
||||
| options | object | 否 | {} | 请求选项 |
|
||||
|
||||
**返回值**
|
||||
```javascript
|
||||
{
|
||||
data: any, // 响应数据
|
||||
recordsTotal: number // 总记录数
|
||||
}
|
||||
```
|
||||
|
||||
**使用示例**
|
||||
```javascript
|
||||
// 基本使用
|
||||
const result = await HttpUtil.get('/api/users');
|
||||
|
||||
// 带参数使用
|
||||
const result = await HttpUtil.get('/api/users', {
|
||||
page: 1,
|
||||
size: 10,
|
||||
name: '张三'
|
||||
});
|
||||
|
||||
// 自定义选项
|
||||
const result = await HttpUtil.get('/api/users', {}, {
|
||||
timeout: 5000,
|
||||
headers: {'Authorization': 'Bearer token'}
|
||||
});
|
||||
```
|
||||
|
||||
#### post() 方法
|
||||
|
||||
**方法签名**
|
||||
```javascript
|
||||
async function post(url, data = {}, options = {})
|
||||
```
|
||||
|
||||
**参数说明**
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|
||||
|-------|------|------|--------|------|
|
||||
| url | string | 是 | - | 请求的URL地址 |
|
||||
| data | object | 否 | {} | POST请求数据 |
|
||||
| options | object | 否 | {} | 请求选项 |
|
||||
|
||||
**返回值**
|
||||
```javascript
|
||||
{
|
||||
data: any, // 响应数据
|
||||
recordsTotal: number // 总记录数
|
||||
}
|
||||
```
|
||||
|
||||
**使用示例**
|
||||
```javascript
|
||||
// 基本使用
|
||||
const result = await HttpUtil.post('/api/users', {
|
||||
name: '张三',
|
||||
age: 25
|
||||
});
|
||||
|
||||
// 表单数据
|
||||
const result = await HttpUtil.post('/api/login', {
|
||||
username: 'admin',
|
||||
password: 'password'
|
||||
}, {
|
||||
requestType: 'form'
|
||||
});
|
||||
```
|
||||
|
||||
#### form() 方法
|
||||
|
||||
**方法签名**
|
||||
```javascript
|
||||
async function form(url, data = {}, options = {})
|
||||
```
|
||||
|
||||
**参数说明**
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|
||||
|-------|------|------|--------|------|
|
||||
| url | string | 是 | - | 请求的URL地址 |
|
||||
| data | object | 否 | {} | 表单数据 |
|
||||
| options | object | 否 | {} | 请求选项 |
|
||||
|
||||
**返回值**
|
||||
```javascript
|
||||
{
|
||||
data: any, // 响应数据
|
||||
recordsTotal: number // 总记录数
|
||||
}
|
||||
```
|
||||
|
||||
**使用示例**
|
||||
```javascript
|
||||
// 表单提交
|
||||
const result = await HttpUtil.form('/api/upload', {
|
||||
file: fileInput.files[0],
|
||||
description: '文件描述'
|
||||
});
|
||||
```
|
||||
|
||||
#### req() 方法
|
||||
|
||||
**方法签名**
|
||||
```javascript
|
||||
async function req(url, options)
|
||||
```
|
||||
|
||||
**参数说明**
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|
||||
|-------|------|------|--------|------|
|
||||
| url | string | 是 | - | 请求的URL地址 |
|
||||
| options | object | 是 | {} | 请求选项 |
|
||||
|
||||
**请求选项参数**
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|
||||
|-------|------|------|--------|------|
|
||||
| method | string | 否 | 'GET' | HTTP方法 |
|
||||
| params | object | 否 | {} | GET参数 |
|
||||
| data | object | 否 | {} | 请求数据 |
|
||||
| requestType | string | 否 | 'json' | 请求类型 ('json' 或 'form') |
|
||||
| headers | object | 否 | {} | 请求头 |
|
||||
| rawResponse | boolean | 否 | false | 是否返回原始响应 |
|
||||
|
||||
**使用示例**
|
||||
```javascript
|
||||
// 自定义请求
|
||||
const result = await HttpUtil.req('/api/data', {
|
||||
method: 'POST',
|
||||
data: {key: 'value'},
|
||||
headers: {'Custom-Header': 'value'}
|
||||
});
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [TsHttpUtil.js:136-165](file://src/https/TsHttpUtil.js#L136-L165)
|
||||
|
||||
### 集成关系
|
||||
|
||||
#### 与存储模块的集成
|
||||
|
||||
TsHttpUtil 通过存储模块管理用户认证信息：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TsHttpUtil {
|
||||
+getUserToken() string
|
||||
+saveUserToken(token) void
|
||||
+getEncryptBody() boolean
|
||||
+saveEncryptBody(bool) void
|
||||
}
|
||||
class TsStorage {
|
||||
+getUserToken() string
|
||||
+saveUserToken(token) void
|
||||
+getEncryptBody() boolean
|
||||
+saveEncryptBody(bool) void
|
||||
}
|
||||
class TsHttpUtil {
|
||||
+headers : object
|
||||
+token : string
|
||||
}
|
||||
TsHttpUtil --> TsStorage : 使用
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsHttpUtil.js:109-111](file://src/https/TsHttpUtil.js#L109-L111)
|
||||
- [TsStorage.js:13-23](file://src/utils/TsStorage.js#L13-L23)
|
||||
|
||||
#### 与加密模块的集成
|
||||
|
||||
加密功能通过 TsCrypto 和 TsSM4 实现：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TsHttpUtil {
|
||||
+encryptData(data) object
|
||||
+decryptData(data) string
|
||||
}
|
||||
class TsCrypto {
|
||||
+encrypt(content) string
|
||||
+decrypt(base64) string
|
||||
}
|
||||
class TsSM4 {
|
||||
+encrypt(plaintext) string
|
||||
+decrypt(ciphertext) string
|
||||
}
|
||||
class TsGlobalConfig {
|
||||
+base64Key : string
|
||||
}
|
||||
TsHttpUtil --> TsCrypto : 使用
|
||||
TsCrypto --> TsSM4 : 使用
|
||||
TsCrypto --> TsGlobalConfig : 读取配置
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
|
||||
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
|
||||
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
|
||||
|
||||
#### 与配置模块的集成
|
||||
|
||||
全局配置管理：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TsGlobalConfig {
|
||||
+defaultConfig : object
|
||||
+getConfig() object
|
||||
+setConfig(obj) void
|
||||
}
|
||||
class TsHttpUtil {
|
||||
+prefix : string
|
||||
+httpParams : function
|
||||
+onHttpError : function
|
||||
}
|
||||
TsHttpUtil --> TsGlobalConfig : 读取配置
|
||||
TsGlobalConfig --> TsHttpUtil : 提供配置
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsGlobalConfig.js:5-29](file://src/utils/TsGlobalConfig.js#L5-L29)
|
||||
- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
|
||||
|
||||
**章节来源**
|
||||
- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
|
||||
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 外部依赖
|
||||
|
||||
项目的主要外部依赖包括：
|
||||
|
||||
| 依赖包 | 版本 | 用途 |
|
||||
|-------|------|-----|
|
||||
| umi-request | 1.4.0 | HTTP 客户端库 |
|
||||
| base64-js | 1.5.1 | Base64 编码/解码 |
|
||||
|
||||
### 内部模块依赖
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
TsHttpUtil[TsHttpUtil.js] --> TsStorage[TsStorage.js]
|
||||
TsHttpUtil --> TsCommon[TsCommon.js]
|
||||
TsHttpUtil --> TsCrypto[TsCrypto.js]
|
||||
TsHttpUtil --> TsGlobalConfig[TsGlobalConfig.js]
|
||||
TsCrypto --> TsSM4[TsSM4.js]
|
||||
TsCrypto --> TsGlobalConfig
|
||||
TsSM4 --> Base64[base64-js]
|
||||
index[index.js] --> TsHttpUtil
|
||||
index --> TsStorage
|
||||
index --> TsCrypto
|
||||
index --> TsGlobalConfig
|
||||
index --> TsSM4
|
||||
index --> TsCommon
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
|
||||
**章节来源**
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 请求优化建议
|
||||
|
||||
1. **批量请求**: 对于多个相关的请求，考虑合并到单个请求中以减少网络开销
|
||||
2. **缓存策略**: 在业务层实现适当的缓存机制，避免重复请求相同数据
|
||||
3. **超时设置**: 合理设置请求超时时间，避免长时间阻塞
|
||||
4. **压缩传输**: 对大体积数据考虑使用压缩算法
|
||||
|
||||
### 内存管理
|
||||
|
||||
- 及时清理不再使用的响应数据
|
||||
- 避免在请求过程中创建大量临时对象
|
||||
- 注意循环引用的处理
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 1. 认证失败
|
||||
|
||||
**症状**: 返回 401 状态码
|
||||
|
||||
**原因**: 用户令牌无效或过期
|
||||
|
||||
**解决方案**:
|
||||
```javascript
|
||||
// 检查用户令牌
|
||||
const token = Storage.getUserToken();
|
||||
if (!token) {
|
||||
// 重新登录
|
||||
redirectToLogin();
|
||||
}
|
||||
|
||||
// 设置自定义头部
|
||||
const result = await HttpUtil.get('/api/protected', {}, {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### 2. 数据解密失败
|
||||
|
||||
**症状**: 解密后数据格式错误
|
||||
|
||||
**原因**: 加密密钥不匹配或数据损坏
|
||||
|
||||
**解决方案**:
|
||||
```javascript
|
||||
// 检查加密配置
|
||||
const encryptEnabled = Storage.getEncryptBody();
|
||||
if (encryptEnabled) {
|
||||
// 验证密钥配置
|
||||
const config = GlobalConfig.getConfig();
|
||||
if (!config.base64Key) {
|
||||
throw new Error('缺少加密密钥配置');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 请求超时
|
||||
|
||||
**症状**: 请求长时间无响应
|
||||
|
||||
**原因**: 网络延迟或服务器负载过高
|
||||
|
||||
**解决方案**:
|
||||
```javascript
|
||||
try {
|
||||
const result = await HttpUtil.get('/api/data', {}, {
|
||||
timeout: 10000 // 10秒超时
|
||||
});
|
||||
} catch (error) {
|
||||
if (error.code === 'ECONNABORTED') {
|
||||
// 处理超时
|
||||
showTimeoutMessage();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. 参数格式错误
|
||||
|
||||
**症状**: 返回 400 状态码
|
||||
|
||||
**原因**: 请求参数格式不符合服务器要求
|
||||
|
||||
**解决方案**:
|
||||
```javascript
|
||||
// 使用分页器参数
|
||||
const result = await HttpUtil.get('/api/list', {
|
||||
pagination: {
|
||||
pageSize: 10,
|
||||
current: 1
|
||||
}
|
||||
});
|
||||
|
||||
// 使用 equals 条件
|
||||
const result = await HttpUtil.get('/api/search', {
|
||||
equals: {
|
||||
status: 'active',
|
||||
type: 'user'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [TsHttpUtil.js:124-127](file://src/https/TsHttpUtil.js#L124-L127)
|
||||
- [TsHttpUtil.js:130-132](file://src/https/TsHttpUtil.js#L130-L132)
|
||||
|
||||
## 结论
|
||||
|
||||
HTTP 请求模块 (TsHttpUtil) 提供了一个功能完整、易于使用的网络请求封装解决方案。其主要优势包括：
|
||||
|
||||
1. **统一的接口设计**: 提供简洁一致的 API 接口
|
||||
2. **智能参数处理**: 自动处理分页器和条件参数
|
||||
3. **完善的错误处理**: 内置状态码映射和错误回调机制
|
||||
4. **灵活的安全支持**: 可选的 SM4 加密传输功能
|
||||
5. **良好的模块化**: 与存储、加密、配置模块的深度集成
|
||||
|
||||
该模块适合在企业级应用中使用，能够有效简化网络请求的处理逻辑，提高开发效率和代码质量。通过合理的配置和使用，可以满足大多数 Web 应用的网络通信需求。
|
||||
490
.qoder/repowiki/zh/content/核心模块/SM4 算法模块 (TsSM4).md
Normal file
490
.qoder/repowiki/zh/content/核心模块/SM4 算法模块 (TsSM4).md
Normal file
@@ -0,0 +1,490 @@
|
||||
# SM4 算法模块 (TsSM4)
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
SM4 算法模块是基于中国国家密码标准的对称加密算法实现，采用 128 位分组长度和 128 位密钥长度。该模块提供了完整的 SM4 加密解密功能，支持 CBC 和 ECB 两种工作模式，并实现了 PKCS7 自动填充算法。模块设计遵循现代 JavaScript 最佳实践，使用 ES6 类语法和 TypedArray 数据结构，确保高性能和内存效率。
|
||||
|
||||
本模块在企业级应用中用于数据加密、安全通信和敏感信息保护，特别适用于需要符合中国国家标准的加密需求场景。
|
||||
|
||||
## 项目结构
|
||||
|
||||
该项目采用模块化组织方式，主要包含以下核心文件：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心模块"
|
||||
SM4[TsSM4.js<br/>主加密模块]
|
||||
Crypto[TsCrypto.js<br/>加密服务封装]
|
||||
Global[TsGlobalConfig.js<br/>全局配置]
|
||||
end
|
||||
subgraph "工具模块"
|
||||
Common[TsCommon.js<br/>通用工具]
|
||||
Storage[TsStorage.js<br/>存储工具]
|
||||
HttpUtil[TsHttpUtil.js<br/>HTTP工具]
|
||||
end
|
||||
subgraph "入口文件"
|
||||
Index[index.js<br/>模块导出]
|
||||
Package[package.json<br/>依赖管理]
|
||||
end
|
||||
SM4 --> Crypto
|
||||
Crypto --> Global
|
||||
Index --> SM4
|
||||
Index --> Crypto
|
||||
Index --> Common
|
||||
Index --> Storage
|
||||
Index --> HttpUtil
|
||||
Package --> SM4
|
||||
Package --> Crypto
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
|
||||
**章节来源**
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 主要类结构
|
||||
|
||||
TsSM4 模块包含两个核心类：Crypt 工具类和 TsSM4 加密类。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Crypt {
|
||||
+stringToArrayBufferInUtf8(str) Uint8Array
|
||||
+utf8ArrayBufferToString(buffer) String
|
||||
+arrayBufferToBase64(buffer) String
|
||||
+base64ToArrayBuffer(base64) Uint8Array
|
||||
}
|
||||
class TsSM4 {
|
||||
-Uint8Array key
|
||||
-Uint8Array iv
|
||||
-String mode
|
||||
-String cipherType
|
||||
-Uint32Array encryptRoundKeys
|
||||
-Uint32Array decryptRoundKeys
|
||||
+constructor(config)
|
||||
+doBlockCrypt(blockData, roundKeys) Uint32Array
|
||||
+spawnEncryptRoundKeys() Uint32Array
|
||||
+rotateLeft(x, y) Number
|
||||
+linearTransform1(b) Number
|
||||
+linearTransform2(b) Number
|
||||
+tauTransform(a) Number
|
||||
+tTransform1(z) Number
|
||||
+tTransform2(z) Number
|
||||
+padding(originalBuffer) Uint8Array
|
||||
+dePadding(paddedBuffer) Uint8Array
|
||||
+uint8ToUint32Block(uint8Array, baseIndex) Uint32Array
|
||||
+encrypt(plaintext) String
|
||||
+decrypt(ciphertext) String
|
||||
}
|
||||
class TsCrypto {
|
||||
-SM4 sm4
|
||||
+constructor()
|
||||
+encrypt(content) String
|
||||
+decrypt(base64) String
|
||||
}
|
||||
TsSM4 --> Crypt : "使用"
|
||||
TsCrypto --> TsSM4 : "封装"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:39-453](file://src/utils/TsSM4.js#L39-L453)
|
||||
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
|
||||
|
||||
### 关键常量定义
|
||||
|
||||
模块定义了 SM4 算法的核心常量：
|
||||
|
||||
- **Sbox 替换表**: 16×16 的 S 盒替换表，用于字节替换操作
|
||||
- **CK 常量数组**: 32 个轮常量，用于密钥扩展
|
||||
- **FK 固定常量**: 4 个固定常量，用于初始密钥处理
|
||||
|
||||
**章节来源**
|
||||
- [TsSM4.js:5-37](file://src/utils/TsSM4.js#L5-L37)
|
||||
|
||||
## 架构概览
|
||||
|
||||
### 整体架构设计
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "应用层"
|
||||
App[业务应用]
|
||||
Config[配置管理]
|
||||
end
|
||||
subgraph "加密服务层"
|
||||
CryptoService[TsCrypto]
|
||||
SM4Engine[TsSM4]
|
||||
end
|
||||
subgraph "数据转换层"
|
||||
Base64[Base64 编码]
|
||||
UTF8[UTF-8 编码]
|
||||
ByteArray[字节数组]
|
||||
end
|
||||
subgraph "底层实现"
|
||||
SBox[S 盒表]
|
||||
RoundKeys[轮密钥]
|
||||
Transform[变换函数]
|
||||
end
|
||||
App --> CryptoService
|
||||
Config --> CryptoService
|
||||
CryptoService --> SM4Engine
|
||||
SM4Engine --> Base64
|
||||
SM4Engine --> UTF8
|
||||
SM4Engine --> ByteArray
|
||||
SM4Engine --> SBox
|
||||
SM4Engine --> RoundKeys
|
||||
SM4Engine --> Transform
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
|
||||
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
|
||||
|
||||
### 数据流处理
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 应用客户端
|
||||
participant Crypto as TsCrypto
|
||||
participant SM4 as TsSM4
|
||||
participant Crypt as Crypt工具
|
||||
Client->>Crypto : encrypt(明文)
|
||||
Crypto->>SM4 : encrypt(明文)
|
||||
SM4->>Crypt : stringToArrayBufferInUtf8(明文)
|
||||
Crypt-->>SM4 : UTF-8 字节数组
|
||||
SM4->>SM4 : padding(填充)
|
||||
SM4->>SM4 : CBC/ECB 模式处理
|
||||
SM4->>Crypt : arrayBufferToBase64(密文)
|
||||
Crypt-->>SM4 : Base64 字符串
|
||||
SM4-->>Crypto : 密文字符串
|
||||
Crypto-->>Client : 密文字符串
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
- [TsCrypto.js:19-21](file://src/utils/TsCrypto.js#L19-L21)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### SM4 核心算法实现
|
||||
|
||||
#### 密钥扩展算法
|
||||
|
||||
密钥扩展是 SM4 算法的核心步骤，负责从原始密钥生成 32 个轮密钥。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始密钥扩展]) --> ExtractMK["提取 MK 密钥<br/>mk[0..3] = key[0..15]"]
|
||||
ExtractMK --> InitK["初始化 K 数组<br/>k[0..3] = mk ⊕ FK"]
|
||||
InitK --> Loop{"循环 i = 0..31"}
|
||||
Loop --> CalcK["计算 k[i+4] = k[i] ⊕ T(k[i+1] ⊕ k[i+2] ⊕ k[i+3] ⊕ CK[i])"]
|
||||
CalcK --> SaveKey["保存轮密钥<br/>encryptRoundKeys[i] = k[i+4]"]
|
||||
SaveKey --> Loop
|
||||
Loop --> |完成| ReverseKeys["反转密钥顺序<br/>decryptRoundKeys = reverse(encryptRoundKeys)"]
|
||||
ReverseKeys --> End([结束])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:189-207](file://src/utils/TsSM4.js#L189-L207)
|
||||
|
||||
#### 轮函数实现
|
||||
|
||||
每个 SM4 轮包含多个变换操作：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
BlockIn[16字节明文块] --> SplitBlock["分割为4个32位字<br/>block[0..3]"]
|
||||
SplitBlock --> RoundLoop{"i = 0..31"}
|
||||
RoundLoop --> XOROp["x[i+4] = x[i] ⊕ T(x[i+1] ⊕ x[i+2] ⊕ x[i+3] ⊕ RK[i])"]
|
||||
XOROp --> RoundLoop
|
||||
RoundLoop --> |完成| FinalBlock["组合最终块<br/>y[0..3] = x[32..35]"]
|
||||
FinalBlock --> BlockOut[16字节密文块]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:166-180](file://src/utils/TsSM4.js#L166-L180)
|
||||
|
||||
#### 变换函数详解
|
||||
|
||||
##### τ 变换 (字节替换)
|
||||
τ 变换使用 S 盒进行非线性替换：
|
||||
- 输入: 32位值
|
||||
- 处理: 将每个字节通过 S 盒查找替换
|
||||
- 输出: 32位值
|
||||
|
||||
##### L 线性变换
|
||||
L 变换实现位移和异或操作：
|
||||
- L1: b ⊕ (b <<< 2) ⊕ (b <<< 10) ⊕ (b <<< 18) ⊕ (b <<< 24)
|
||||
- L2: b ⊕ (b <<< 13) ⊕ (b <<< 23)
|
||||
|
||||
##### T 组合变换
|
||||
T 变换结合 τ 和 L 变换：
|
||||
- T1: L1(τ(z))
|
||||
- T2: L2(τ(z))
|
||||
|
||||
**章节来源**
|
||||
- [TsSM4.js:250-277](file://src/utils/TsSM4.js#L250-L277)
|
||||
|
||||
### 工作模式实现
|
||||
|
||||
#### CBC 模式
|
||||
|
||||
CBC (Cipher Block Chaining) 模式提供链式加密：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant P as 明文块
|
||||
participant IV as 初始化向量
|
||||
participant XOR as 异或运算
|
||||
participant ENC as 加密器
|
||||
participant C as 密文块
|
||||
P1->>XOR : 明文1 ⊕ IV
|
||||
XOR->>ENC : (明文1 ⊕ IV)
|
||||
ENC-->>C : 密文1
|
||||
C->>XOR : 密文1 ⊕ 明文2
|
||||
XOR->>ENC : (密文1 ⊕ 明文2) ⊕ IV
|
||||
ENC-->>C : 密文2
|
||||
Note over IV,C : 每次使用前一个密文作为链输入
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:343-378](file://src/utils/TsSM4.js#L343-L378)
|
||||
|
||||
#### ECB 模式
|
||||
|
||||
ECB (Electronic Codebook) 模式提供独立块加密：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Plain1[明文块1] --> Encrypt1[独立加密]
|
||||
Plain2[明文块2] --> Encrypt2[独立加密]
|
||||
Plain3[明文块3] --> Encrypt3[独立加密]
|
||||
Encrypt1 --> Cipher1[密文块1]
|
||||
Encrypt2 --> Cipher2[密文块2]
|
||||
Encrypt3 --> Cipher3[密文块3]
|
||||
Note1[相同明文块产生相同密文块]
|
||||
Note2[无链式依赖]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:368-378](file://src/utils/TsSM4.js#L368-L378)
|
||||
|
||||
### PKCS7 填充算法
|
||||
|
||||
PKCS7 是一种标准的块填充方案：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始填充]) --> CheckNull{"输入为空?"}
|
||||
CheckNull --> |是| ReturnNull[返回 null]
|
||||
CheckNull --> |否| CalcPad["计算填充长度<br/>padLen = 16 - (len % 16)"]
|
||||
CalcPad --> CreateBuffer["创建新缓冲区<br/>长度 = 原长度 + padLen"]
|
||||
CreateBuffer --> CopyData["复制原数据到新缓冲区"]
|
||||
CopyData --> FillPad["填充 padLen 个字节<br/>每个字节值为 padLen"]
|
||||
FillPad --> ReturnBuffer[返回填充后的缓冲区]
|
||||
ReturnNull --> End([结束])
|
||||
ReturnBuffer --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:287-296](file://src/utils/TsSM4.js#L287-L296)
|
||||
|
||||
**章节来源**
|
||||
- [TsSM4.js:287-312](file://src/utils/TsSM4.js#L287-L312)
|
||||
|
||||
### 数据类型转换
|
||||
|
||||
#### 字节数组与 32 位整数转换
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Uint8Array[Uint8Array] --> SplitBytes["按字节分割<br/>每4字节组成一个32位整数"]
|
||||
SplitBytes --> ShiftLeft["左移操作<br/>高位字节 << 24, 16, 8, 0"]
|
||||
ShiftLeft --> ORCombine["按位或组合<br/>形成32位整数"]
|
||||
ORCombine --> Uint32Array[Uint32Array]
|
||||
Uint32Array --> SplitBits["按位拆分<br/>32位整数拆分为4个字节"]
|
||||
SplitBits --> ShiftRight["右移操作<br/>高位字节 >> 24, 16, 8, 0"]
|
||||
ShiftRight --> ANDMask["按位与掩码<br/>& 0xFF"]
|
||||
ANDMask --> Uint8Array[Uint8Array]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:322-329](file://src/utils/TsSM4.js#L322-L329)
|
||||
|
||||
**章节来源**
|
||||
- [TsSM4.js:322-329](file://src/utils/TsSM4.js#L322-L329)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 外部依赖
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "外部库"
|
||||
Base64[base64-js@1.5.1<br/>Base64 编解码]
|
||||
UmiRequest[umi-request@1.4.0<br/>HTTP 请求]
|
||||
end
|
||||
subgraph "内部模块"
|
||||
SM4[TsSM4.js<br/>SM4 加密算法]
|
||||
Crypto[TsCrypto.js<br/>加密服务封装]
|
||||
Global[TsGlobalConfig.js<br/>全局配置]
|
||||
Common[TsCommon.js<br/>通用工具]
|
||||
Storage[TsStorage.js<br/>存储工具]
|
||||
HttpUtil[TsHttpUtil.js<br/>HTTP 工具]
|
||||
end
|
||||
SM4 --> Base64
|
||||
Crypto --> Base64
|
||||
Crypto --> Global
|
||||
HttpUtil --> UmiRequest
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js#L1)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js#L1)
|
||||
|
||||
### 内部模块依赖
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
SM4[TsSM4] --> Crypt[Crypt 工具类]
|
||||
Crypto[TsCrypto] --> SM4
|
||||
Crypto --> Global[全局配置]
|
||||
HttpUtil[TsHttpUtil] --> SM4
|
||||
HttpUtil --> Crypto
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsSM4.js:1-94](file://src/utils/TsSM4.js#L1-L94)
|
||||
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
|
||||
**章节来源**
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 内存使用分析
|
||||
|
||||
#### 数据结构内存占用
|
||||
|
||||
| 数据结构 | 大小 | 用途 |
|
||||
|---------|------|------|
|
||||
| Uint8Array | 1 字节/元素 | 原始字节数据 |
|
||||
| Uint32Array | 4 字节/元素 | 32位整数运算 |
|
||||
| Sbox 表 | 256 字节 | 字节替换表 |
|
||||
| 轮密钥数组 | 128 字节 | 32个轮密钥 |
|
||||
| 中间变量 | ~144 字节 | 临时计算结果 |
|
||||
|
||||
#### 内存优化策略
|
||||
|
||||
1. **TypedArray 使用**: 优先使用 TypedArray 减少内存开销
|
||||
2. **就地计算**: 尽可能重用数组避免额外分配
|
||||
3. **批量处理**: 一次处理多个块提高缓存利用率
|
||||
|
||||
### 性能特征
|
||||
|
||||
#### 时间复杂度
|
||||
|
||||
- **密钥扩展**: O(1) - 固定 32 次迭代
|
||||
- **单块加密**: O(1) - 固定 32 轮运算
|
||||
- **整体加密**: O(n) - n 为块数量
|
||||
|
||||
#### 空间复杂度
|
||||
|
||||
- **内存使用**: O(n) - n 为输入数据大小
|
||||
- **额外开销**: O(1) - 固定大小的中间变量
|
||||
|
||||
### 并发处理
|
||||
|
||||
模块当前不支持并发操作，建议：
|
||||
1. 为每个并发任务创建独立的 TsSM4 实例
|
||||
2. 避免在多线程环境中共享同一实例
|
||||
3. 考虑使用 Web Workers 处理大量数据
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见错误及解决方案
|
||||
|
||||
#### 密钥长度错误
|
||||
|
||||
**问题**: 密钥长度不是 16 字节
|
||||
**解决**: 确保密钥为 16 字节长度
|
||||
**位置**: [TsSM4.js:103-105](file://src/utils/TsSM4.js#L103-L105)
|
||||
|
||||
#### IV 参数错误
|
||||
|
||||
**问题**: CBC 模式下 IV 长度不正确
|
||||
**解决**: 确保 IV 为 16 字节长度
|
||||
**位置**: [TsSM4.js:119-121](file://src/utils/TsSM4.js#L119-L121)
|
||||
|
||||
#### 填充数据错误
|
||||
|
||||
**问题**: 去填充时数据格式不正确
|
||||
**解决**: 确保使用相同的填充算法进行加解密
|
||||
**位置**: [TsSM4.js:309-311](file://src/utils/TsSM4.js#L309-L311)
|
||||
|
||||
### 调试技巧
|
||||
|
||||
1. **启用详细日志**: 在开发环境中输出中间计算结果
|
||||
2. **单元测试**: 为关键函数编写测试用例
|
||||
3. **边界测试**: 测试空数据、单块数据、多块数据等场景
|
||||
|
||||
**章节来源**
|
||||
- [TsSM4.js:103-121](file://src/utils/TsSM4.js#L103-L121)
|
||||
- [TsSM4.js:309-311](file://src/utils/TsSM4.js#L309-L311)
|
||||
|
||||
## 结论
|
||||
|
||||
SM4 算法模块提供了完整、高效的中国国家标准加密实现。模块具有以下特点：
|
||||
|
||||
### 技术优势
|
||||
|
||||
1. **标准兼容**: 完全符合 SM4 算法规范
|
||||
2. **性能优秀**: 使用 TypedArray 和优化算法
|
||||
3. **接口友好**: 提供简洁的加密解密接口
|
||||
4. **模式完整**: 支持 CBC 和 ECB 两种工作模式
|
||||
|
||||
### 应用场景
|
||||
|
||||
- 企业数据加密
|
||||
- 网络通信安全
|
||||
- 敏感信息保护
|
||||
- 符合国家标准的系统集成
|
||||
|
||||
### 发展建议
|
||||
|
||||
1. **添加更多模式**: 考虑支持 OFB、CFB 等模式
|
||||
2. **性能优化**: 实现 SIMD 指令集优化
|
||||
3. **安全性增强**: 添加完整性校验机制
|
||||
4. **文档完善**: 提供更详细的使用示例
|
||||
|
||||
该模块为企业级应用提供了可靠的加密解决方案，满足了中国国家标准的要求，同时保持了良好的性能和易用性。
|
||||
363
.qoder/repowiki/zh/content/核心模块/全局配置模块 (TsGlobalConfig).md
Normal file
363
.qoder/repowiki/zh/content/核心模块/全局配置模块 (TsGlobalConfig).md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 全局配置模块 (TsGlobalConfig)
|
||||
|
||||
<cite>
|
||||
**本文引用的文件列表**
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
- [TsCommon.js](file://src/utils/TsCommon.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向全局配置模块（TsGlobalConfig），系统性阐述其在工具包中的核心地位与作用，以及与网络请求、加解密、存储等模块的集成关系。文档重点覆盖：
|
||||
- 默认配置与动态更新机制
|
||||
- 配置项类型、作用域与优先级规则
|
||||
- 完整的配置 API 使用说明
|
||||
- 配置示例、最佳实践与常见场景
|
||||
- 错误处理回调与配置验证逻辑
|
||||
|
||||
## 项目结构
|
||||
该工具包采用按功能模块划分的组织方式，TsGlobalConfig 作为全局配置中心，被网络请求、加解密、存储等模块以依赖形式使用，对外通过入口文件统一导出。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "入口与导出"
|
||||
IDX["index.js"]
|
||||
end
|
||||
subgraph "配置与工具"
|
||||
CFG["TsGlobalConfig.js"]
|
||||
COM["TsCommon.js"]
|
||||
STO["TsStorage.js"]
|
||||
end
|
||||
subgraph "网络与安全"
|
||||
HTTP["TsHttpUtil.js"]
|
||||
CRY["TsCrypto.js"]
|
||||
SM4["TsSM4.js"]
|
||||
end
|
||||
IDX --> HTTP
|
||||
IDX --> CFG
|
||||
IDX --> STO
|
||||
IDX --> CRY
|
||||
IDX --> COM
|
||||
HTTP --> CFG
|
||||
HTTP --> STO
|
||||
HTTP --> COM
|
||||
CRY --> CFG
|
||||
CRY --> SM4
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [index.js](file://index.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
- [TsCommon.js](file://src/utils/TsCommon.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
|
||||
章节来源
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
|
||||
## 核心组件
|
||||
- 全局配置中心（TsGlobalConfig）
|
||||
- 提供默认配置与运行时配置合并能力
|
||||
- 暴露配置读取与写入接口，支持动态更新
|
||||
- 网络请求模块（TsHttpUtil）
|
||||
- 通过全局配置决定前缀、附加参数、错误处理回调等行为
|
||||
- 加密模块（TsCrypto）
|
||||
- 从全局配置读取密钥，用于 SM4 加解密
|
||||
- 存储模块（TsStorage）
|
||||
- 与全局配置配合控制是否启用请求体加密开关
|
||||
|
||||
章节来源
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
|
||||
## 架构总览
|
||||
TsGlobalConfig 作为“全局状态”容器，贯穿请求生命周期的关键节点：
|
||||
- 请求发起前：根据配置决定 URL 前缀拼接、附加参数注入
|
||||
- 请求过程中：根据配置决定是否加密请求体
|
||||
- 请求完成后：根据配置调用错误处理回调
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Caller as "调用方"
|
||||
participant Http as "TsHttpUtil"
|
||||
participant Cfg as "TsGlobalConfig"
|
||||
participant Sto as "TsStorage"
|
||||
participant Cry as "TsCrypto"
|
||||
participant Net as "umi-request"
|
||||
Caller->>Http : "发起请求"
|
||||
Http->>Cfg : "读取配置前缀/附加参数/错误回调"
|
||||
Http->>Sto : "读取用户 Token"
|
||||
Http->>Http : "根据配置处理参数/附加参数"
|
||||
alt "需要加密"
|
||||
Http->>Cry : "读取 base64Key 并加密"
|
||||
end
|
||||
Http->>Net : "发送请求"
|
||||
Net-->>Http : "响应结果"
|
||||
alt "业务错误"
|
||||
Http->>Cfg : "调用 onHttpError 回调"
|
||||
end
|
||||
Http-->>Caller : "返回处理后的数据"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### TsGlobalConfig 组件分析
|
||||
- 默认配置
|
||||
- 包含基础密钥、URL 前缀、HTTP 错误回调、附加参数函数等
|
||||
- 配置读取
|
||||
- 优先读取浏览器全局对象上的运行时配置；若未设置则回退到默认配置
|
||||
- 配置写入
|
||||
- 合并传入配置与当前配置，形成最终运行时配置
|
||||
- 作用域与优先级
|
||||
- 作用域：浏览器全局 window 对象
|
||||
- 优先级：运行时配置 > 默认配置
|
||||
- 配置项类型与用途
|
||||
- base64Key：SM4 密钥（Base64 字符串），用于加密/解密
|
||||
- prefix：字符串或函数，用于拼接请求 URL 前缀
|
||||
- onHttpError：函数，接收后端返回的错误对象，用于统一错误处理
|
||||
- httpParams：函数，返回附加参数对象，用于 GET/POST 注入
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> ReadRuntime["读取 window.httpConfig"]
|
||||
ReadRuntime --> HasRuntime{"是否存在运行时配置？"}
|
||||
HasRuntime -- "是" --> Merge["合并默认配置与运行时配置"]
|
||||
HasRuntime -- "否" --> UseDefault["使用默认配置"]
|
||||
Merge --> ReturnCfg["返回最终配置"]
|
||||
UseDefault --> ReturnCfg
|
||||
ReturnCfg --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
|
||||
章节来源
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
|
||||
### TsHttpUtil 与全局配置的集成
|
||||
- URL 前缀处理
|
||||
- 支持字符串或函数两种形式；函数形式可按 URL 动态生成前缀
|
||||
- 附加参数注入
|
||||
- 若配置了 httpParams 函数，则在 GET 参数与非表单 POST 数据中注入
|
||||
- 错误处理回调
|
||||
- 当响应码非 200 时，调用 onHttpError 回调
|
||||
- 请求体加密
|
||||
- 结合存储模块的开关与全局配置的密钥，对请求体进行加密包装
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Util as "TsHttpUtil"
|
||||
participant Cfg as "TsGlobalConfig"
|
||||
participant Sto as "TsStorage"
|
||||
participant Net as "umi-request"
|
||||
Util->>Cfg : "读取 prefix/httpParams/onHttpError"
|
||||
Util->>Sto : "读取用户 Token"
|
||||
Util->>Util : "处理分页/equals 等参数"
|
||||
Util->>Cfg : "调用 httpParams()"
|
||||
Util->>Net : "发送请求"
|
||||
Net-->>Util : "返回响应"
|
||||
alt "业务错误"
|
||||
Util->>Cfg : "调用 onHttpError(res)"
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
|
||||
### TsCrypto 与全局配置的集成
|
||||
- 初始化阶段
|
||||
- 从全局配置读取 base64Key，并转换为字节数组
|
||||
- 加解密流程
|
||||
- 基于 SM4 算法，支持 ECB/CBC 模式与 Base64 输出类型
|
||||
- 配置影响点
|
||||
- base64Key 变更会直接影响密钥解析与后续加解密结果
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TsCrypto {
|
||||
+constructor()
|
||||
+encrypt(content)
|
||||
+decrypt(base64)
|
||||
}
|
||||
class TsSM4 {
|
||||
+constructor(config)
|
||||
+encrypt(plaintext)
|
||||
+decrypt(ciphertext)
|
||||
}
|
||||
TsCrypto --> TsSM4 : "组合使用"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
|
||||
章节来源
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
|
||||
### 配置 API 文档
|
||||
- setConfig(obj)
|
||||
- 功能：合并传入配置与当前运行时配置，形成新的全局配置
|
||||
- 参数：obj 为配置对象，键值对应默认配置项
|
||||
- 注意：仅影响后续请求与加密初始化
|
||||
- getConfig()
|
||||
- 功能：返回当前运行时配置（若未设置则回退默认配置）
|
||||
- 返回：配置对象（包含 base64Key、prefix、onHttpError、httpParams）
|
||||
|
||||
章节来源
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
|
||||
### 配置项类型、作用域与优先级
|
||||
- 类型与含义
|
||||
- base64Key：字符串，SM4 密钥（Base64 编码）
|
||||
- prefix：字符串或函数，用于拼接请求 URL 前缀
|
||||
- onHttpError：函数，接收后端返回的错误对象
|
||||
- httpParams：函数，返回附加参数对象
|
||||
- 作用域
|
||||
- 浏览器全局 window 对象，模块间共享
|
||||
- 优先级
|
||||
- 运行时配置优先于默认配置；函数类型的 prefix 可按 URL 动态生效
|
||||
|
||||
章节来源
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
|
||||
### 配置示例与最佳实践
|
||||
- 示例一：设置 URL 前缀与错误回调
|
||||
- 在应用启动时调用 setConfig，设置 prefix 与 onHttpError
|
||||
- 之后所有请求自动拼接前缀并统一错误处理
|
||||
- 示例二：启用请求体加密
|
||||
- 通过存储模块保存加密开关状态
|
||||
- TsHttpUtil 在发送请求时读取开关并按需加密
|
||||
- 最佳实践
|
||||
- 将全局配置集中初始化，避免分散设置
|
||||
- prefix 使用函数形式以适配多环境
|
||||
- onHttpError 中统一记录日志与用户提示
|
||||
- base64Key 由后端统一管理，避免硬编码
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
|
||||
### 错误处理回调与配置验证逻辑
|
||||
- 错误处理回调
|
||||
- TsHttpUtil 在业务错误时调用 onHttpError，便于统一处理
|
||||
- 配置验证
|
||||
- TsCrypto 在构造时依赖 base64Key 的正确性
|
||||
- TsSM4 在构造时校验密钥长度与 IV 长度（内部逻辑）
|
||||
- 建议
|
||||
- 在 setConfig 后进行一次关键配置的自检
|
||||
- 对 prefix 函数进行边界测试（如空字符串、特殊字符）
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
|
||||
## 依赖关系分析
|
||||
- TsHttpUtil 依赖
|
||||
- TsGlobalConfig：读取前缀、附加参数、错误回调
|
||||
- TsStorage：读取用户 Token、加密开关
|
||||
- TsCommon：通用工具（如 JSON 解析）
|
||||
- TsCrypto 依赖
|
||||
- TsGlobalConfig：读取 base64Key
|
||||
- TsSM4：SM4 加解密实现
|
||||
- TsStorage 与 TsGlobalConfig 的间接耦合
|
||||
- 通过开关控制是否启用加密，进而影响请求流程
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Http["TsHttpUtil"] --> Cfg["TsGlobalConfig"]
|
||||
Http --> Sto["TsStorage"]
|
||||
Http --> Com["TsCommon"]
|
||||
Cry["TsCrypto"] --> Cfg
|
||||
Cry --> Sm4["TsSM4"]
|
||||
Sto --> Com
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
- [TsCommon.js](file://src/utils/TsCommon.js)
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
- [TsCommon.js](file://src/utils/TsCommon.js)
|
||||
|
||||
## 性能考量
|
||||
- 配置读取成本极低，建议在请求发起前一次性读取并缓存必要字段
|
||||
- prefix 为函数时，每次请求都会执行，建议在函数内做必要的缓存或短路判断
|
||||
- httpParams 返回的对象会被频繁合并，建议保持对象简洁
|
||||
- 加密/解密为 CPU 密集型操作，仅在必要时启用
|
||||
|
||||
## 故障排查指南
|
||||
- 症状：请求未带前缀
|
||||
- 排查：确认 setConfig 是否已设置 prefix；若为函数，确认返回值
|
||||
- 症状：onHttpError 未触发
|
||||
- 排查：确认后端返回码非 200；确认 onHttpError 是否为函数
|
||||
- 症状：加密失败或解密异常
|
||||
- 排查：确认 base64Key 正确；确认前后端密钥一致；确认存储开关状态
|
||||
- 症状：附加参数未生效
|
||||
- 排查：确认 httpParams 是否为函数；确认请求类型（GET/POST）是否匹配
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
|
||||
## 结论
|
||||
TsGlobalConfig 作为工具包的“全局中枢”，通过简单而强大的配置 API，实现了对网络请求、加解密、存储等模块的统一控制。合理使用配置项与回调，可显著提升系统的可维护性与一致性。建议在应用启动阶段完成全局配置初始化，并结合错误处理与日志记录，确保问题可追踪、可恢复。
|
||||
|
||||
## 附录
|
||||
- 入口导出
|
||||
- index.js 将 TsGlobalConfig 与其他模块一起导出，便于外部统一引用
|
||||
- 版本与依赖
|
||||
- 依赖 umi-request 与 base64-js，用于网络请求与 Base64 编解码
|
||||
|
||||
章节来源
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
398
.qoder/repowiki/zh/content/核心模块/加密模块 (TsCrypto).md
Normal file
398
.qoder/repowiki/zh/content/核心模块/加密模块 (TsCrypto).md
Normal file
@@ -0,0 +1,398 @@
|
||||
# 加密模块 (TsCrypto)
|
||||
|
||||
<cite>
|
||||
**本文引用的文件列表**
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件为加密模块（TsCrypto）的全面技术文档，聚焦于基于 SM4 算法的加密与解密实现，覆盖 CBC 与 ECB 模式支持与配置、Base64 编解码机制、自动填充与去填充算法，以及与全局配置系统、存储系统和 HTTP 请求模块的集成方式。文档同时提供完整的 API 接口说明、使用示例、性能与安全最佳实践，并解释加密开关控制、token 加密传输等典型应用场景。
|
||||
|
||||
## 项目结构
|
||||
该工具包采用按功能模块划分的组织方式：
|
||||
- utils：通用工具与加密核心实现
|
||||
- TsCrypto.js：对外暴露的加密模块入口，封装 SM4 并与全局配置联动
|
||||
- TsSM4.js：SM4 算法实现，含填充/去填充、CBC/ECB 模式、Base64 文本编解码
|
||||
- TsGlobalConfig.js：全局配置读取与设置
|
||||
- TsStorage.js：本地存储与加密开关、token 的持久化
|
||||
- TsCommon.js：通用工具函数（如 JSON 解析、URL 参数解析等）
|
||||
- https：HTTP 请求封装与加密开关集成
|
||||
- TsHttpUtil.js：统一请求处理、参数预处理、加解密与响应解密
|
||||
- index.js：导出模块集合
|
||||
- package.json：依赖声明（base64-js、umi-request）
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "工具包(utils)"
|
||||
Crypto["TsCrypto.js"]
|
||||
SM4["TsSM4.js"]
|
||||
GConf["TsGlobalConfig.js"]
|
||||
Store["TsStorage.js"]
|
||||
Common["TsCommon.js"]
|
||||
end
|
||||
subgraph "HTTP(https)"
|
||||
HttpUtil["TsHttpUtil.js"]
|
||||
end
|
||||
Index["index.js"]
|
||||
Package["package.json"]
|
||||
Crypto --> SM4
|
||||
Crypto --> GConf
|
||||
HttpUtil --> Crypto
|
||||
HttpUtil --> Store
|
||||
HttpUtil --> GConf
|
||||
HttpUtil --> Common
|
||||
Index --> Crypto
|
||||
Index --> SM4
|
||||
Index --> GConf
|
||||
Index --> Store
|
||||
Index --> HttpUtil
|
||||
Package --> SM4
|
||||
Package --> HttpUtil
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [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)
|
||||
|
||||
章节来源
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [package.json:1-24](file://package.json#L1-L24)
|
||||
|
||||
## 核心组件
|
||||
- TsCrypto：对外加密模块，负责初始化 SM4 实例（默认 ECB 模式、Base64 输出），并提供 encrypt/decrypt 方法。
|
||||
- TsSM4：SM4 算法核心，支持 CBC/ECB 模式、Base64/text 输出、自动 PKCS#7 填充与去填充、UTF-8 字符串编解码。
|
||||
- TsGlobalConfig：全局配置读取与合并，提供 base64Key、prefix、httpParams、onHttpError 等。
|
||||
- TsStorage：本地存储封装，提供用户 token、加密开关等键值存取。
|
||||
- TsHttpUtil：HTTP 请求封装，集成加密开关、请求体加密、响应体解密、token 注入等。
|
||||
|
||||
章节来源
|
||||
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
|
||||
- [TsSM4.js:96-456](file://src/utils/TsSM4.js#L96-L456)
|
||||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
|
||||
## 架构总览
|
||||
加密模块在工具包中的位置与交互如下：
|
||||
- TsCrypto 初始化时从全局配置读取 base64Key，转换为字节后注入 SM4；默认模式为 ECB，输出为 Base64。
|
||||
- TsHttpUtil 在发送请求前根据存储的加密开关决定是否对请求体进行加密；收到响应后若标记为加密，则进行解密并尝试 JSON 解析。
|
||||
- TsStorage 提供加密开关与 token 的持久化，便于跨页面/会话保持状态。
|
||||
- TsGlobalConfig 提供全局配置（如前缀、附加参数、错误回调）以影响 HTTP 请求行为。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "调用方"
|
||||
participant HttpUtil as "TsHttpUtil"
|
||||
participant Store as "TsStorage"
|
||||
participant Crypto as "TsCrypto"
|
||||
participant SM4 as "TsSM4"
|
||||
participant Server as "后端服务"
|
||||
Client->>HttpUtil : "post(url, data)"
|
||||
HttpUtil->>Store : "getEncryptBody()"
|
||||
alt "加密开关开启"
|
||||
HttpUtil->>Crypto : "encrypt(JSON.stringify(data))"
|
||||
Crypto->>SM4 : "encrypt(UTF-8字节)"
|
||||
SM4-->>Crypto : "Base64密文"
|
||||
Crypto-->>HttpUtil : "Base64密文"
|
||||
HttpUtil->>Server : "POST { encryptData : Base64密文 }"
|
||||
else "加密开关关闭"
|
||||
HttpUtil->>Server : "POST data"
|
||||
end
|
||||
Server-->>HttpUtil : "响应 { code, data, encrypt? }"
|
||||
alt "响应标记为加密"
|
||||
HttpUtil->>Crypto : "decrypt(data)"
|
||||
Crypto->>SM4 : "decrypt(Base64密文)"
|
||||
SM4-->>Crypto : "明文字节数组"
|
||||
Crypto-->>HttpUtil : "明文字符串"
|
||||
HttpUtil->>HttpUtil : "parseJSON(可选)"
|
||||
end
|
||||
HttpUtil-->>Client : "{ data, recordsTotal }"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsHttpUtil.js:81-123](file://src/https/TsHttpUtil.js#L81-L123)
|
||||
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
|
||||
- [TsSM4.js:338-452](file://src/utils/TsSM4.js#L338-L452)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### TsCrypto 组件分析
|
||||
- 角色定位：对外加密模块，封装 SM4 并与全局配置联动。
|
||||
- 关键点：
|
||||
- 构造函数中从全局配置读取 base64Key，转换为字节数组后传入 SM4。
|
||||
- 默认模式为 ECB，输出类型为 Base64。
|
||||
- 对外提供 encrypt/content 与 decrypt/base64 两个方法，分别委托给 SM4 的对应逻辑。
|
||||
- 适用场景：作为 HTTP 请求层的加密前置，或独立用于数据加密/解密。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TsCrypto {
|
||||
+constructor()
|
||||
+encrypt(content) String
|
||||
+decrypt(base64) String
|
||||
}
|
||||
class TsSM4 {
|
||||
+constructor(config)
|
||||
+encrypt(plaintext) String
|
||||
+decrypt(ciphertext) String
|
||||
-padding(buffer) Uint8Array
|
||||
-dePadding(buffer) Uint8Array
|
||||
-uint8ToUint32Block(arr, idx) Uint32Array
|
||||
-doBlockCrypt(block, roundKeys) Uint32Array
|
||||
-spawnEncryptRoundKeys() void
|
||||
-tTransform1(z) Uint32
|
||||
-tTransform2(z) Uint32
|
||||
-linearTransform1(x) Uint32
|
||||
-linearTransform2(x) Uint32
|
||||
-rotateLeft(x,y) Uint32
|
||||
}
|
||||
class GlobalConfig {
|
||||
+getConfig() Object
|
||||
+setConfig(obj) void
|
||||
}
|
||||
TsCrypto --> TsSM4 : "组合"
|
||||
TsCrypto --> GlobalConfig : "读取配置"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
|
||||
- [TsSM4.js:96-456](file://src/utils/TsSM4.js#L96-L456)
|
||||
- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)
|
||||
|
||||
章节来源
|
||||
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
|
||||
|
||||
### TsSM4 组件分析
|
||||
- 角色定位：SM4 算法实现，支持 CBC/ECB 模式、Base64/text 输出、UTF-8 编解码、PKCS#7 填充/去填充。
|
||||
- 关键点：
|
||||
- 支持 CBC/ECB 模式选择，默认 CBC；CBC 需要 16 字节 IV，否则抛错。
|
||||
- 输出类型支持 Base64 与 text；输入统一为 UTF-8 字节流。
|
||||
- 填充/去填充：按 16 字节块进行 PKCS#7 填充与去填充。
|
||||
- 字符串编解码：通过 Crypt 工具类在 UTF-8 与 Base64 之间转换。
|
||||
- 性能与复杂度：
|
||||
- 每块 16 字节，循环 32 轮；时间复杂度 O(n)，空间复杂度 O(n)。
|
||||
- 填充/去填充为线性处理，开销较小。
|
||||
- 安全性：
|
||||
- CBC 模式下 IV 必须为 16 字节，且建议随机生成；当前实现未内置 IV 生成，需确保传入合法 IV。
|
||||
- ECB 模式不推荐用于长文本或重复明文场景，易暴露模式特征。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> ToUtf8["UTF-8 编码为字节数组"]
|
||||
ToUtf8 --> Pad["PKCS#7 填充到 16 字节倍数"]
|
||||
Pad --> Mode{"模式选择"}
|
||||
Mode --> |CBC| CbcLoop["逐块 CBC 循环<br/>链式 XOR + 轮函数"]
|
||||
Mode --> |ECB| EcbLoop["逐块 ECB 循环<br/>直接轮函数"]
|
||||
CbcLoop --> OutSel{"输出类型"}
|
||||
EcbLoop --> OutSel
|
||||
OutSel --> |Base64| ToBase64["Base64 编码"]
|
||||
OutSel --> |text| ToText["UTF-8 解码"]
|
||||
ToBase64 --> End(["结束"])
|
||||
ToText --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsSM4.js:287-312](file://src/utils/TsSM4.js#L287-L312)
|
||||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
- [TsSM4.js:408-452](file://src/utils/TsSM4.js#L408-L452)
|
||||
|
||||
章节来源
|
||||
- [TsSM4.js:96-456](file://src/utils/TsSM4.js#L96-L456)
|
||||
|
||||
### TsGlobalConfig 组件分析
|
||||
- 角色定位：全局配置中心，提供默认配置与运行时合并。
|
||||
- 关键点：
|
||||
- 默认 base64Key、prefix、httpParams、onHttpError 等。
|
||||
- getConfig 返回 window.httpConfig 或默认配置；setConfig 合并传入对象。
|
||||
- 与加密模块的关系：
|
||||
- TsCrypto 通过 getConfig().base64Key 读取密钥；TsHttpUtil 通过 getConfig().prefix/httpParams/onHttpError 影响请求行为。
|
||||
|
||||
章节来源
|
||||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||||
- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
|
||||
- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
|
||||
|
||||
### TsStorage 组件分析
|
||||
- 角色定位：本地存储封装，提供 token 与加密开关的持久化。
|
||||
- 关键点：
|
||||
- save/get：统一 JSON 序列化/反序列化。
|
||||
- saveUserToken/getUserToken：token 的便捷存取。
|
||||
- saveEncryptBody/getEncryptBody：加密开关的持久化，影响 HTTP 请求是否加密请求体。
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
|
||||
|
||||
### TsHttpUtil 组件分析
|
||||
- 角色定位：HTTP 请求封装，集成加密开关、请求体加密、响应体解密、token 注入。
|
||||
- 关键点：
|
||||
- dealParamsBody：对 GET 参数与 POST 数据进行预处理；当加密开关开启时，将 data 包装为 { encryptData: TsCrypto.encrypt(JSON.stringify(data)) }。
|
||||
- req：发起请求，自动拼接 prefix、注入 token、处理响应；若响应标记为加密，则调用 TsCrypto.decrypt 并尝试 JSON 解析。
|
||||
- 错误处理：根据状态码映射错误信息，或调用全局 onHttpError 回调。
|
||||
- 与加密模块的协作：
|
||||
- 使用 TsCrypto.encrypt/decrypt 完成请求体与响应体的加解密。
|
||||
- 通过 TsStorage 控制加密开关，通过 TsGlobalConfig 控制前缀与附加参数。
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
|
||||
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
|
||||
|
||||
## 依赖关系分析
|
||||
- TsCrypto 依赖 TsSM4 与 TsGlobalConfig。
|
||||
- TsHttpUtil 依赖 TsCrypto、TsStorage、TsGlobalConfig、TsCommon。
|
||||
- TsSM4 依赖 base64-js（用于 Base64 编解码）。
|
||||
- index.js 将各模块统一导出，供外部使用。
|
||||
- package.json 声明 base64-js 与 umi-request 依赖。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
TsCrypto["TsCrypto.js"] --> TsSM4["TsSM4.js"]
|
||||
TsCrypto --> TsGlobalConfig["TsGlobalConfig.js"]
|
||||
TsHttpUtil["TsHttpUtil.js"] --> TsCrypto
|
||||
TsHttpUtil --> TsStorage["TsStorage.js"]
|
||||
TsHttpUtil --> TsGlobalConfig
|
||||
TsHttpUtil --> TsCommon["TsCommon.js"]
|
||||
TsSM4 --> Base64["base64-js(依赖)"]
|
||||
index_js["index.js"] --> TsCrypto
|
||||
index_js --> TsSM4
|
||||
index_js --> TsGlobalConfig
|
||||
index_js --> TsStorage
|
||||
index_js --> TsHttpUtil
|
||||
package_json["package.json"] --> Base64
|
||||
package_json --> UmiReq["umi-request(依赖)"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
|
||||
- [TsSM4.js:1](file://src/utils/TsSM4.js#L1)
|
||||
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
|
||||
章节来源
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
|
||||
## 性能考量
|
||||
- 时间复杂度：SM4 每块 16 字节，32 轮，整体 O(n)；填充/去填充为线性处理，开销较小。
|
||||
- 内存占用：主要为输入/输出字节数组与中间块数组，空间复杂度 O(n)。
|
||||
- Base64 编解码：在浏览器与 Node 环境均可用 base64-js，性能稳定。
|
||||
- CBC/ECB 选择：CBC 增加链式处理，但无额外显著性能损耗；ECB 更简单但安全性较低。
|
||||
- 建议：
|
||||
- 对大文本分块处理（当前实现按块处理，已具备良好扩展性）。
|
||||
- 在浏览器端避免频繁重复加密，必要时缓存结果。
|
||||
- 使用 CBC 模式并确保 IV 正确（当前实现要求 16 字节 IV，否则抛错）。
|
||||
|
||||
## 故障排查指南
|
||||
- “iv 错误”异常
|
||||
- 现象：CBC 模式下抛出 iv 错误。
|
||||
- 原因：未正确传入 16 字节 IV 或未传入 IV。
|
||||
- 处理：确保传入长度为 16 的 IV，或切换至 ECB 模式。
|
||||
- 参考路径：[TsSM4.js:345-347](file://src/utils/TsSM4.js#L345-L347)、[TsSM4.js:410-412](file://src/utils/TsSM4.js#L410-L412)
|
||||
- “密钥长度不为 16 字节”
|
||||
- 现象：构造 SM4 实例时抛出密钥长度错误。
|
||||
- 原因：base64Key 解码后不是 16 字节。
|
||||
- 处理：确认 base64Key 来自后端并符合规范。
|
||||
- 参考路径：[TsSM4.js:103-105](file://src/utils/TsSM4.js#L103-L105)
|
||||
- “响应未解密”
|
||||
- 现象：响应未按预期解密。
|
||||
- 原因：响应未标记为加密或密钥不一致。
|
||||
- 处理：确认后端响应标记 encrypt 且密钥一致。
|
||||
- 参考路径：[TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
|
||||
- “加密开关无效”
|
||||
- 现象：请求未加密。
|
||||
- 原因：加密开关未启用或未持久化。
|
||||
- 处理：调用 saveEncryptBody(true) 并确认存储生效。
|
||||
- 参考路径：[TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)、[TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
|
||||
|
||||
章节来源
|
||||
- [TsSM4.js:103-105](file://src/utils/TsSM4.js#L103-L105)
|
||||
- [TsSM4.js:345-347](file://src/utils/TsSM4.js#L345-L347)
|
||||
- [TsSM4.js:410-412](file://src/utils/TsSM4.js#L410-L412)
|
||||
- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
|
||||
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||||
|
||||
## 结论
|
||||
本加密模块以 TsCrypto 为核心，结合 TsSM4 的 SM4 算法实现，提供了 CBC/ECB 模式、Base64 编解码、PKCS#7 填充与去填充、UTF-8 字符串编解码能力，并与全局配置系统、存储系统、HTTP 请求模块形成完整闭环。通过加密开关与 token 注入，满足了请求体加密与安全传输的常见需求。建议在生产环境中优先使用 CBC 模式并妥善管理 IV 与密钥，遵循最小暴露原则与安全最佳实践。
|
||||
|
||||
## 附录
|
||||
|
||||
### API 接口文档
|
||||
- TsCrypto.encrypt(content)
|
||||
- 功能：对明文字符串进行加密，返回 Base64 字符串。
|
||||
- 输入：明文字符串。
|
||||
- 输出：Base64 密文字符串。
|
||||
- 参考路径：[TsCrypto.js:19-21](file://src/utils/TsCrypto.js#L19-L21)、[TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
- TsCrypto.decrypt(base64)
|
||||
- 功能：对 Base64 密文进行解密，返回明文字符串。
|
||||
- 输入：Base64 密文字符串。
|
||||
- 输出：明文字符串。
|
||||
- 参考路径：[TsCrypto.js:28-30](file://src/utils/TsCrypto.js#L28-L30)、[TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
|
||||
- TsSM4.encrypt(plaintext)
|
||||
- 功能：支持 CBC/ECB 模式、Base64/text 输出、UTF-8 编解码与 PKCS#7 填充。
|
||||
- 输入：明文字符串。
|
||||
- 输出：Base64 或 UTF-8 字符串（取决于 cipherType）。
|
||||
- 参考路径：[TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
- TsSM4.decrypt(ciphertext)
|
||||
- 功能：支持 CBC/ECB 模式、Base64/text 输入、UTF-8 编解码与 PKCS#7 去填充。
|
||||
- 输入：Base64 或 UTF-8 密文字符串。
|
||||
- 输出：明文字符串。
|
||||
- 参考路径：[TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
|
||||
- TsGlobalConfig.getConfig()/setConfig(obj)
|
||||
- 功能：读取/设置全局配置，包括 base64Key、prefix、httpParams、onHttpError。
|
||||
- 参考路径：[TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)
|
||||
- TsStorage.saveEncryptBody(bool)/getEncryptBody()
|
||||
- 功能：设置/获取加密开关，影响 HTTP 请求是否加密请求体。
|
||||
- 参考路径：[TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||||
- TsHttpUtil.post/get/form(req)
|
||||
- 功能：统一发起 HTTP 请求，自动处理加密开关、请求体加密、响应体解密、token 注入。
|
||||
- 参考路径：[TsHttpUtil.js:152-165](file://src/https/TsHttpUtil.js#L152-L165)
|
||||
|
||||
### 使用示例
|
||||
- 启用请求体加密
|
||||
- 设置加密开关：调用 saveEncryptBody(true)。
|
||||
- 发送请求：post(url, data) 自动将 data 包装为 { encryptData: TsCrypto.encrypt(JSON.stringify(data)) }。
|
||||
- 参考路径：[TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)、[TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
|
||||
- 响应体解密
|
||||
- 若后端响应标记为加密，则自动调用 TsCrypto.decrypt 并尝试 JSON 解析。
|
||||
- 参考路径：[TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
|
||||
- 自定义密钥与前缀
|
||||
- 通过 setConfig({ base64Key, prefix }) 配置密钥与请求前缀。
|
||||
- 参考路径：[TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)、[TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
|
||||
|
||||
### 安全最佳实践
|
||||
- CBC 模式
|
||||
- 使用 16 字节 IV，建议随机生成并随消息传输或在协议中约定。
|
||||
- 避免重复使用相同的 IV 与密钥组合。
|
||||
- ECB 模式
|
||||
- 不适用于长文本或存在重复明文的场景，易泄露模式特征。
|
||||
- 密钥管理
|
||||
- base64Key 应来自可信后端，定期轮换；避免硬编码在前端。
|
||||
- 响应校验
|
||||
- 对响应进行完整性校验（如 HMAC），防止篡改。
|
||||
- 日志与调试
|
||||
- 生产环境避免打印密文与敏感信息；仅在开发环境启用严格日志级别。
|
||||
507
.qoder/repowiki/zh/content/核心模块/存储模块 (TsStorage).md
Normal file
507
.qoder/repowiki/zh/content/核心模块/存储模块 (TsStorage).md
Normal file
@@ -0,0 +1,507 @@
|
||||
# 存储模块 (TsStorage)
|
||||
|
||||
<cite>
|
||||
**本文引用的文件列表**
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [TsCommon.js](file://src/utils/TsCommon.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件为存储模块（TsStorage）的完整数据持久化文档，聚焦于基于浏览器 localStorage 的数据存储机制，涵盖以下主题：
|
||||
- 数据序列化与反序列化流程
|
||||
- 用户 token 管理
|
||||
- 加密开关控制与数据生命周期管理
|
||||
- 与加密模块（SM4/加密器）的集成关系
|
||||
- 数据安全传输与存储最佳实践
|
||||
- 完整 API 接口说明（保存、获取、删除等）
|
||||
- 使用示例、数据迁移策略与备份恢复方案
|
||||
- 浏览器兼容性与存储容量限制
|
||||
|
||||
## 项目结构
|
||||
该工具包采用“按功能域分层”的组织方式，存储模块位于 utils 目录下，并通过 index.js 汇总导出，供上层业务统一调用。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "工具包入口"
|
||||
IDX["index.js"]
|
||||
end
|
||||
subgraph "存储层"
|
||||
TS["TsStorage.js"]
|
||||
TC["TsCommon.js"]
|
||||
end
|
||||
subgraph "加密层"
|
||||
TG["TsGlobalConfig.js"]
|
||||
TSM["TsSM4.js"]
|
||||
TCR["TsCrypto.js"]
|
||||
end
|
||||
subgraph "网络层"
|
||||
TH["TsHttpUtil.js"]
|
||||
end
|
||||
IDX --> TS
|
||||
IDX --> TCR
|
||||
IDX --> TSM
|
||||
IDX --> TG
|
||||
IDX --> TH
|
||||
TH --> TS
|
||||
TH --> TCR
|
||||
TH --> TG
|
||||
TS --> TC
|
||||
TCR --> TSM
|
||||
TCR --> TG
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [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)
|
||||
- [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)
|
||||
|
||||
## 核心组件
|
||||
- 存储模块（TsStorage）：封装 localStorage 的读写、token 管理、加密开关管理，提供统一的键值存取接口。
|
||||
- 加密模块（TsCrypto + TsSM4）：基于 SM4 算法的加解密实现，支持 ECB 模式与 Base64 输出。
|
||||
- 全局配置（TsGlobalConfig）：提供 base64Key、前缀、HTTP 参数注入与错误回调等全局配置。
|
||||
- 通用工具（TsCommon）：提供 JSON 解析、空值判断等基础能力。
|
||||
- 网络工具（TsHttpUtil）：在请求中自动注入 token 与加密开关，对响应进行解密与解析。
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
|
||||
## 架构总览
|
||||
存储模块与加密模块的交互路径如下：网络层在发送请求时根据加密开关对请求体进行加密；接收响应时若标记为加密，则进行解密并解析 JSON；存储层负责持久化 token 与加密开关状态。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as "应用"
|
||||
participant Http as "TsHttpUtil"
|
||||
participant Store as "TsStorage"
|
||||
participant Crypto as "TsCrypto"
|
||||
participant SM4 as "TsSM4"
|
||||
participant Srv as "后端服务"
|
||||
App->>Store : "saveUserToken(token)"
|
||||
App->>Store : "saveEncryptBody(true/false)"
|
||||
App->>Http : "post(url, data)"
|
||||
Http->>Store : "getEncryptBody()"
|
||||
alt "加密开启"
|
||||
Http->>Crypto : "encrypt(JSON.stringify(data))"
|
||||
Crypto->>SM4 : "encrypt(明文)"
|
||||
SM4-->>Crypto : "密文(Base64)"
|
||||
Crypto-->>Http : "密文"
|
||||
Http->>Srv : "POST { encryptData : 密文 }"
|
||||
else "加密关闭"
|
||||
Http->>Srv : "POST 原始 JSON"
|
||||
end
|
||||
Srv-->>Http : "响应(可能含 encrypt 标记)"
|
||||
alt "响应需解密"
|
||||
Http->>Crypto : "decrypt(密文)"
|
||||
Crypto->>SM4 : "decrypt(密文)"
|
||||
SM4-->>Crypto : "明文"
|
||||
Crypto-->>Http : "明文"
|
||||
Http->>Http : "parseJSON(明文)"
|
||||
end
|
||||
Http-->>App : "{ data, recordsTotal }"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsHttpUtil.js:80-91](file://src/https/TsHttpUtil.js#L80-L91)
|
||||
- [TsHttpUtil.js:117-123](file://src/https/TsHttpUtil.js#L117-L123)
|
||||
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||||
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
|
||||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 存储模块（TsStorage）
|
||||
- 功能职责
|
||||
- 统一的键值存取：将任意值序列化为 JSON 字符串后写入 localStorage。
|
||||
- 用户 token 管理：提供保存与读取 token 的便捷方法。
|
||||
- 加密开关管理：保存/读取“是否对请求体进行加密”的布尔标志。
|
||||
- 安全反序列化：通过通用工具解析 JSON，避免异常导致崩溃。
|
||||
- 关键实现要点
|
||||
- 写入：以 {data: value} 的结构写入 localStorage，便于后续统一解析。
|
||||
- 读取：从 localStorage 读取字符串，交由通用工具解析为对象，再取出 data 字段；未命中或解析失败时返回默认值。
|
||||
- token 与加密开关：分别以固定键名保存，便于网络层直接读取。
|
||||
- 错误处理
|
||||
- 读取失败或 JSON 解析异常时，返回默认值，保证健壮性。
|
||||
- 性能与复杂度
|
||||
- 写入/读取均为 O(1)，序列化/反序列化为 O(n)（n 为字符串长度）。
|
||||
- 使用建议
|
||||
- 对大对象建议在上层进行拆分或压缩，避免 localStorage 膨胀。
|
||||
- 避免存储敏感信息（如明文密码），优先使用加密开关与服务端保护。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["函数入口"]) --> SaveGet{"save 或 get?"}
|
||||
SaveGet --> |save| Serialize["JSON.stringify({data: value})"]
|
||||
Serialize --> Write["localStorage.setItem(key, 字符串)"]
|
||||
SaveGet --> |get| Read["localStorage.getItem(key)"]
|
||||
Read --> Parse["Common.parseJSON(字符串, {data: 默认值})"]
|
||||
Parse --> Extract["取 data 字段"]
|
||||
Extract --> End(["返回结果"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||||
|
||||
### 加密模块（TsCrypto + TsSM4）
|
||||
- 功能职责
|
||||
- 提供 SM4 加密与解密能力，支持 ECB 模式与 Base64 输出。
|
||||
- 通过全局配置注入密钥（base64 编码），确保前后端一致。
|
||||
- 关键实现要点
|
||||
- 初始化：从全局配置读取 base64Key 并转换为字节数组作为密钥。
|
||||
- 模式与输出：默认 ECB 模式与 Base64 输出，满足前端直传需求。
|
||||
- 块处理：按 16 字节块进行填充、轮密钥变换与输出转换。
|
||||
- 安全性
|
||||
- ECB 模式适合小数据块加密，但不提供完整性校验；建议仅用于请求体加密场景。
|
||||
- 密钥来源于全局配置，需确保其安全性与一致性。
|
||||
- 性能与复杂度
|
||||
- 单次加/解密为 O(n)（n 为数据长度），块大小固定为 16 字节。
|
||||
- 使用建议
|
||||
- 对大文本建议分片处理，避免一次性内存压力。
|
||||
- 与网络层配合使用，避免在本地重复加密。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TsCrypto {
|
||||
+constructor()
|
||||
+encrypt(content) string
|
||||
+decrypt(base64) string
|
||||
-sm4 : TsSM4
|
||||
}
|
||||
class TsSM4 {
|
||||
+constructor(config)
|
||||
+encrypt(plaintext) string
|
||||
+decrypt(ciphertext) string
|
||||
-mode : string
|
||||
-cipherType : string
|
||||
-key : Uint8Array
|
||||
-iv : Uint8Array
|
||||
-encryptRoundKeys : Uint32Array
|
||||
-decryptRoundKeys : Uint32Array
|
||||
}
|
||||
TsCrypto --> TsSM4 : "组合"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
|
||||
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
|
||||
|
||||
章节来源
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
|
||||
|
||||
### 网络层与存储/加密集成（TsHttpUtil）
|
||||
- 功能职责
|
||||
- 在请求前根据加密开关对请求体进行加密，并替换为 { encryptData: 密文 }。
|
||||
- 在响应后根据响应标记进行解密，并解析 JSON。
|
||||
- 自动注入 token 到请求头。
|
||||
- 关键流程
|
||||
- 请求前处理：读取加密开关，若开启则对 data 进行加密；读取 token 注入到 headers。
|
||||
- 响应后处理：若响应标记为加密，则解密并解析 JSON；否则直接返回 data。
|
||||
- 错误处理
|
||||
- 统一错误处理器返回标准化错误对象。
|
||||
- 性能与复杂度
|
||||
- 主要开销在 JSON 序列化/反序列化与 SM4 加解密，整体为 O(n)。
|
||||
- 使用建议
|
||||
- 通过全局配置统一设置加密开关与密钥，避免分散配置。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "调用方"
|
||||
participant H as "TsHttpUtil"
|
||||
participant S as "TsStorage"
|
||||
participant E as "TsCrypto"
|
||||
participant M as "TsSM4"
|
||||
participant R as "后端"
|
||||
C->>H : "post(url, {data})"
|
||||
H->>S : "getEncryptBody()"
|
||||
alt "加密开启"
|
||||
H->>E : "encrypt(JSON.stringify(data))"
|
||||
E->>M : "encrypt(明文)"
|
||||
M-->>E : "密文"
|
||||
E-->>H : "密文"
|
||||
H->>R : "POST { encryptData : 密文 }"
|
||||
else "加密关闭"
|
||||
H->>R : "POST { data }"
|
||||
end
|
||||
R-->>H : "响应(可能含 encrypt 标记)"
|
||||
alt "响应需解密"
|
||||
H->>E : "decrypt(密文)"
|
||||
E->>M : "decrypt(密文)"
|
||||
M-->>E : "明文"
|
||||
E-->>H : "明文"
|
||||
H->>H : "parseJSON(明文)"
|
||||
end
|
||||
H-->>C : "{ data, recordsTotal }"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
|
||||
- [TsHttpUtil.js:117-123](file://src/https/TsHttpUtil.js#L117-L123)
|
||||
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||||
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
|
||||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
|
||||
### API 接口文档（存储模块）
|
||||
- 保存用户 token
|
||||
- 方法：saveUserToken(token)
|
||||
- 作用：将 token 以固定键名保存至 localStorage
|
||||
- 返回：无
|
||||
- 参考：[TsStorage.js:9-11](file://src/utils/TsStorage.js#L9-L11)
|
||||
- 获取用户 token
|
||||
- 方法：getUserToken()
|
||||
- 作用：从 localStorage 读取 token，未命中返回空字符串
|
||||
- 返回：字符串
|
||||
- 参考：[TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)
|
||||
- 开启/关闭请求体加密
|
||||
- 方法：saveEncryptBody(bool)
|
||||
- 作用：保存布尔值以控制请求体是否加密
|
||||
- 返回：无
|
||||
- 参考：[TsStorage.js:17-19](file://src/utils/TsStorage.js#L17-L19)
|
||||
- 读取加密开关
|
||||
- 方法：getEncryptBody()
|
||||
- 作用：读取加密开关，未命中返回默认 true
|
||||
- 返回：布尔值
|
||||
- 参考：[TsStorage.js:21-23](file://src/utils/TsStorage.js#L21-L23)
|
||||
- 通用保存
|
||||
- 方法：save(key, value)
|
||||
- 作用：将任意值序列化后保存至 localStorage
|
||||
- 返回：无
|
||||
- 参考：[TsStorage.js:31-33](file://src/utils/TsStorage.js#L31-L33)
|
||||
- 通用获取
|
||||
- 方法：get(key, def)
|
||||
- 作用：从 localStorage 读取并解析 JSON，返回 data 字段
|
||||
- 返回：任意类型（默认值为传入 def）
|
||||
- 参考：[TsStorage.js:41-43](file://src/utils/TsStorage.js#L41-L43)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
|
||||
### 数据序列化与反序列化
|
||||
- 序列化
|
||||
- 将任意值包装为 {data: value}，再通过 JSON.stringify 转为字符串，写入 localStorage。
|
||||
- 优点：统一结构，便于后续解析；可扩展字段（如版本号）。
|
||||
- 参考：[TsStorage.js:31-33](file://src/utils/TsStorage.js#L31-L33)
|
||||
- 反序列化
|
||||
- 从 localStorage 读取字符串，使用通用工具解析为对象，取 data 字段作为实际值。
|
||||
- 若解析失败或未命中，返回默认值（def）。
|
||||
- 参考：[TsStorage.js:41-43](file://src/utils/TsStorage.js#L41-L43), [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||||
|
||||
### 用户 token 管理
|
||||
- 存储位置：固定键名为 token
|
||||
- 读写接口：saveUserToken/getUserToken
|
||||
- 使用场景：网络层在请求头中注入 token，实现鉴权
|
||||
- 参考：[TsStorage.js:9-15](file://src/utils/TsStorage.js#L9-L15), [TsHttpUtil.js:109-111](file://src/https/TsHttpUtil.js#L109-L111)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsHttpUtil.js:109-111](file://src/https/TsHttpUtil.js#L109-L111)
|
||||
|
||||
### 加密开关控制与数据生命周期
|
||||
- 加密开关
|
||||
- 保存键名：encrypt_body
|
||||
- 默认值：true（开启加密）
|
||||
- 作用：控制网络层是否对请求体进行加密
|
||||
- 参考：[TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23), [TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
|
||||
- 生命周期
|
||||
- 保存：saveEncryptBody(bool)
|
||||
- 读取：getEncryptBody()，未命中返回 true
|
||||
- 删除：localStorage.removeItem("encrypt_body")
|
||||
- 参考：[TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsHttpUtil.js:80-91](file://src/https/TsHttpUtil.js#L80-L91)
|
||||
|
||||
### 存储模块与加密模块的集成关系
|
||||
- 网络层在请求前读取加密开关，决定是否对 data 进行加密。
|
||||
- 响应后若标记为加密，网络层进行解密并解析 JSON。
|
||||
- 存储层负责持久化 token 与加密开关，形成闭环。
|
||||
- 参考：[TsHttpUtil.js:80-91](file://src/https/TsHttpUtil.js#L80-L91), [TsHttpUtil.js:117-123](file://src/https/TsHttpUtil.js#L117-L123), [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
|
||||
### 数据安全传输与存储最佳实践
|
||||
- 传输安全
|
||||
- 使用加密开关对请求体进行加密，避免明文在网络中传输。
|
||||
- 仅对必要字段加密，避免过度加密影响性能。
|
||||
- 参考：[TsHttpUtil.js:80-91](file://src/https/TsHttpUtil.js#L80-L91)
|
||||
- 存储安全
|
||||
- 不在 localStorage 中存储敏感明文（如密码、私钥）。
|
||||
- 使用加密开关保护本地缓存的敏感数据。
|
||||
- 参考：[TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||||
- 配置安全
|
||||
- 密钥来源于全局配置，需确保其保密性与一致性。
|
||||
- 参考：[TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29), [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
|
||||
|
||||
章节来源
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
|
||||
### 使用示例
|
||||
- 保存与读取普通数据
|
||||
- 参考：[README.md:28-41](file://README.md#L28-L41)
|
||||
- 设置加密开关
|
||||
- 参考：[README.md:12-26](file://README.md#L12-L26)
|
||||
- 保存用户 token
|
||||
- 参考：[TsStorage.js:9-15](file://src/utils/TsStorage.js#L9-L15)
|
||||
|
||||
章节来源
|
||||
- [README.md:1-43](file://README.md#L1-L43)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
|
||||
### 数据迁移策略与备份恢复
|
||||
- 迁移策略
|
||||
- 版本升级时，可在存储层增加版本字段，读取时进行兼容性处理。
|
||||
- 对历史数据进行批量重写（如重新序列化），确保新结构可用。
|
||||
- 参考：[TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||||
- 备份与恢复
|
||||
- 备份：读取所有键值并导出为 JSON 文件。
|
||||
- 恢复：导入 JSON 后逐条写入 localStorage。
|
||||
- 注意：避免在恢复过程中覆盖当前用户数据，建议先导入到临时键名，再合并。
|
||||
- 参考：[TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
|
||||
### 浏览器兼容性与存储容量限制
|
||||
- 浏览器兼容性
|
||||
- localStorage 在现代浏览器中广泛支持；在无痕模式或受限环境下可能不可用。
|
||||
- 参考：[TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||||
- 存储容量限制
|
||||
- localStorage 通常为 5–10 MB（因浏览器而异），超出会抛出异常。
|
||||
- 建议：对大对象进行分片或压缩，避免频繁写入导致溢出。
|
||||
- 参考：[TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
|
||||
## 依赖关系分析
|
||||
- 模块耦合
|
||||
- TsHttpUtil 依赖 TsStorage、TsCrypto、TsGlobalConfig，形成“网络层-存储层-加密层-配置层”的链路。
|
||||
- TsStorage 依赖 TsCommon，用于安全解析 JSON。
|
||||
- TsCrypto 依赖 TsSM4 与全局配置，提供加解密能力。
|
||||
- 外部依赖
|
||||
- base64-js：Base64 编解码与字节数组互转。
|
||||
- umi-request：HTTP 请求封装与错误处理。
|
||||
- 可能的循环依赖
|
||||
- 当前模块间无循环依赖，结构清晰。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Http["TsHttpUtil"] --> Store["TsStorage"]
|
||||
Http --> Crypto["TsCrypto"]
|
||||
Http --> Global["TsGlobalConfig"]
|
||||
Store --> Common["TsCommon"]
|
||||
Crypto --> SM4["TsSM4"]
|
||||
Crypto --> Global
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [TsHttpUtil.js:1-6](file://src/https/TsHttpUtil.js#L1-L6)
|
||||
- [TsStorage.js:1](file://src/utils/TsStorage.js#L1)
|
||||
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
|
||||
- [TsSM4.js:1](file://src/utils/TsSM4.js#L1)
|
||||
- [TsGlobalConfig.js:1-3](file://src/utils/TsGlobalConfig.js#L1-L3)
|
||||
- [TsCommon.js:1](file://src/utils/TsCommon.js#L1)
|
||||
|
||||
章节来源
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
|
||||
## 性能考量
|
||||
- 序列化/反序列化成本：O(n)，n 为字符串长度；建议对大对象进行分片或压缩。
|
||||
- 加解密成本：SM4 单次加/解密 O(n)，注意避免对频繁小数据进行重复加密。
|
||||
- I/O 成本：localStorage 读写为 O(1)，但频繁写入可能导致主线程阻塞，建议批量写入或延迟写入。
|
||||
- 建议：在业务层对热点数据进行缓存，减少重复序列化与写入。
|
||||
|
||||
## 故障排查指南
|
||||
- 读取不到数据
|
||||
- 检查键名是否正确；确认是否被覆盖或删除。
|
||||
- 参考：[TsStorage.js:41-43](file://src/utils/TsStorage.js#L41-L43)
|
||||
- JSON 解析失败
|
||||
- 检查存储内容是否为合法 JSON；确认是否被其他模块篡改。
|
||||
- 参考：[TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||||
- 加密/解密异常
|
||||
- 检查密钥是否正确；确认 ECB 模式与 Base64 输出是否匹配。
|
||||
- 参考：[TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13), [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||||
- 请求未加密
|
||||
- 检查加密开关是否开启；确认网络层是否正确读取开关。
|
||||
- 参考：[TsHttpUtil.js:80-91](file://src/https/TsHttpUtil.js#L80-L91), [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||||
|
||||
章节来源
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [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)
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
|
||||
## 结论
|
||||
TsStorage 通过统一的序列化/反序列化与键值管理，为应用提供了简洁可靠的本地存储能力；结合加密模块与网络层，实现了从传输到存储的端到端安全方案。建议在生产环境中：
|
||||
- 明确敏感数据边界，合理启用加密开关；
|
||||
- 控制存储体积，避免 localStorage 溢出；
|
||||
- 在升级时做好版本兼容与迁移策略；
|
||||
- 严格管理密钥与配置，确保一致性与安全性。
|
||||
|
||||
## 附录
|
||||
- 入口导出
|
||||
- index.js 汇总导出各模块，便于统一引入。
|
||||
- 参考：[index.js:8-15](file://index.js#L8-L15)
|
||||
- 依赖清单
|
||||
- base64-js、umi-request 等外部依赖。
|
||||
- 参考：[package.json:19-22](file://package.json#L19-L22)
|
||||
|
||||
章节来源
|
||||
- [index.js:1-16](file://index.js#L1-L16)
|
||||
- [package.json:1-24](file://package.json#L1-L24)
|
||||
516
.qoder/repowiki/zh/content/核心模块/核心模块.md
Normal file
516
.qoder/repowiki/zh/content/核心模块/核心模块.md
Normal file
@@ -0,0 +1,516 @@
|
||||
# 核心模块
|
||||
|
||||
<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. **性能监控**：定期监控加密和网络请求的性能指标
|
||||
|
||||
该工具包为前端开发提供了一个可靠、安全、易用的基础框架，适合在企业级应用中使用。
|
||||
591
.qoder/repowiki/zh/content/核心模块/通用工具模块 (TsCommon).md
Normal file
591
.qoder/repowiki/zh/content/核心模块/通用工具模块 (TsCommon).md
Normal file
@@ -0,0 +1,591 @@
|
||||
# 通用工具模块（TsCommon）
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [TsCommon.js](file://src/utils/TsCommon.js)
|
||||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||||
- [index.js](file://index.js)
|
||||
- [package.json](file://package.json)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
|
||||
通用工具模块（TsCommon）是一个专为前端开发设计的JavaScript工具库，提供了日常开发中最常用的工具函数集合。该模块采用模块化设计，支持浏览器和Node.js环境，具有以下特点：
|
||||
|
||||
- **轻量级设计**：专注于核心工具函数，避免功能冗余
|
||||
- **环境适配**：智能检测运行环境，提供跨平台兼容性
|
||||
- **错误安全**：完善的异常处理机制，确保函数调用的稳定性
|
||||
- **易于扩展**：清晰的模块接口，便于功能扩展和维护
|
||||
|
||||
该工具模块主要服务于企业级应用开发，特别是在需要统一工具函数管理的大型项目中发挥重要作用。
|
||||
|
||||
## 项目结构
|
||||
|
||||
项目采用清晰的模块化组织结构，按照功能域进行文件分类：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "项目根目录"
|
||||
Root[index.js]
|
||||
Package[package.json]
|
||||
Readme[README.md]
|
||||
end
|
||||
subgraph "源代码目录"
|
||||
Utils[src/utils/]
|
||||
Https[src/https/]
|
||||
end
|
||||
subgraph "工具模块"
|
||||
Common[TsCommon.js]
|
||||
Storage[TsStorage.js]
|
||||
Crypto[TsCrypto.js]
|
||||
SM4[TsSM4.js]
|
||||
GlobalConfig[TsGlobalConfig.js]
|
||||
HttpUtil[TsHttpUtil.js]
|
||||
end
|
||||
subgraph "HTTP模块"
|
||||
HttpUtil
|
||||
end
|
||||
Root --> Utils
|
||||
Root --> Https
|
||||
Utils --> Common
|
||||
Utils --> Storage
|
||||
Utils --> Crypto
|
||||
Utils --> SM4
|
||||
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)
|
||||
|
||||
## 核心组件
|
||||
|
||||
TsCommon模块提供了7个核心工具函数，每个函数都针对特定的开发场景进行了优化：
|
||||
|
||||
### 主要功能函数
|
||||
|
||||
| 函数名称 | 功能描述 | 返回类型 | 使用场景 |
|
||||
|---------|----------|----------|----------|
|
||||
| getParamFormUrl | 从URL中提取指定参数值 | String | URL参数解析、路由参数处理 |
|
||||
| isEmpty | 检查值是否为空 | Boolean | 数据验证、条件判断 |
|
||||
| parseJSON | 安全解析JSON字符串 | Any | 数据序列化、API响应处理 |
|
||||
| split | 分割字符串为数组 | Array | 数据处理、配置解析 |
|
||||
| isDevelopment | 检测开发环境 | Boolean | 环境配置、调试控制 |
|
||||
| replaceAll | 替换所有匹配字符 | String | 文本处理、数据清洗 |
|
||||
| endWith | 检查字符串结尾 | Boolean | 文件类型判断、路径处理 |
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||||
|
||||
## 架构概览
|
||||
|
||||
TsCommon模块采用简洁的函数式编程模式，所有工具函数都是独立的纯函数，不依赖外部状态。模块间通过明确的依赖关系协作，形成完整的工具生态系统。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "TsCommon模块"
|
||||
CommonFunctions[TsCommon.js]
|
||||
UrlParser[URL参数解析]
|
||||
ValueChecker[空值检查]
|
||||
JsonParser[JSON解析]
|
||||
StringProcessor[字符串处理]
|
||||
EnvDetector[环境检测]
|
||||
end
|
||||
subgraph "依赖模块"
|
||||
Storage[TsStorage.js]
|
||||
Crypto[TsCrypto.js]
|
||||
GlobalConfig[TsGlobalConfig.js]
|
||||
SM4[TsSM4.js]
|
||||
end
|
||||
subgraph "上层应用"
|
||||
HttpUtil[TsHttpUtil.js]
|
||||
BusinessLogic[业务逻辑层]
|
||||
end
|
||||
CommonFunctions --> UrlParser
|
||||
CommonFunctions --> ValueChecker
|
||||
CommonFunctions --> JsonParser
|
||||
CommonFunctions --> StringProcessor
|
||||
CommonFunctions --> EnvDetector
|
||||
HttpUtil --> CommonFunctions
|
||||
HttpUtil --> Storage
|
||||
HttpUtil --> Crypto
|
||||
Crypto --> SM4
|
||||
Storage --> CommonFunctions
|
||||
BusinessLogic --> CommonFunctions
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### URL参数解析函数
|
||||
|
||||
#### getParamFormUrl函数
|
||||
|
||||
该函数专门用于从URL中提取指定的查询参数值，支持自定义主机地址和参数键名。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端
|
||||
participant Common as TsCommon
|
||||
participant Browser as 浏览器环境
|
||||
participant Regex as 正则表达式
|
||||
Client->>Common : getParamFormUrl(key, host?)
|
||||
Common->>Browser : 获取当前页面URL
|
||||
Browser-->>Common : 返回完整URL
|
||||
Common->>Regex : 创建参数匹配正则
|
||||
Regex-->>Common : 返回匹配结果
|
||||
Common->>Common : 解码URI编码值
|
||||
Common-->>Client : 返回参数值或空字符串
|
||||
Note over Common : 异常处理：解析失败返回空字符串
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsCommon.js:4-18](file://src/utils/TsCommon.js#L4-L18)
|
||||
|
||||
**函数签名**: `getParamFormUrl(key: string, host?: string): string`
|
||||
|
||||
**参数说明**:
|
||||
- `key`: 必需，要提取的参数键名
|
||||
- `host`: 可选，自定义URL地址，默认使用当前页面URL
|
||||
|
||||
**返回值**: 提取到的参数值，如果未找到则返回空字符串
|
||||
|
||||
**使用示例**:
|
||||
```javascript
|
||||
// 从当前页面URL提取参数
|
||||
const userId = Common.getParamFormUrl('userId');
|
||||
|
||||
// 从指定URL提取参数
|
||||
const token = Common.getParamFormUrl('token', 'https://api.example.com?token=abc123');
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:4-18](file://src/utils/TsCommon.js#L4-L18)
|
||||
|
||||
### 空值检查函数
|
||||
|
||||
#### isEmpty函数
|
||||
|
||||
提供统一的空值检查机制，覆盖JavaScript中常见的空值情况。
|
||||
|
||||
**函数签名**: `isEmpty(value: any): boolean`
|
||||
|
||||
**功能特性**:
|
||||
- 检测 `undefined` 值
|
||||
- 检测 `null` 值
|
||||
- 检测空字符串 `''`
|
||||
- 支持任意数据类型的空值判断
|
||||
|
||||
**使用场景**:
|
||||
- 表单数据验证
|
||||
- API响应数据处理
|
||||
- 条件渲染控制
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:25-27](file://src/utils/TsCommon.js#L25-L27)
|
||||
|
||||
### JSON解析函数
|
||||
|
||||
#### parseJSON函数
|
||||
|
||||
提供安全的JSON解析功能，包含异常处理和默认值机制。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([函数调用]) --> ParseJSON["尝试解析JSON字符串"]
|
||||
ParseJSON --> ParseSuccess{"解析成功?"}
|
||||
ParseSuccess --> |是| ValidateResult["验证解析结果"]
|
||||
ParseSuccess --> |否| UseDefault["使用默认值"]
|
||||
ValidateResult --> ResultValid{"结果有效?"}
|
||||
ResultValid --> |是| ReturnResult["返回解析结果"]
|
||||
ResultValid --> |否| UseDefault
|
||||
UseDefault --> ReturnDefault["返回默认值"]
|
||||
ReturnResult --> End([结束])
|
||||
ReturnDefault --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||||
|
||||
**函数签名**: `parseJSON(value: string, def?: any): any`
|
||||
|
||||
**参数说明**:
|
||||
- `value`: 必需，要解析的JSON字符串
|
||||
- `def`: 可选，默认返回值，默认为 `{}`
|
||||
|
||||
**返回值**: 解析后的对象或提供的默认值
|
||||
|
||||
**使用示例**:
|
||||
```javascript
|
||||
// 基本使用
|
||||
const userData = Common.parseJSON('{"name":"John"}');
|
||||
|
||||
// 自定义默认值
|
||||
const config = Common.parseJSON('invalid-json', {theme:'dark'});
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||||
|
||||
### 字符串分割函数
|
||||
|
||||
#### split函数
|
||||
|
||||
提供灵活的字符串分割功能，支持自定义分隔符。
|
||||
|
||||
**函数签名**: `split(obj: string, seq?: string): string[]`
|
||||
|
||||
**参数说明**:
|
||||
- `obj`: 必需，要分割的字符串
|
||||
- `seq`: 可选，分隔符，默认为逗号 `,`
|
||||
|
||||
**返回值**: 分割后的字符串数组
|
||||
|
||||
**使用示例**:
|
||||
```javascript
|
||||
// 默认逗号分隔
|
||||
const tags = Common.split('javascript,python,java');
|
||||
|
||||
// 自定义分隔符
|
||||
const items = Common.split('apple|banana|orange', '|');
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:51-56](file://src/utils/TsCommon.js#L51-L56)
|
||||
|
||||
### 开发环境检测函数
|
||||
|
||||
#### isDevelopment函数
|
||||
|
||||
提供统一的环境检测机制，支持多种环境配置方式。
|
||||
|
||||
**函数签名**: `isDevelopment(): boolean`
|
||||
|
||||
**功能特性**:
|
||||
- 检测 `process.env.NODE_ENV` 环境变量
|
||||
- 支持开发环境标识
|
||||
- 返回布尔值结果
|
||||
|
||||
**使用场景**:
|
||||
- 条件调试输出
|
||||
- 开发/生产环境配置切换
|
||||
- API地址环境区分
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)
|
||||
|
||||
### 字符串替换函数
|
||||
|
||||
#### replaceAll函数
|
||||
|
||||
提供全局字符串替换功能，支持正则表达式模式。
|
||||
|
||||
**函数签名**: `replaceAll(string: string, s1: string, s2: string): string`
|
||||
|
||||
**参数说明**:
|
||||
- `string`: 必需，原字符串
|
||||
- `s1`: 必需，要被替换的子字符串
|
||||
- `s2`: 必需，替换后的字符串
|
||||
|
||||
**返回值**: 替换后的字符串
|
||||
|
||||
**使用示例**:
|
||||
```javascript
|
||||
// 替换所有特殊字符
|
||||
const cleanText = Common.replaceAll('hello world!', ' ', '');
|
||||
|
||||
// HTML标签清理
|
||||
const plainText = Common.replaceAll('<p>Hello</p>', '<[^>]*>', '');
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:74-76](file://src/utils/TsCommon.js#L74-L76)
|
||||
|
||||
### 字符串结尾检查函数
|
||||
|
||||
#### endWith函数
|
||||
|
||||
提供字符串结尾检查功能，支持多字符结尾判断。
|
||||
|
||||
**函数签名**: `endWith(string?: string, endStr?: string): boolean`
|
||||
|
||||
**参数说明**:
|
||||
- `string`: 可选，要检查的字符串，默认为空字符串
|
||||
- `endStr`: 必需，要检查的结尾字符串
|
||||
|
||||
**返回值**: 如果字符串以指定后缀结尾返回true，否则false
|
||||
|
||||
**使用示例**:
|
||||
```javascript
|
||||
// 检查文件扩展名
|
||||
const isImage = Common.endWith('photo.jpg', '.jpg');
|
||||
|
||||
// 检查URL结尾
|
||||
const isApiEndpoint = Common.endWith('/api/users', '/users');
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:84-87](file://src/utils/TsCommon.js#L84-L87)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
TsCommon模块与其他模块之间存在清晰的依赖关系，形成了完整的工具生态系统。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "TsCommon核心"
|
||||
Common[TsCommon.js]
|
||||
end
|
||||
subgraph "直接依赖"
|
||||
Storage[TsStorage.js]
|
||||
Crypto[TsCrypto.js]
|
||||
GlobalConfig[TsGlobalConfig.js]
|
||||
end
|
||||
subgraph "间接依赖"
|
||||
SM4[TsSM4.js]
|
||||
Base64[base64-js]
|
||||
UmiRequest[umi-request]
|
||||
end
|
||||
subgraph "外部依赖"
|
||||
BrowserEnv[浏览器环境]
|
||||
NodeEnv[Node.js环境]
|
||||
end
|
||||
Common --> Storage
|
||||
Common --> GlobalConfig
|
||||
Storage --> Common
|
||||
Crypto --> SM4
|
||||
Crypto --> Base64
|
||||
Crypto --> GlobalConfig
|
||||
SM4 --> Base64
|
||||
HttpUtil --> Common
|
||||
HttpUtil --> Storage
|
||||
HttpUtil --> Crypto
|
||||
HttpUtil --> GlobalConfig
|
||||
HttpUtil --> UmiRequest
|
||||
Common -.-> BrowserEnv
|
||||
Common -.-> NodeEnv
|
||||
Storage -.-> BrowserEnv
|
||||
Crypto -.-> NodeEnv
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
- [package.json:19-22](file://package.json#L19-L22)
|
||||
|
||||
### 模块间交互流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as 应用程序
|
||||
participant HttpUtil as HTTP工具
|
||||
participant Storage as 存储工具
|
||||
participant Crypto as 加密工具
|
||||
participant Common as 通用工具
|
||||
App->>HttpUtil : 发起HTTP请求
|
||||
HttpUtil->>Common : 使用isEmpty检查数据
|
||||
HttpUtil->>Storage : 获取用户令牌
|
||||
Storage->>Common : 使用parseJSON解析数据
|
||||
HttpUtil->>Crypto : 加密请求数据
|
||||
Crypto->>Crypto : 使用SM4算法
|
||||
Crypto-->>HttpUtil : 返回加密结果
|
||||
HttpUtil-->>App : 返回处理后的响应
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
|
||||
- [TsStorage.js:41-43](file://src/utils/TsStorage.js#L41-L43)
|
||||
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
|
||||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||||
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 时间复杂度分析
|
||||
|
||||
| 函数 | 时间复杂度 | 空间复杂度 | 说明 |
|
||||
|------|------------|------------|------|
|
||||
| getParamFormUrl | O(n) | O(1) | n为URL长度，正则匹配 |
|
||||
| isEmpty | O(1) | O(1) | 常数时间比较 |
|
||||
| parseJSON | O(n) | O(n) | n为字符串长度，JSON解析 |
|
||||
| split | O(n) | O(n) | n为字符串长度，字符串分割 |
|
||||
| isDevelopment | O(1) | O(1) | 环境变量读取 |
|
||||
| replaceAll | O(n*m) | O(n+m) | n为原字符串长度，m为匹配次数 |
|
||||
| endWith | O(m) | O(1) | m为endStr长度 |
|
||||
|
||||
### 内存使用优化
|
||||
|
||||
1. **字符串处理优化**: 所有字符串操作都使用原生JavaScript方法，避免额外的内存分配
|
||||
2. **正则表达式复用**: URL参数解析中的正则表达式在函数内部创建，避免重复编译
|
||||
3. **异常处理**: 所有函数都有完善的异常处理，防止内存泄漏
|
||||
|
||||
### 缓存策略
|
||||
|
||||
- URL参数解析结果不进行缓存，因为每次调用可能使用不同的URL
|
||||
- 环境检测结果可缓存，但当前实现每次都重新检查以确保准确性
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### URL参数解析失败
|
||||
|
||||
**问题**: `getParamFormUrl` 返回空字符串
|
||||
**原因**:
|
||||
- URL中不存在指定参数
|
||||
- URL格式不正确
|
||||
- 浏览器环境限制
|
||||
|
||||
**解决方案**:
|
||||
```javascript
|
||||
// 检查URL格式
|
||||
const url = Common.getParamFormUrl('key', customUrl);
|
||||
if (!url) {
|
||||
console.warn('参数解析失败，检查URL格式');
|
||||
}
|
||||
|
||||
// 使用默认值
|
||||
const value = Common.getParamFormUrl('key') || defaultValue;
|
||||
```
|
||||
|
||||
#### JSON解析异常
|
||||
|
||||
**问题**: `parseJSON` 抛出异常或返回错误结果
|
||||
**原因**:
|
||||
- 输入不是有效的JSON格式
|
||||
- 字符串包含特殊字符
|
||||
|
||||
**解决方案**:
|
||||
```javascript
|
||||
// 使用try-catch处理
|
||||
let result;
|
||||
try {
|
||||
result = Common.parseJSON(jsonString);
|
||||
} catch (error) {
|
||||
console.error('JSON解析失败:', error);
|
||||
result = defaultValue;
|
||||
}
|
||||
|
||||
// 或者使用默认值机制
|
||||
const data = Common.parseJSON(invalidJson, {});
|
||||
```
|
||||
|
||||
#### 环境检测不准确
|
||||
|
||||
**问题**: `isDevelopment` 返回错误的环境信息
|
||||
**原因**:
|
||||
- `NODE_ENV` 环境变量未正确设置
|
||||
- 在浏览器环境中无法访问Node.js环境变量
|
||||
|
||||
**解决方案**:
|
||||
```javascript
|
||||
// 检查环境变量
|
||||
console.log('NODE_ENV:', process.env.NODE_ENV);
|
||||
|
||||
// 在浏览器环境中使用其他方式检测
|
||||
const isDev = typeof window !== 'undefined' &&
|
||||
window.location.hostname === 'localhost';
|
||||
```
|
||||
|
||||
### 调试技巧
|
||||
|
||||
1. **启用详细日志**: 在开发环境中使用 `isDevelopment` 函数控制日志输出
|
||||
2. **参数验证**: 在调用工具函数前验证输入参数的有效性
|
||||
3. **异常捕获**: 对可能失败的函数调用使用try-catch包装
|
||||
|
||||
**章节来源**
|
||||
- [TsCommon.js:7-17](file://src/utils/TsCommon.js#L7-L17)
|
||||
- [TsCommon.js:36-42](file://src/utils/TsCommon.js#L36-L42)
|
||||
|
||||
## 结论
|
||||
|
||||
TsCommon通用工具模块通过提供7个核心工具函数，为JavaScript开发提供了坚实的基础工具集。该模块具有以下优势：
|
||||
|
||||
1. **功能完备**: 覆盖了日常开发中最常用的工具函数
|
||||
2. **设计优雅**: 采用纯函数设计，无副作用，易于测试
|
||||
3. **环境友好**: 支持浏览器和Node.js双环境运行
|
||||
4. **错误安全**: 完善的异常处理机制，确保程序稳定性
|
||||
5. **易于扩展**: 清晰的模块接口，便于功能扩展
|
||||
|
||||
该模块特别适用于需要统一工具函数管理的企业级应用开发，能够显著提高开发效率和代码质量。通过合理的依赖管理和模块化设计，TsCommon为整个工具库生态系统奠定了坚实的基础。
|
||||
|
||||
## 附录
|
||||
|
||||
### API参考表
|
||||
|
||||
#### URL处理函数
|
||||
|
||||
| 函数名 | 参数 | 返回值 | 描述 |
|
||||
|--------|------|--------|------|
|
||||
| getParamFormUrl | `(key: string, host?: string)` | `string` | 从URL中提取参数值 |
|
||||
| endWith | `(string?: string, endStr?: string)` | `boolean` | 检查字符串是否以指定后缀结尾 |
|
||||
|
||||
#### 数据处理函数
|
||||
|
||||
| 函数名 | 参数 | 返回值 | 描述 |
|
||||
|--------|------|--------|------|
|
||||
| isEmpty | `(value: any)` | `boolean` | 检查值是否为空 |
|
||||
| parseJSON | `(value: string, def?: any)` | `any` | 安全解析JSON字符串 |
|
||||
| split | `(obj: string, seq?: string)` | `string[]` | 分割字符串为数组 |
|
||||
|
||||
#### 字符串处理函数
|
||||
|
||||
| 函数名 | 参数 | 返回值 | 描述 |
|
||||
|--------|------|--------|------|
|
||||
| replaceAll | `(string: string, s1: string, s2: string)` | `string` | 替换所有匹配的子字符串 |
|
||||
|
||||
#### 环境检测函数
|
||||
|
||||
| 函数名 | 参数 | 返回值 | 描述 |
|
||||
|--------|------|--------|------|
|
||||
| isDevelopment | `()` | `boolean` | 检测是否为开发环境 |
|
||||
|
||||
### 最佳实践建议
|
||||
|
||||
1. **参数验证**: 在调用任何工具函数前，先使用 `isEmpty` 验证输入参数
|
||||
2. **错误处理**: 对可能失败的函数调用使用适当的异常处理机制
|
||||
3. **环境适配**: 使用 `isDevelopment` 控制开发和生产环境的不同行为
|
||||
4. **性能优化**: 对于频繁调用的函数，考虑缓存结果以提高性能
|
||||
5. **代码复用**: 将常用的工具函数组合成更高层的业务函数
|
||||
|
||||
### 版本兼容性
|
||||
|
||||
- **Node.js版本**: 支持Node.js 12及以上版本
|
||||
- **浏览器兼容**: 支持现代浏览器（Chrome 60+, Firefox 55+, Safari 11+）
|
||||
- **ES版本**: 使用ES6+语法，需要相应的转译配置
|
||||
Reference in New Issue
Block a user