Files

曾文豪 523cc777f8 docs(readme): 重构README并补充详细文档内容

2026-04-29 11:20:18 +08:00

24 KiB

Raw Permalink Blame History

通用工具 API

**本文档引用的文件** - [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)

简介

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

主要特性：

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

项目结构

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

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

图表来源

章节来源

核心组件

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

主要模块概览

模块名称	文件路径	功能描述
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 请求封装

模块依赖关系

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

图表来源

章节来源

架构概览

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

整体架构图

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

图表来源

数据流处理流程

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 : 返回处理后的数据

图表来源

详细组件分析

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 路径处理
字符串格式验证

参数验证规则:

支持空字符串作为输入
不区分大小写

章节来源

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

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 算法流程图

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

图表来源

章节来源

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 - 加密开关状态

使用场景:

加密功能状态检查
请求前状态确认
安全策略验证

章节来源

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

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

24 KiB Raw Permalink Blame History Unescape Escape

通用工具 API

目录

简介

项目结构

核心组件

主要模块概览

模块依赖关系

架构概览

整体架构图

数据流处理流程

详细组件分析

TsCommon 通用工具模块

核心 API 接口

getParamFormUrl - URL 参数解析

isEmpty - 空值判断

parseJSON - JSON 解析

split - 字符串分割

isDevelopment - 环境检测

replaceAll - 全部替换

endWith - 结尾判断

TsCrypto 加密工具模块

核心 API 接口

构造函数

encrypt - 数据加密

decrypt - 数据解密

TsSM4 SM4 算法实现

核心 API 接口

构造函数

encrypt - 数据加密

decrypt - 数据解密

SM4 算法流程图

TsStorage 存储工具模块

核心 API 接口

save - 保存数据

get - 获取数据

saveUserToken - 保存用户令牌

getUserToken - 获取用户令牌

saveEncryptBody - 设置加密开关

getEncryptBody - 获取加密开关

TsGlobalConfig 全局配置模块

核心 API 接口

getConfig - 获取配置

setConfig - 设置配置

TsHttpUtil HTTP 请求工具

核心 API 接口

req - 通用请求方法

24 KiB

Raw Permalink Blame History