# 配置管理 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 包提供了强大而灵活的配置管理能力。通过统一的配置接口，开发者可以轻松地定制各种系统行为，包括网络请求、数据加密、错误处理等关键功能。

模块设计遵循了以下原则：
- **单一职责**：配置管理专注于配置的存储和读取
- **松耦合**：通过接口抽象降低模块间的依赖
- **可扩展性**：支持动态配置和运行时更新
- **安全性**：提供加密配置和参数验证机制

未来可以考虑的功能增强：
- 配置版本管理
- 配置热重载机制
- 更完善的配置验证和错误提示
- 配置持久化到本地存储