12 KiB
12 KiB
全局配置模块 (TsGlobalConfig)
**本文引用的文件列表** - [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)目录
简介
本文件面向全局配置模块（TsGlobalConfig），系统性阐述其在工具包中的核心地位与作用，以及与网络请求、加解密、存储等模块的集成关系。文档重点覆盖：
- 默认配置与动态更新机制
- 配置项类型、作用域与优先级规则
- 完整的配置 API 使用说明
- 配置示例、最佳实践与常见场景
- 错误处理回调与配置验证逻辑
项目结构
该工具包采用按功能模块划分的组织方式，TsGlobalConfig 作为全局配置中心，被网络请求、加解密、存储等模块以依赖形式使用，对外通过入口文件统一导出。
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
图表来源
章节来源
核心组件
- 全局配置中心（TsGlobalConfig）
- 提供默认配置与运行时配置合并能力
- 暴露配置读取与写入接口，支持动态更新
- 网络请求模块（TsHttpUtil）
- 通过全局配置决定前缀、附加参数、错误处理回调等行为
- 加密模块（TsCrypto）
- 从全局配置读取密钥，用于 SM4 加解密
- 存储模块（TsStorage）
- 与全局配置配合控制是否启用请求体加密开关
章节来源
架构总览
TsGlobalConfig 作为“全局状态”容器，贯穿请求生命周期的关键节点：
- 请求发起前：根据配置决定 URL 前缀拼接、附加参数注入
- 请求过程中：根据配置决定是否加密请求体
- 请求完成后：根据配置调用错误处理回调
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 : "返回处理后的数据"
图表来源
详细组件分析
TsGlobalConfig 组件分析
- 默认配置
- 包含基础密钥、URL 前缀、HTTP 错误回调、附加参数函数等
- 配置读取
- 优先读取浏览器全局对象上的运行时配置；若未设置则回退到默认配置
- 配置写入
- 合并传入配置与当前配置，形成最终运行时配置
- 作用域与优先级
- 作用域：浏览器全局 window 对象
- 优先级：运行时配置 > 默认配置
- 配置项类型与用途
- base64Key：SM4 密钥（Base64 字符串），用于加密/解密
- prefix：字符串或函数，用于拼接请求 URL 前缀
- onHttpError：函数，接收后端返回的错误对象，用于统一错误处理
- httpParams：函数，返回附加参数对象，用于 GET/POST 注入
flowchart TD
Start(["开始"]) --> ReadRuntime["读取 window.httpConfig"]
ReadRuntime --> HasRuntime{"是否存在运行时配置？"}
HasRuntime -- "是" --> Merge["合并默认配置与运行时配置"]
HasRuntime -- "否" --> UseDefault["使用默认配置"]
Merge --> ReturnCfg["返回最终配置"]
UseDefault --> ReturnCfg
ReturnCfg --> End(["结束"])
图表来源
章节来源
TsHttpUtil 与全局配置的集成
- URL 前缀处理
- 支持字符串或函数两种形式；函数形式可按 URL 动态生成前缀
- 附加参数注入
- 若配置了 httpParams 函数，则在 GET 参数与非表单 POST 数据中注入
- 错误处理回调
- 当响应码非 200 时，调用 onHttpError 回调
- 请求体加密
- 结合存储模块的开关与全局配置的密钥，对请求体进行加密包装
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
图表来源
章节来源
TsCrypto 与全局配置的集成
- 初始化阶段
- 从全局配置读取 base64Key，并转换为字节数组
- 加解密流程
- 基于 SM4 算法，支持 ECB/CBC 模式与 Base64 输出类型
- 配置影响点
- base64Key 变更会直接影响密钥解析与后续加解密结果
classDiagram
class TsCrypto {
+constructor()
+encrypt(content)
+decrypt(base64)
}
class TsSM4 {
+constructor(config)
+encrypt(plaintext)
+decrypt(ciphertext)
}
TsCrypto --> TsSM4 : "组合使用"
图表来源
章节来源
配置 API 文档
- setConfig(obj)
- 功能：合并传入配置与当前运行时配置，形成新的全局配置
- 参数：obj 为配置对象，键值对应默认配置项
- 注意：仅影响后续请求与加密初始化
- getConfig()
- 功能：返回当前运行时配置（若未设置则回退默认配置）
- 返回：配置对象（包含 base64Key、prefix、onHttpError、httpParams）
章节来源
配置项类型、作用域与优先级
- 类型与含义
- base64Key：字符串，SM4 密钥（Base64 编码）
- prefix：字符串或函数，用于拼接请求 URL 前缀
- onHttpError：函数，接收后端返回的错误对象
- httpParams：函数，返回附加参数对象
- 作用域
- 浏览器全局 window 对象，模块间共享
- 优先级
- 运行时配置优先于默认配置；函数类型的 prefix 可按 URL 动态生效
章节来源
配置示例与最佳实践
- 示例一：设置 URL 前缀与错误回调
- 在应用启动时调用 setConfig，设置 prefix 与 onHttpError
- 之后所有请求自动拼接前缀并统一错误处理
- 示例二：启用请求体加密
- 通过存储模块保存加密开关状态
- TsHttpUtil 在发送请求时读取开关并按需加密
- 最佳实践
- 将全局配置集中初始化，避免分散设置
- prefix 使用函数形式以适配多环境
- onHttpError 中统一记录日志与用户提示
- base64Key 由后端统一管理，避免硬编码
章节来源
错误处理回调与配置验证逻辑
- 错误处理回调
- TsHttpUtil 在业务错误时调用 onHttpError，便于统一处理
- 配置验证
- TsCrypto 在构造时依赖 base64Key 的正确性
- TsSM4 在构造时校验密钥长度与 IV 长度（内部逻辑）
- 建议
- 在 setConfig 后进行一次关键配置的自检
- 对 prefix 函数进行边界测试（如空字符串、特殊字符）
章节来源
依赖关系分析
- TsHttpUtil 依赖
- TsGlobalConfig：读取前缀、附加参数、错误回调
- TsStorage：读取用户 Token、加密开关
- TsCommon：通用工具（如 JSON 解析）
- TsCrypto 依赖
- TsGlobalConfig：读取 base64Key
- TsSM4：SM4 加解密实现
- TsStorage 与 TsGlobalConfig 的间接耦合
- 通过开关控制是否启用加密，进而影响请求流程
graph LR
Http["TsHttpUtil"] --> Cfg["TsGlobalConfig"]
Http --> Sto["TsStorage"]
Http --> Com["TsCommon"]
Cry["TsCrypto"] --> Cfg
Cry --> Sm4["TsSM4"]
Sto --> Com
图表来源
章节来源
性能考量
- 配置读取成本极低，建议在请求发起前一次性读取并缓存必要字段
- prefix 为函数时，每次请求都会执行，建议在函数内做必要的缓存或短路判断
- httpParams 返回的对象会被频繁合并，建议保持对象简洁
- 加密/解密为 CPU 密集型操作，仅在必要时启用
故障排查指南
- 症状：请求未带前缀
- 排查：确认 setConfig 是否已设置 prefix；若为函数，确认返回值
- 症状：onHttpError 未触发
- 排查：确认后端返回码非 200；确认 onHttpError 是否为函数
- 症状：加密失败或解密异常
- 排查：确认 base64Key 正确；确认前后端密钥一致；确认存储开关状态
- 症状：附加参数未生效
- 排查：确认 httpParams 是否为函数；确认请求类型（GET/POST）是否匹配
章节来源
结论
TsGlobalConfig 作为工具包的“全局中枢”，通过简单而强大的配置 API，实现了对网络请求、加解密、存储等模块的统一控制。合理使用配置项与回调，可显著提升系统的可维护性与一致性。建议在应用启动阶段完成全局配置初始化，并结合错误处理与日志记录，确保问题可追踪、可恢复。
附录
- 入口导出
- index.js 将 TsGlobalConfig 与其他模块一起导出，便于外部统一引用
- 版本与依赖
- 依赖 umi-request 与 base64-js，用于网络请求与 Base64 编解码
章节来源