412 lines
12 KiB
Markdown
412 lines
12 KiB
Markdown
# 配置管理 API
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
|
||
- [TsCrypto.js](file://src/utils/TsCrypto.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. [结论](#结论)
|
||
|
||
## 简介
|
||
|
||
配置管理模块是 npm-tool 包的核心基础设施，负责管理系统级的全局配置。该模块提供了统一的配置存储、读取和更新机制，支持运行时动态配置管理。通过配置管理，开发者可以灵活地控制网络请求行为、加密参数、错误处理策略等关键功能。
|
||
|
||
本模块采用单例模式设计，使用浏览器全局对象 `window.httpConfig` 作为配置存储容器，确保配置在整个应用生命周期内的持久性和一致性。配置系统支持多种配置项类型，包括基础数据类型、函数类型和回调函数类型，为不同场景提供灵活的配置选项。
|
||
|
||
## 项目结构
|
||
|
||
npm-tool 包采用模块化设计，配置管理相关的核心文件位于 `src/utils/` 目录下：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "配置管理模块"
|
||
TsGlobalConfig[TsGlobalConfig.js<br/>全局配置管理]
|
||
TsCrypto[TsCrypto.js<br/>加密工具]
|
||
TsSM4[TsSM4.js<br/>SM4算法实现]
|
||
end
|
||
subgraph "HTTP 请求模块"
|
||
TsHttpUtil[TsHttpUtil.js<br/>HTTP 请求封装]
|
||
end
|
||
subgraph "存储模块"
|
||
TsStorage[TsStorage.js<br/>本地存储]
|
||
end
|
||
subgraph "工具模块"
|
||
TsCommon[TsCommon.js<br/>通用工具]
|
||
end
|
||
subgraph "入口文件"
|
||
Index[index.js<br/>模块导出]
|
||
Package[package.json<br/>包配置]
|
||
end
|
||
TsGlobalConfig --> TsHttpUtil
|
||
TsCrypto --> TsSM4
|
||
TsCrypto --> TsGlobalConfig
|
||
TsHttpUtil --> TsStorage
|
||
TsHttpUtil --> TsCommon
|
||
Index --> TsGlobalConfig
|
||
Index --> TsHttpUtil
|
||
Index --> TsCrypto
|
||
Index --> TsStorage
|
||
Index --> TsCommon
|
||
```
|
||
|
||
**图表来源**
|
||
- [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)
|
||
|
||
**章节来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [package.json:1-24](file://package.json#L1-L24)
|
||
|
||
## 核心组件
|
||
|
||
### 全局配置系统
|
||
|
||
全局配置系统是整个模块的核心，提供了配置的存储、读取和更新功能。系统采用默认配置与用户配置相结合的设计模式，确保在任何情况下都有可用的配置。
|
||
|
||
#### 配置项类型定义
|
||
|
||
| 配置项名称 | 类型 | 默认值 | 描述 |
|
||
|-----------|------|--------|------|
|
||
| base64Key | string | "WmdUzPJXbngVNiaSsQrihg==" | SM4 加密算法的 Base64 密钥 |
|
||
| prefix | string/function | "" | API 前缀，可为字符串或函数 |
|
||
| onHttpError | function | `(res) => {}` | HTTP 错误处理回调函数 |
|
||
| httpParams | function | `(res) => {}` | HTTP 请求参数处理函数 |
|
||
|
||
#### 配置优先级机制
|
||
|
||
配置系统采用以下优先级顺序：
|
||
|
||
1. **用户配置**：通过 `setConfig()` 设置的最新配置
|
||
2. **全局配置**：存储在 `window.httpConfig` 中的配置
|
||
3. **默认配置**：硬编码在代码中的默认值
|
||
|
||
**章节来源**
|
||
- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
|
||
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
|
||
|
||
## 架构概览
|
||
|
||
配置管理模块采用分层架构设计，确保各组件之间的松耦合和高内聚：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "配置管理层"
|
||
ConfigManager[配置管理器]
|
||
DefaultConfig[默认配置]
|
||
UserConfig[用户配置]
|
||
end
|
||
subgraph "应用层"
|
||
HttpUtil[HTTP 工具]
|
||
Crypto[加密工具]
|
||
Storage[存储工具]
|
||
end
|
||
subgraph "外部依赖"
|
||
Window[window.httpConfig]
|
||
UmiRequest[umi-request]
|
||
Base64Js[base64-js]
|
||
end
|
||
ConfigManager --> DefaultConfig
|
||
ConfigManager --> UserConfig
|
||
ConfigManager --> Window
|
||
HttpUtil --> ConfigManager
|
||
Crypto --> ConfigManager
|
||
HttpUtil --> UmiRequest
|
||
Crypto --> Base64Js
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
|
||
- [TsHttpUtil.js:100-134](file://src/https/TsHttpUtil.js#L100-L134)
|
||
- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
|
||
|
||
### 配置更新流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as 客户端代码
|
||
participant Config as 配置管理器
|
||
participant Window as window.httpConfig
|
||
participant HttpUtil as HTTP工具
|
||
Client->>Config : setConfig(新配置)
|
||
Config->>Window : 合并配置
|
||
Window-->>Config : 更新后的配置
|
||
Config-->>Client : 返回更新结果
|
||
HttpUtil->>Config : getConfig()
|
||
Config->>Window : 获取当前配置
|
||
Window-->>Config : 返回配置对象
|
||
Config-->>HttpUtil : 返回配置
|
||
HttpUtil->>HttpUtil : 使用配置执行请求
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)
|
||
- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
|
||
|
||
## 详细组件分析
|
||
|
||
### 配置管理器 (TsGlobalConfig)
|
||
|
||
配置管理器是整个系统的核心组件，负责管理全局配置的生命周期。
|
||
|
||
#### 方法签名
|
||
|
||
```javascript
|
||
// 获取当前配置
|
||
function getConfig(): ConfigObject
|
||
|
||
// 设置配置
|
||
function setConfig(obj?: Partial<ConfigObject>): void
|
||
```
|
||
|
||
#### 配置对象结构
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class ConfigObject {
|
||
+string base64Key
|
||
+string|function prefix
|
||
+function onHttpError
|
||
+function httpParams
|
||
}
|
||
class DefaultConfig {
|
||
+string base64Key = "WmdUzPJXbngVNiaSsQrihg=="
|
||
+string prefix = ""
|
||
+function onHttpError
|
||
+function httpParams
|
||
}
|
||
class GlobalConfig {
|
||
+getConfig() : ConfigObject
|
||
+setConfig(obj) : void
|
||
}
|
||
ConfigObject <|-- DefaultConfig
|
||
GlobalConfig --> ConfigObject : uses
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
|
||
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
|
||
|
||
#### 配置验证规则
|
||
|
||
配置系统实现了以下验证机制：
|
||
|
||
1. **类型验证**：确保配置项符合预期类型
|
||
2. **函数验证**：验证回调函数的可调用性
|
||
3. **密钥验证**：验证加密密钥的有效性
|
||
|
||
**章节来源**
|
||
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
|
||
|
||
### HTTP 工具集成
|
||
|
||
HTTP 工具通过配置管理器获取运行时配置，实现动态配置管理。
|
||
|
||
#### 配置使用流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([开始请求]) --> GetConfig[获取配置]
|
||
GetConfig --> CheckPrefix{检查前缀类型}
|
||
CheckPrefix --> |函数| CallPrefix[调用前缀函数]
|
||
CheckPrefix --> |字符串| UsePrefix[使用字符串前缀]
|
||
CallPrefix --> BuildURL[构建完整URL]
|
||
UsePrefix --> BuildURL
|
||
BuildURL --> AddParams[添加额外参数]
|
||
AddParams --> EncryptCheck{检查加密开关}
|
||
EncryptCheck --> |启用| EncryptData[加密数据]
|
||
EncryptCheck --> |禁用| SendRequest[发送请求]
|
||
EncryptData --> SendRequest
|
||
SendRequest --> HandleResponse[处理响应]
|
||
HandleResponse --> End([结束])
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
|
||
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
|
||
|
||
#### 配置项详细说明
|
||
|
||
| 配置项 | 类型 | 默认值 | 作用域 | 说明 |
|
||
|--------|------|--------|--------|------|
|
||
| base64Key | string | "WmdUzPJXbngVNiaSsQrihg==" | 全局 | SM4 加密算法密钥，用于数据加解密 |
|
||
| prefix | string/function | "" | HTTP 请求 | API 基础路径，支持动态函数生成 |
|
||
| onHttpError | function | `(res) => {}` | HTTP 请求 | 自定义错误处理逻辑 |
|
||
| httpParams | function | `(res) => {}` | HTTP 请求 | 动态添加请求参数 |
|
||
|
||
**章节来源**
|
||
- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
|
||
- [TsHttpUtil.js:100-134](file://src/https/TsHttpUtil.js#L100-L134)
|
||
|
||
### 加密模块集成
|
||
|
||
加密模块通过配置管理器获取密钥信息，实现安全的数据传输。
|
||
|
||
#### 加密配置流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Crypto as 加密模块
|
||
participant Config as 配置管理器
|
||
participant SM4 as SM4算法
|
||
participant Window as window对象
|
||
Crypto->>Config : getConfig()
|
||
Config->>Window : 获取base64Key
|
||
Window-->>Config : 返回密钥
|
||
Config-->>Crypto : 返回配置
|
||
Crypto->>SM4 : 初始化加密器
|
||
SM4->>Crypto : 加密器实例
|
||
Crypto-->>SM4 : 执行加密
|
||
SM4-->>Crypto : 返回加密结果
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
|
||
- [TsSM4.js:102-156](file://src/utils/TsSM4.js#L102-L156)
|
||
|
||
**章节来源**
|
||
- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
|
||
- [TsSM4.js:102-156](file://src/utils/TsSM4.js#L102-L156)
|
||
|
||
## 依赖关系分析
|
||
|
||
配置管理模块与其他模块的依赖关系如下：
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "核心依赖"
|
||
TsGlobalConfig[TsGlobalConfig.js]
|
||
TsHttpUtil[TsHttpUtil.js]
|
||
TsCrypto[TsCrypto.js]
|
||
end
|
||
subgraph "外部依赖"
|
||
umi_request[umi-request]
|
||
base64_js[base64-js]
|
||
end
|
||
subgraph "内部依赖"
|
||
TsStorage[TsStorage.js]
|
||
TsCommon[TsCommon.js]
|
||
TsSM4[TsSM4.js]
|
||
end
|
||
TsGlobalConfig --> TsHttpUtil
|
||
TsGlobalConfig --> TsCrypto
|
||
TsHttpUtil --> umi_request
|
||
TsCrypto --> base64_js
|
||
TsCrypto --> TsSM4
|
||
TsHttpUtil --> TsStorage
|
||
TsHttpUtil --> TsCommon
|
||
```
|
||
|
||
**图表来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [TsHttpUtil.js:1-6](file://src/https/TsHttpUtil.js#L1-L6)
|
||
- [TsCrypto.js:1-4](file://src/utils/TsCrypto.js#L1-L4)
|
||
|
||
### 模块导出结构
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class ExportModule {
|
||
+TsHttpUtil
|
||
+TsCommon
|
||
+TsStorage
|
||
+TsSM4
|
||
+TsCrypto
|
||
+TsGlobalConfig
|
||
}
|
||
class TsGlobalConfig {
|
||
+setConfig(obj)
|
||
+getConfig()
|
||
}
|
||
class TsHttpUtil {
|
||
+req(url, options)
|
||
+get(url, params, options)
|
||
+post(url, data, options)
|
||
+form(url, data, options)
|
||
}
|
||
ExportModule --> TsGlobalConfig
|
||
ExportModule --> TsHttpUtil
|
||
```
|
||
|
||
**图表来源**
|
||
- [index.js:8-15](file://index.js#L8-L15)
|
||
|
||
**章节来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [package.json:19-22](file://package.json#L19-L22)
|
||
|
||
## 性能考虑
|
||
|
||
配置管理模块在设计时充分考虑了性能优化：
|
||
|
||
### 缓存机制
|
||
- 配置读取采用缓存策略，避免重复的对象合并操作
|
||
- 加密器实例化后复用，减少内存分配开销
|
||
|
||
### 异步处理
|
||
- 配置更新采用异步方式，不影响主线程执行
|
||
- HTTP 请求处理支持 Promise 异步模式
|
||
|
||
### 内存管理
|
||
- 配置对象采用浅拷贝策略，减少内存占用
|
||
- 及时清理不再使用的配置引用
|
||
|
||
## 故障排除指南
|
||
|
||
### 常见配置问题
|
||
|
||
#### 配置不生效
|
||
**症状**：设置配置后，系统仍然使用默认配置
|
||
**解决方案**：
|
||
1. 确认配置对象的键名正确
|
||
2. 检查配置值的类型是否符合要求
|
||
3. 验证配置更新时机是否正确
|
||
|
||
#### 加密失败
|
||
**症状**：数据加密或解密过程中出现错误
|
||
**解决方案**：
|
||
1. 验证 base64Key 的长度是否为 16 字节
|
||
2. 检查密钥格式是否正确
|
||
3. 确认加密模式配置正确
|
||
|
||
#### HTTP 请求异常
|
||
**症状**：网络请求失败或返回错误
|
||
**解决方案**：
|
||
1. 检查 prefix 配置是否正确
|
||
2. 验证 onHttpError 回调函数逻辑
|
||
3. 确认 httpParams 函数返回正确的参数对象
|
||
|
||
**章节来源**
|
||
- [TsSM4.js:103-122](file://src/utils/TsSM4.js#L103-L122)
|
||
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
|
||
|
||
## 结论
|
||
|
||
配置管理模块为 npm-tool 包提供了强大而灵活的配置管理能力。通过统一的配置接口，开发者可以轻松地定制各种系统行为，包括网络请求、数据加密、错误处理等关键功能。
|
||
|
||
模块设计遵循了以下原则：
|
||
- **单一职责**：配置管理专注于配置的存储和读取
|
||
- **松耦合**：通过接口抽象降低模块间的依赖
|
||
- **可扩展性**：支持动态配置和运行时更新
|
||
- **安全性**：提供加密配置和参数验证机制
|
||
|
||
未来可以考虑的功能增强：
|
||
- 配置版本管理
|
||
- 配置热重载机制
|
||
- 更完善的配置验证和错误提示
|
||
- 配置持久化到本地存储 |