# 全局配置

<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 模块的设计理念、实现原理与使用方法，并结合 Http 请求流程、加解密链路与存储模块，给出配置项的数据类型、默认值、取值范围、动态更新机制、优先级处理逻辑、配置示例（开发/生产）、配置存储位置与访问方式、配置验证、错误处理与调试技巧。目标是帮助读者快速理解并正确使用该全局配置体系。

## 项目结构
该项目采用按功能域组织的目录结构：
- utils：通用工具与基础能力（全局配置、通用方法、存储、加解密、SM4 实现）
- https：HTTP 请求封装（基于 umi-request 的扩展）
- 根目录入口 index.js 汇总导出各模块，供上层业务统一引入

```mermaid
graph TB
subgraph "工具模块(utils)"
GC["TsGlobalConfig.js"]
CM["TsCommon.js"]
ST["TsStorage.js"]
CR["TsCrypto.js"]
SM["TsSM4.js"]
end
subgraph "HTTP模块(https)"
HT["TsHttpUtil.js"]
end
IDX["index.js"] --> GC
IDX --> CM
IDX --> ST
IDX --> CR
IDX --> SM
IDX --> HT
HT --> GC
HT --> ST
HT --> CR
CR --> GC
CR --> SM
```

图表来源
- [index.js:1-16](file://index.js#L1-L16)
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
- [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)
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)

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

## 核心组件
- 全局配置模块 TsGlobalConfig：提供默认配置、读取配置、合并覆盖配置的能力；配置最终存储于 window.httpConfig。
- HTTP 工具 TsHttpUtil：通过 GlobalConfig 读取前缀、错误回调与附加参数函数；负责请求扩展、参数处理、加解密开关、响应解析与错误回调。
- 加密模块 TsCrypto：基于 SM4 算法与 base64 密钥，从 GlobalConfig 读取 base64Key 构造密钥缓冲区，支持加密/解密。
- 存储模块 TsStorage：提供本地存储、用户 Token 与“是否加密 body”的开关读写。
- 通用模块 TsCommon：提供空值判断、JSON 解析、URL 参数解析、开发环境判断等辅助能力。

章节来源
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
- [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)

## 架构总览
下图展示全局配置在系统中的作用与交互关系：HTTP 请求在发起前读取 GlobalConfig 的 prefix、httpParams 与 onHttpError；加密模块在初始化时读取 base64Key；存储模块提供加密开关与用户 Token。

```mermaid
sequenceDiagram
participant App as "应用代码"
participant Http as "TsHttpUtil"
participant GC as "TsGlobalConfig"
participant Crypto as "TsCrypto"
participant Store as "TsStorage"
participant Net as "umi-request"
App->>Http : "调用 get/post/form"
Http->>GC : "读取 prefix / httpParams / onHttpError"
Http->>Store : "读取用户 Token"
Http->>Net : "发起请求(含 headers/token)"
Net-->>Http : "返回响应"
Http->>Http : "根据响应码处理/解密"
Http->>GC : "调用 onHttpError(res)"
Http-->>App : "Promise 返回结果"
Note over Crypto,GC : "TsCrypto 在构造时读取 base64Key"
```

