npm-tool/.qoder/repowiki/zh/content/配置指南/全局配置.md

全局配置

**本文引用的文件** - [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)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能与安全考量
8. 故障排查指南
9. 结论
10. 附录

简介

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

项目结构

该项目采用按功能域组织的目录结构：

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

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
• TsGlobalConfig.js:1-34
• TsHttpUtil.js:1-171
• TsCrypto.js:1-34
• TsSM4.js:1-456
• TsStorage.js:1-55
• TsCommon.js:1-98

章节来源

• index.js:1-16
• package.json:1-24

核心组件

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

章节来源

• TsGlobalConfig.js:1-34
• TsHttpUtil.js:1-171
• TsCrypto.js:1-34
• TsStorage.js:1-55
• TsCommon.js:1-98

架构总览

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

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
• TsGlobalConfig.js:19-29
• TsCrypto.js:5-13
• TsStorage.js:13-23

详细组件分析

TsGlobalConfig 设计与实现

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

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

图表来源

• TsGlobalConfig.js:27-29
• TsGlobalConfig.js:19-21

章节来源

• TsGlobalConfig.js:1-34

配置项详解与使用

• 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
• TsHttpUtil.js:70-88
• TsHttpUtil.js:124-127
• TsCrypto.js:8-12
• TsSM4.js:102-106

动态更新机制与优先级

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

章节来源

• TsGlobalConfig.js:27-29
• TsGlobalConfig.js:19-21

配置存储位置与访问方式

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

章节来源

• TsGlobalConfig.js:19-29

配置示例（开发/生产）

• 开发环境示例

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

• 生产环境示例

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

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

章节来源

• README.md:12-26
• TsHttpUtil.js:70-88
• TsStorage.js:17-23

配置验证与错误处理

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

章节来源

• TsSM4.js:102-106
• TsHttpUtil.js:124-127
• TsCrypto.js:8-12

调试技巧

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

章节来源

• TsGlobalConfig.js:19-21
• TsHttpUtil.js:70-91
• TsStorage.js:21-23

依赖关系分析

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

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
• TsHttpUtil.js:1-5
• TsCrypto.js:1-3

章节来源

• index.js:1-16
• TsHttpUtil.js:1-5
• TsCrypto.js:1-3

性能与安全考量

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

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

故障排查指南

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

章节来源

• TsGlobalConfig.js:19-29
• TsHttpUtil.js:70-88
• TsHttpUtil.js:124-127
• TsCrypto.js:8-12
• TsSM4.js:102-106

结论

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
• README.md:12-26