348 lines
14 KiB
Markdown
348 lines
14 KiB
Markdown
# 全局配置
|
||
|
||
<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) |