363 lines
12 KiB
Markdown
363 lines
12 KiB
Markdown
# 全局配置模块 (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) |