图表来源
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
- [TsCrypto.js:5-13](file://src/utils/TsCrypto.js#L5-L13)
- [TsStorage.js:13-23](file://src/utils/TsStorage.js#L13-L23)

## 详细组件分析

### TsGlobalConfig 设计与实现
- 默认配置 defaultConfig
  - base64Key: 字符串，用于 SM4 密钥的 base64 编码形式
  - prefix: 字符串或函数，用于拼接请求前缀
  - onHttpError: 函数，用于统一处理 HTTP 错误
  - httpParams: 函数，用于为每次请求注入额外参数
- getConfig
  - 从 window.httpConfig 读取当前配置；若未设置则回退到 defaultConfig
- setConfig
  - 将传入对象与当前配置进行浅合并后写回 window.httpConfig

```mermaid
flowchart TD
Start(["调用 setConfig(obj)"]) --> GetCur["读取当前配置<br/>window.httpConfig 或 defaultConfig"]
GetCur --> Merge["浅合并: {...cur, ...obj}"]
Merge --> Write["写回 window.httpConfig"]
Write --> End(["完成"])
```

图表来源
- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)
- [TsGlobalConfig.js:19-21](file://src/utils/TsGlobalConfig.js#L19-L21)

章节来源
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)

### 配置项详解与使用

- base64Key
  - 类型：字符串（Base64 编码）
  - 默认值：见默认配置
  - 作用：作为 SM4 密钥的 base64 字符串，在加密模块初始化时转换为字节缓冲区
  - 取值范围：需满足 SM4 密钥长度要求（构造函数会校验长度）
  - 使用建议：生产环境务必由后端提供并保持一致；不要硬编码在前端
  - 访问方式：通过 GlobalConfig.getConfig().base64Key
  - 关联模块：TsCrypto、TsSM4

- prefix
  - 类型：字符串或函数
  - 默认值：空字符串
  - 作用：为请求 URL 添加统一前缀；若为函数，则以 URL 为参数动态计算前缀
  - 取值范围：任意字符串或可返回字符串的函数
  - 使用建议：开发环境与生产环境可通过函数区分；避免硬编码路径
  - 访问方式：通过 GlobalConfig.getConfig().prefix
  - 关联模块：TsHttpUtil

- onHttpError
  - 类型：函数
  - 默认值：空函数
  - 作用：统一处理 HTTP 响应非 200 的场景；接收响应对象
  - 取值范围：函数签名需兼容接收响应对象
  - 使用建议：可在其中记录日志、弹窗提示、跳转登录等
  - 访问方式：通过 GlobalConfig.getConfig().onHttpError(res)
  - 关联模块：TsHttpUtil

- httpParams
  - 类型：函数
  - 默认值：空函数
  - 作用：为每次请求注入额外参数；GET 请求合并到 params，非 GET 且非 form 合并到 data
  - 取值范围：函数需返回参数对象
  - 使用建议：可用于注入公共查询条件、租户信息、时间戳等
  - 访问方式：通过 GlobalConfig.getConfig().httpParams()
  - 关联模块：TsHttpUtil

章节来源
- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
- [TsHttpUtil.js:124-127](file://src/https/TsHttpUtil.js#L124-L127)
- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
- [TsSM4.js:102-106](file://src/utils/TsSM4.js#L102-L106)

### 动态更新机制与优先级
- 更新机制
  - setConfig 会将传入对象与当前配置进行浅合并，写回 window.httpConfig
  - getConfig 读取 window.httpConfig，若未设置则回退到默认配置
- 优先级
  - 传入对象 > 当前配置 > 默认配置
  - 若传入对象中某键缺失，则沿用当前配置；若当前配置也缺失，则使用默认配置
- 注意事项
  - 浅合并意味着嵌套对象不会递归合并；如需深层覆盖，应在传入对象中直接提供完整结构
  - prefix 支持函数，可在运行时根据 URL 动态决定前缀

章节来源
- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)
- [TsGlobalConfig.js:19-21](file://src/utils/TsGlobalConfig.js#L19-L21)

### 配置存储位置与访问方式
- 存储位置：window.httpConfig
- 访问方式：
  - 读取：GlobalConfig.getConfig()
  - 写入：GlobalConfig.setConfig(obj)
- 适用场景：
  - 开发环境：可注入测试前缀、日志输出的错误处理函数
  - 生产环境：注入真实域名前缀、统一鉴权头、错误上报回调

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

### 配置示例（开发/生产）

- 开发环境示例
  - 前缀：指向本地或测试服务
  - 错误处理：控制台打印
  - 附加参数：注入测试租户或调试标记
  - 加密开关：可关闭或开启（视需求而定）

- 生产环境示例
  - 前缀：指向正式域名
  - 错误处理：统一上报、登录跳转
  - 附加参数：注入用户标识、时间戳、签名等
  - 加密开关：开启加密体（encrypt_body），并确保 base64Key 与后端一致

说明：以上为使用思路与最佳实践，具体实现请参考 README 中的示例与各模块源码。

章节来源
- [README.md:12-26](file://README.md#L12-L26)
- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)

### 配置验证与错误处理
- 配置验证
  - base64Key 长度校验：SM4 构造函数会校验密钥长度为 16 字节
  - prefix 类型校验：若为函数，需确保返回字符串
  - httpParams 类型校验：需返回对象
  - onHttpError 类型校验：需为函数
- 错误处理
  - HTTP 层：统一错误处理函数 onHttpError(res)
  - 加密层：密钥不匹配或格式错误会在加密/解密阶段抛出异常
  - 存储层：本地存储失败时会降级为默认值

章节来源
- [TsSM4.js:102-106](file://src/utils/TsSM4.js#L102-L106)
- [TsHttpUtil.js:124-127](file://src/https/TsHttpUtil.js#L124-L127)
- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)

### 调试技巧
- 打印当前配置：在关键位置调用 GlobalConfig.getConfig() 输出配置快照
- 检查前缀拼接：在请求发起前打印最终 URL
- 检查附加参数：在 dealParamsBody 中断点查看 extraParams 与 options 的合并结果
- 检查加密开关：通过 TsStorage.getEncryptBody() 确认是否启用加密体
- 检查错误回调：在 onHttpError 中记录响应状态与消息，便于定位问题

章节来源
- [TsGlobalConfig.js:19-21](file://src/utils/TsGlobalConfig.js#L19-L21)
- [TsHttpUtil.js:70-91](file://src/https/TsHttpUtil.js#L70-L91)
- [TsStorage.js:21-23](file://src/utils/TsStorage.js#L21-L23)

## 依赖关系分析
- TsHttpUtil 依赖
  - GlobalConfig：读取 prefix、httpParams、onHttpError
  - Storage：读取用户 Token、加密开关
  - Crypto：在需要时对请求体进行加密
- TsCrypto 依赖
  - GlobalConfig：读取 base64Key
  - SM4：执行加解密
- index.js 汇总导出所有模块，供上层统一引入

```mermaid
graph LR
HT["TsHttpUtil"] --> GC["TsGlobalConfig"]
HT --> ST["TsStorage"]
HT --> CR["TsCrypto"]
CR --> GC
CR --> SM["TsSM4"]
IDX["index.js"] --> GC
IDX --> HT
IDX --> CR
IDX --> ST
IDX --> SM
```

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

章节来源
- [index.js:1-16](file://index.js#L1-L16)
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)

## 性能与安全考量
- 性能
  - setConfig 为浅合并，开销极低；建议仅在应用启动时进行一次全局配置
  - httpParams 为函数调用，建议避免复杂计算；必要时可缓存结果
  - 加密体仅在开启加密开关时启用，避免不必要的 CPU 开销
- 安全
  - base64Key 不要硬编码在前端；生产环境由后端下发或通过安全渠道同步
  - 建议在生产环境强制开启加密体，并定期轮换密钥
  - onHttpError 中避免泄露敏感信息

[本节为通用指导，无需特定文件来源]

## 故障排查指南
- 无法读取配置
  - 确认是否已调用 setConfig；否则 getConfig 将返回默认配置
- 前缀无效
  - 检查 prefix 是字符串还是函数；若是函数，确认其返回值为字符串
- 附加参数未生效
  - 确认 httpParams 返回对象；GET 请求合并到 params，非 GET 且非 form 合并到 data
- 加密异常
  - 检查 base64Key 是否为 16 字节对应的 Base64；确认前后端密钥一致
- 错误回调未触发
  - 确认响应码非 200；onHttpError 仅在非 200 时调用

章节来源
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
- [TsHttpUtil.js:124-127](file://src/https/TsHttpUtil.js#L124-L127)
- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
- [TsSM4.js:102-106](file://src/utils/TsSM4.js#L102-L106)

## 结论
TsGlobalConfig 提供了简洁、灵活的全局配置能力，配合 TsHttpUtil、TsCrypto、TsStorage 等模块，形成完整的请求、加解密与存储闭环。通过 window.httpConfig 统一管理配置，既保证了易用性，又兼顾了动态更新与优先级处理。建议在实际项目中：
- 在应用启动阶段集中 setConfig
- 明确区分开发/生产环境的前缀与错误处理策略
- 严格管理 base64Key，确保前后端一致
- 合理使用 httpParams 注入公共参数，避免重复代码

[本节为总结，无需特定文件来源]

## 附录

### API 一览（来自模块导出）
- index.js 汇总导出：TsHttpUtil、TsCommon、TsStorage、TsSM4、TsCrypto、TsGlobalConfig
- README.md 提供了基本使用示例（含 setConfig 与 post 调用）

章节来源
- [index.js:8-15](file://index.js#L8-L15)
- [README.md:12-26](file://README.md#L12-L26)