# 通用工具 API

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [index.js](file://index.js)
- [TsCommon.js](file://src/utils/TsCommon.js)
- [TsCrypto.js](file://src/utils/TsCrypto.js)
- [TsSM4.js](file://src/utils/TsSM4.js)
- [TsStorage.js](file://src/utils/TsStorage.js)
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

这是一个功能丰富的 JavaScript 工具包，提供了多种实用的工具函数和组件，主要用于 Web 应用开发中的常见需求。该工具包包含了字符串处理、数据类型检查、URL 操作、加密解密、存储管理、HTTP 请求等功能模块。

主要特性：
- **字符串处理工具**：URL 参数解析、空值判断、JSON 解析、字符串替换、结尾判断等
- **加密解密功能**：基于 SM4 算法的加密解密工具
- **存储管理**：本地存储封装，支持对象序列化
- **HTTP 请求工具**：基于 umi-request 的网络请求封装
- **全局配置管理**：统一的配置管理和环境检测

## 项目结构

该项目采用模块化的组织方式，主要分为以下目录结构：

```mermaid
graph TB
subgraph "项目根目录"
Root[index.js<br/>主入口文件]
Package[package.json<br/>项目配置]
Readme[README.md<br/>使用说明]
end
subgraph "src/ 工具源码目录"
Utils[src/utils/<br/>通用工具模块]
Https[src/https/<br/>HTTP 工具模块]
end
subgraph "Utils 模块"
Common[TsCommon.js<br/>通用工具]
Crypto[TsCrypto.js<br/>加密工具]
SM4[TsSM4.js<br/>SM4 算法实现]
Storage[TsStorage.js<br/>存储工具]
Config[TsGlobalConfig.js<br/>全局配置]
end
subgraph "Https 模块"
HttpUtil[TsHttpUtil.js<br/>HTTP 请求工具]
end
Root --> Utils
Root --> Https
Utils --> Common
Utils --> Crypto
Utils --> SM4
Utils --> Storage
Utils --> Config
Https --> HttpUtil
```

**图表来源**
- [index.js:1-16](file://index.js#L1-L16)
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)

**章节来源**
- [index.js:1-16](file://index.js#L1-L16)
- [package.json:1-24](file://package.json#L1-L24)

## 核心组件

该工具包的核心由六个主要模块组成，每个模块都提供特定的功能领域：

### 主要模块概览

| 模块名称 | 文件路径 | 功能描述 |
|---------|----------|----------|
| TsCommon | src/utils/TsCommon.js | 通用工具函数集合 |
| TsCrypto | src/utils/TsCrypto.js | 加密解密工具 |
| TsSM4 | src/utils/TsSM4.js | SM4 算法实现 |
| TsStorage | src/utils/TsStorage.js | 本地存储管理 |
| TsGlobalConfig | src/utils/TsGlobalConfig.js | 全局配置管理 |
| TsHttpUtil | src/https/TsHttpUtil.js | HTTP 请求封装 |

### 模块依赖关系

```mermaid
graph LR
subgraph "外部依赖"
Umi[umi-request<br/>网络请求库]
Base64[base64-js<br/>Base64 编解码]
end
subgraph "内部模块"
Common[TsCommon]
Crypto[TsCrypto]
SM4[TsSM4]
Storage[TsStorage]
Config[TsGlobalConfig]
HttpUtil[TsHttpUtil]
end
HttpUtil --> Storage
HttpUtil --> Common
HttpUtil --> Crypto
HttpUtil --> Config
Crypto --> SM4
Crypto --> Config
Storage --> Common
SM4 --> Base64
HttpUtil --> Umi
```

**图表来源**
- [package.json:19-22](file://package.json#L19-L22)
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)

**章节来源**
- [package.json:19-22](file://package.json#L19-L22)
- [index.js:8-15](file://index.js#L8-L15)

## 架构概览

该工具包采用了分层架构设计，将不同功能领域的工具函数分离到独立的模块中，通过清晰的依赖关系实现松耦合的设计。

### 整体架构图

```mermaid
graph TB
subgraph "应用层"
App[业务应用]
end
subgraph "工具层"
HttpLayer[HTTP 层<br/>TsHttpUtil]
CryptoLayer[加密层<br/>TsCrypto + TsSM4]
StorageLayer[存储层<br/>TsStorage]
CommonLayer[通用层<br/>TsCommon]
end
subgraph "基础设施层"
Network[umi-request]
CryptoLib[SM4 算法]
StorageAPI[localStorage]
Encoding[base64-js]
end
App --> HttpLayer
HttpLayer --> CryptoLayer
HttpLayer --> StorageLayer
HttpLayer --> CommonLayer
CryptoLayer --> CryptoLib
CryptoLayer --> Encoding
StorageLayer --> StorageAPI
HttpLayer --> Network
```

**图表来源**
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)

### 数据流处理流程

```mermaid
sequenceDiagram
participant Client as 应用客户端
participant HttpUtil as HTTP 工具
participant Crypto as 加密模块
participant Storage as 存储模块
participant Server as 服务器
Client->>HttpUtil : 发送请求
HttpUtil->>Storage : 获取用户令牌
Storage-->>HttpUtil : 返回令牌
HttpUtil->>HttpUtil : 处理请求参数
HttpUtil->>Crypto : 加密数据(可选)
Crypto-->>HttpUtil : 返回加密结果
HttpUtil->>Server : 发送 HTTP 请求
Server-->>HttpUtil : 返回响应
HttpUtil->>Crypto : 解密响应(可选)
Crypto-->>HttpUtil : 返回解密结果
HttpUtil-->>Client : 返回处理后的数据
```

**图表来源**
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)

## 详细组件分析

### TsCommon 通用工具模块

TsCommon 模块提供了基础的工具函数，涵盖了字符串处理、数据类型检查、URL 操作等多个方面。

#### 核心 API 接口

##### getParamFormUrl - URL 参数解析

**方法签名**: `getParamFormUrl(key, host)`

**参数说明**:
- `key`: string - 要获取的 URL 参数键名
- `host`: string (可选) - 目标 URL 字符串，默认使用当前页面 URL

**返回值**: string - 匹配参数的值，未找到时返回空字符串

**使用场景**:
- 从 URL 中提取查询参数
- 处理页面分享链接中的参数
- 解析路由参数

**参数验证规则**:
- 支持任意字符串作为参数键
- host 参数可选，不传入时使用当前页面 URL

**边界条件处理**:
- URL 中无问号或无查询参数时返回空字符串
- 参数值包含特殊字符时自动解码
- URL 格式不正确时捕获异常并返回空字符串

##### isEmpty - 空值判断

**方法签名**: `isEmpty(value)`

**参数说明**:
- `value`: any - 要检查的值

**返回值**: boolean - 值为 undefined、null 或空字符串时返回 true

**使用场景**:
- 表单验证
- 数据预处理
- 条件判断

**参数验证规则**:
- 接受任意类型的参数
- 严格比较空值类型

##### parseJSON - JSON 解析

**方法签名**: `parseJSON(value, def)`

**参数说明**:
- `value`: string - 要解析的 JSON 字符串
- `def`: any (可选) - 默认返回值，默认为空对象 {}

**返回值**: any - 解析后的对象或默认值

**使用场景**:
- 安全地解析 JSON 字符串
- 处理可能损坏的 JSON 数据
- 提供默认值机制

**参数验证规则**:
- 第二个参数为可选，默认值为空对象
- 解析失败时返回默认值

**边界条件处理**:
- JSON 格式错误时捕获异常
- 解析结果为空时使用默认值

##### split - 字符串分割

**方法签名**: `split(obj, seq)`

**参数说明**:
- `obj`: string - 要分割的字符串
- `seq`: string (可选) - 分隔符，默认为逗号

**返回值**: string[] - 分割后的字符串数组

**使用场景**:
- 处理逗号分隔的列表
- 解析配置字符串
- 数据格式转换

**参数验证规则**:
- 支持任意字符串作为输入
- 分隔符可自定义

**边界条件处理**:
- 输入为 falsy 值时返回空数组
- 空字符串返回包含空字符串的数组

##### isDevelopment - 环境检测

**方法签名**: `isDevelopment()`

**参数说明**: 无

**返回值**: boolean - 当前环境为 development 时返回 true

**使用场景**:
- 开发模式下的调试输出
- 环境相关的功能开关
- 测试环境配置

**参数验证规则**:
- 依赖 Node.js 的环境变量

##### replaceAll - 全部替换

**方法签名**: `replaceAll(string, s1, s2)`

**参数说明**:
- `string`: string - 原始字符串
- `s1`: string - 要替换的子字符串
- `s2`: string - 替换后的字符串

**返回值**: string - 替换后的字符串

**使用场景**:
- 批量字符串替换
- 文本格式化
- 数据清洗

**参数验证规则**:
- 支持正则表达式的特殊字符
- 使用全局标志进行完全替换

##### endWith - 结尾判断

**方法签名**: `endWith(string, endStr)`

**参数说明**:
- `string`: string - 要检查的字符串
- `endStr`: string - 结尾字符串

**返回值**: boolean - 字符串以指定结尾时返回 true

**使用场景**:
- 文件扩展名检查
- URL 路径处理
- 字符串格式验证

**参数验证规则**:
- 支持空字符串作为输入
- 不区分大小写

**章节来源**
- [TsCommon.js:4-18](file://src/utils/TsCommon.js#L4-L18)
- [TsCommon.js:25-27](file://src/utils/TsCommon.js#L25-L27)
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
- [TsCommon.js:51-56](file://src/utils/TsCommon.js#L51-L56)
- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)
- [TsCommon.js:74-76](file://src/utils/TsCommon.js#L74-L76)
- [TsCommon.js:84-87](file://src/utils/TsCommon.js#L84-L87)

### TsCrypto 加密工具模块

TsCrypto 模块提供了基于 SM4 算法的加密解密功能，封装了底层的加密细节。

#### 核心 API 接口

##### 构造函数

**方法签名**: `new TsCrypto()`

**参数说明**: 无

**初始化过程**:
- 从全局配置获取 Base64 密钥
- 创建 SM4 实例（ECB 模式）
- 设置密文类型为 Base64

##### encrypt - 数据加密

**方法签名**: `encrypt(content)`

**参数说明**:
- `content`: string | any - 要加密的内容

**返回值**: string - 加密后的 Base64 字符串

**使用场景**:
- 敏感数据传输加密
- API 请求体加密
- 数据安全存储

**参数验证规则**:
- 自动将非字符串内容转换为 JSON 字符串
- 依赖 SM4 算法进行加密

##### decrypt - 数据解密

**方法签名**: `decrypt(base64)`

**参数说明**:
- `base64`: string - Base64 编码的密文

**返回值**: string - 解密后的原始内容

**使用场景**:
- 解密服务器返回的加密数据
- 数据恢复和验证
- 安全通信

**参数验证规则**:
- 接收 Base64 编码的密文
- 返回原始明文内容

**章节来源**
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)

### TsSM4 SM4 算法实现

TsSM4 是一个完整的 SM4 对称加密算法实现，支持 ECB 和 CBC 两种工作模式。

#### 核心 API 接口

##### 构造函数

**方法签名**: `new TsSM4(config)`

**参数说明**:
- `config`: object - 配置对象
  - `keyBuffer`: Uint8Array - 16 字节密钥缓冲区
  - `mode`: string - 加密模式，'cbc' 或 'ecb'，默认 'cbc'
  - `outType`: string - 输出类型，'base64' 或 'text'，默认 'base64'

**参数验证规则**:
- 密钥长度必须为 16 字节
- IV（初始化向量）长度必须为 16 字节（CBC 模式）
- 支持的模式：'cbc'、'ecb'
- 支持的输出类型：'base64'、'text'

##### encrypt - 数据加密

**方法签名**: `encrypt(plaintext)`

**参数说明**:
- `plaintext`: string - 要加密的明文

**返回值**: string - 加密后的密文

**使用场景**:
- 数据加密传输
- 密钥生成和管理
- 安全通信协议

**参数验证规则**:
- 自动进行 PKCS#7 填充
- 支持 UTF-8 编码
- 根据模式选择加密算法

##### decrypt - 数据解密

**方法签名**: `decrypt(ciphertext)`

**参数说明**:
- `ciphertext`: string - 要解密的密文

**返回值**: string - 解密后的明文

**使用场景**:
- 数据解密和验证
- 安全通信解码
- 数据恢复

**参数验证规则**:
- 支持 Base64 和文本两种输入格式
- 自动移除 PKCS#7 填充
- 支持 UTF-8 编码

#### SM4 算法流程图

```mermaid
flowchart TD
Start([开始加密]) --> Prepare["准备明文字节流<br/>UTF-8 编码"]
Prepare --> Padding["PKCS#7 填充<br/>16 字节对齐"]
Padding --> Mode{"选择模式"}
Mode --> |CBC| CBCInit["CBC 模式初始化<br/>IV = 16 字节"]
Mode --> |ECB| ECBInit["ECB 模式初始化<br/>无 IV"]
CBCInit --> BlockLoop["按块处理<br/>16 字节/块"]
ECBInit --> BlockLoop
BlockLoop --> XOR["与前一块密文异或<br/>(CBC)"]
XOR --> Round["32 轮加密循环"]
Round --> Output["输出密文字节流"]
Output --> Type{"输出类型"}
Type --> |Base64| Base64["Base64 编码"]
Type --> |Text| Text["UTF-8 解码"]
Base64 --> End([结束])
Text --> End
```

**图表来源**
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)

**章节来源**
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)

### TsStorage 存储工具模块

TsStorage 模块提供了本地存储的封装，支持对象的序列化和反序列化。

#### 核心 API 接口

##### save - 保存数据

**方法签名**: `save(key, value)`

**参数说明**:
- `key`: string - 存储键名
- `value`: any - 要保存的值

**返回值**: void

**使用场景**:
- 用户偏好设置保存
- 临时数据缓存
- 应用状态持久化

**参数验证规则**:
- 键名必须为字符串
- 值会被 JSON 序列化

##### get - 获取数据

**方法签名**: `get(key, def)`

**参数说明**:
- `key`: string - 存储键名
- `def`: any (可选) - 默认返回值，默认为空字符串

**返回值**: any - 存储的值或默认值

**使用场景**:
- 用户数据读取
- 应用状态恢复
- 配置信息获取

**参数验证规则**:
- 键名必须为字符串
- 支持默认值机制

##### saveUserToken - 保存用户令牌

**方法签名**: `saveUserToken(token)`

**参数说明**:
- `token`: string - 用户令牌

**返回值**: void

**使用场景**:
- 用户登录状态管理
- 认证信息存储
- 会话管理

##### getUserToken - 获取用户令牌

**方法签名**: `getUserToken()`

**参数说明**: 无

**返回值**: string - 用户令牌或空字符串

**使用场景**:
- 请求头认证
- 用户状态检查
- 权限验证

##### saveEncryptBody - 设置加密开关

**方法签名**: `saveEncryptBody(bool)`

**参数说明**:
- `bool`: boolean - 加密开关，默认 true

**返回值**: void

**使用场景**:
- 加密功能配置
- 安全策略设置
- 性能权衡

##### getEncryptBody - 获取加密开关

**方法签名**: `getEncryptBody()`

**参数说明**: 无

**返回值**: boolean - 加密开关状态

**使用场景**:
- 加密功能状态检查
- 请求前状态确认
- 安全策略验证

**章节来源**
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
- [TsStorage.js:9-23](file://src/utils/TsStorage.js#L9-L23)

### TsGlobalConfig 全局配置模块

TsGlobalConfig 模块提供了统一的配置管理功能，支持运行时配置更新。

#### 核心 API 接口

##### getConfig - 获取配置

**方法签名**: `getConfig()`

**参数说明**: 无

**返回值**: object - 当前配置对象

**配置项说明**:
- `base64Key`: string - Base64 编码的密钥，默认值为 "WmdUzPJXbngVNiaSsQrihg=="
- `prefix`: string | function - API 前缀，可以是字符串或函数
- `onHttpError`: function - HTTP 错误回调函数
- `httpParams`: function - HTTP 参数处理器

##### setConfig - 设置配置

**方法签名**: `setConfig(obj)`

**参数说明**:
- `obj`: object - 要合并的配置对象

**返回值**: void

**使用场景**:
- 应用启动时的配置初始化
- 运行时配置动态更新
- 环境相关的配置切换

**参数验证规则**:
- 支持部分配置项的更新
- 使用对象合并的方式更新配置

**章节来源**
- [TsGlobalConfig.js:5-29](file://src/utils/TsGlobalConfig.js#L5-L29)

### TsHttpUtil HTTP 请求工具

TsHttpUtil 模块基于 umi-request 提供了增强的 HTTP 请求功能，集成了加密解密、参数处理、错误处理等功能。

#### 核心 API 接口

##### req - 通用请求方法

**方法签名**: `req(url, options)`

**参数说明**:
- `url`: string - 请求地址
- `options`: object - 请求选项
  - `method`: string - HTTP 方法，默认 'GET'
  - `params`: object - 查询参数
  - `data`: object - 请求体数据
  - `headers`: object - 请求头
  - `rawResponse`: boolean - 是否返回原始响应

**返回值**: Promise<object> - 处理后的响应数据

**使用场景**:
- 统一的 HTTP 请求入口
- 复杂请求的参数处理
- 响应数据的统一格式化

##### get - GET 请求

**方法签名**: `get(url, params, options)`

**参数说明**:
- `url`: string - 请求地址
- `params`: object - 查询参数，默认 {}
- `options`: object - 请求选项，默认 {}

**返回值**: Promise<object> - 响应数据

**使用场景**:
- 数据获取请求
- 列表查询
- 资源读取

##### post - POST 请求

**方法签名**: `post(url, data, options)`

**参数说明**:
- `url`: string - 请求地址
- `data`: object - 请求体数据，默认 {}
- `options`: object - 请求选项，默认 {}

**返回值**: Promise<object> - 响应数据

**使用场景**:
- 数据创建
- 表单提交
- 资源更新

##### form - 表单提交

**方法签名**: `form(url, data, options)`

**参数说明**:
- `url`: string - 请求地址
- `data`: object - 表单数据，默认 {}
- `options`: object - 请求选项，默认 {}

**返回值**: Promise<object> - 响应数据

**使用场景**:
- 文件上传
- 表单数据提交
- 多部分数据传输

#### HTTP 请求处理流程

```mermaid
sequenceDiagram
participant Client as 客户端
participant HttpUtil as HTTP 工具
participant Config as 配置管理
participant Storage as 存储模块
participant Crypto as 加密模块
participant Request as 网络请求
Client->>HttpUtil : 发送请求
HttpUtil->>Config : 获取配置前缀
Config-->>HttpUtil : 返回前缀
HttpUtil->>HttpUtil : 处理分页参数
HttpUtil->>HttpUtil : 处理相等条件
HttpUtil->>Config : 获取额外参数
Config-->>HttpUtil : 返回额外参数
HttpUtil->>Storage : 获取用户令牌
Storage-->>HttpUtil : 返回令牌
HttpUtil->>Crypto : 加密请求体(可选)
Crypto-->>HttpUtil : 返回加密结果
HttpUtil->>Request : 发送网络请求
Request-->>HttpUtil : 返回响应
HttpUtil->>HttpUtil : 检查响应状态
HttpUtil->>Crypto : 解密响应(可选)
Crypto-->>HttpUtil : 返回解密结果
HttpUtil-->>Client : 返回处理后的数据
```

**图表来源**
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)

**章节来源**
- [TsHttpUtil.js:99-171](file://src/https/TsHttpUtil.js#L99-L171)

## 依赖分析

该工具包的依赖关系相对简单，主要依赖于两个外部库和内部模块间的协作。

### 外部依赖

| 依赖名称 | 版本 | 用途 |
|---------|------|------|
| base64-js | 1.5.1 | Base64 编解码 |
| umi-request | 1.4.0 | HTTP 请求封装 |

### 内部模块依赖

```mermaid
graph TD
subgraph "主入口"
Index[index.js]
end
subgraph "工具模块"
Common[TsCommon]
Crypto[TsCrypto]
SM4[TsSM4]
Storage[TsStorage]
Config[TsGlobalConfig]
end
subgraph "HTTP 模块"
HttpUtil[TsHttpUtil]
end
Index --> Common
Index --> Crypto
Index --> SM4
Index --> Storage
Index --> Config
Index --> HttpUtil
HttpUtil --> Storage
HttpUtil --> Common
HttpUtil --> Crypto
HttpUtil --> Config
Crypto --> SM4
Crypto --> Config
Storage --> Common
```

**图表来源**
- [index.js:1-16](file://index.js#L1-L16)
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)

### 依赖关系分析

该工具包采用了清晰的模块化设计，各模块职责明确：

1. **TsCommon** 作为基础工具模块，被其他所有模块依赖
2. **TsCrypto** 依赖 **TsSM4** 和 **TsGlobalConfig** 进行加密操作
3. **TsStorage** 依赖 **TsCommon** 进行 JSON 解析
4. **TsHttpUtil** 依赖所有其他模块进行完整的 HTTP 请求处理

**章节来源**
- [package.json:19-22](file://package.json#L19-L22)
- [index.js:1-16](file://index.js#L1-L16)

## 性能考虑

在使用该工具包时，需要考虑以下几个方面的性能影响：

### 字符串处理性能

- **URL 参数解析**: 使用正则表达式进行匹配，对于大量参数的 URL 可能影响性能
- **字符串替换**: `replaceAll` 使用全局正则表达式，复杂字符串可能影响性能
- **JSON 解析**: 大对象的序列化和反序列化可能成为性能瓶颈

### 加密解密性能

- **SM4 算法**: 32 轮加密循环，对于大文本加密会有明显的时间开销
- **Base64 编解码**: 大数据量的编码解码会影响性能
- **内存使用**: 加密解密过程中会产生中间缓冲区

### 存储性能

- **localStorage 操作**: 大对象序列化会影响存储性能
- **频繁读写**: 高频的存储操作可能影响页面响应性

### HTTP 请求优化

- **请求合并**: 合理设计 API 接口，避免不必要的请求
- **缓存策略**: 利用浏览器缓存减少重复请求
- **批量操作**: 将多个小请求合并为批量请求

## 故障排除指南

### 常见问题及解决方案

#### 1. 加密密钥错误

**问题症状**: 加密或解密时报错，提示密钥长度不正确

**解决方案**:
- 确保密钥长度为 16 字节
- 检查 Base64 编码是否正确
- 验证密钥格式符合要求

#### 2. URL 参数解析失败

**问题症状**: `getParamFormUrl` 返回空字符串

**解决方案**:
- 检查 URL 格式是否正确
- 确认参数键名拼写正确
- 验证 URL 中是否包含查询参数

#### 3. JSON 解析异常

**问题症状**: `parseJSON` 抛出异常或返回默认值

**解决方案**:
- 检查 JSON 字符串格式
- 验证字符编码是否正确
- 确认字符串不是 null 或 undefined

#### 4. HTTP 请求失败

**问题症状**: 网络请求返回错误状态

**解决方案**:
- 检查网络连接状态
- 验证 API 地址和参数
- 查看服务器响应状态码
- 检查跨域配置

#### 5. 存储数据丢失

**问题症状**: `get` 方法返回默认值而非预期数据

**解决方案**:
- 检查浏览器存储容量限制
- 验证键名是否一致
- 确认数据格式正确
- 检查浏览器隐私模式设置

### 调试技巧

1. **启用开发模式**: 使用 `isDevelopment()` 检测当前环境
2. **日志输出**: 在关键位置添加调试信息
3. **错误捕获**: 使用 try-catch 包装敏感操作
4. **单元测试**: 为关键函数编写测试用例

**章节来源**
- [TsSM4.js:103-122](file://src/utils/TsSM4.js#L103-L122)
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)

## 结论

该通用工具包提供了完整的 JavaScript 工具函数集合，具有以下特点：

### 优势

1. **模块化设计**: 清晰的功能划分，便于维护和扩展
2. **安全性**: 内置加密解密功能，支持敏感数据保护
3. **易用性**: 简洁的 API 设计，易于集成到现有项目
4. **完整性**: 覆盖了 Web 开发中的常见需求

### 使用建议

1. **合理选择加密模式**: 根据安全需求选择合适的加密算法和模式
2. **注意性能影响**: 大数据量处理时要考虑性能开销
3. **错误处理**: 建立完善的错误处理机制
4. **版本兼容**: 关注依赖库的版本更新和兼容性

### 扩展方向

1. **更多加密算法**: 可以添加 AES、RSA 等其他加密算法
2. **缓存机制**: 实现更高效的缓存策略
3. **监控功能**: 添加性能监控和错误追踪
4. **国际化支持**: 支持多语言错误消息

该工具包为 JavaScript 开发提供了坚实的基础工具集，能够有效提升开发效率和代码质量。