# 全局配置模块 (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)