# 配置指南

<cite>
**本文档引用的文件**
- [package.json](file://package.json)
- [README.md](file://README.md)
- [index.js](file://index.js)
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
- [TsCrypto.js](file://src/utils/TsCrypto.js)
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
- [TsSM4.js](file://src/utils/TsSM4.js)
- [TsStorage.js](file://src/utils/TsStorage.js)
- [TsCommon.js](file://src/utils/TsCommon.js)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心配置组件](#核心配置组件)
4. [架构概览](#架构概览)
5. [详细配置分析](#详细配置分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

npm-tool 是一个基于 Node.js 的工具包，提供了网络请求、数据加密、存储管理和通用工具等功能。该工具包的核心特性包括：

- **全局配置管理**：支持通过 window 对象进行全局配置
- **数据加密功能**：基于 SM4 算法的端到端数据加密
- **HTTP 请求封装**：基于 umi-request 的网络请求工具
- **本地存储管理**：提供用户令牌和加密开关的持久化存储
- **环境适配**：支持开发和生产环境的差异化配置

## 项目结构

该项目采用模块化的文件组织方式，主要分为以下几个核心目录：

```mermaid
graph TB
subgraph "项目根目录"
PJSON[package.json]
README[README.md]
INDEX[index.js]
end
subgraph "源代码目录 (src/)"
HTTPS[https/]
UTILS[utils/]
end
subgraph "HTTPS 模块"
HTTP[TsHttpUtil.js]
end
subgraph "工具模块"
COMMON[TsCommon.js]
CRYPTO[TsCrypto.js]
GLOBAL[TsGlobalConfig.js]
SM4[TsSM4.js]
STORAGE[TsStorage.js]
end
INDEX --> HTTP
INDEX --> COMMON
INDEX --> CRYPTO
INDEX --> GLOBAL
INDEX --> SM4
INDEX --> STORAGE
HTTP --> STORAGE
HTTP --> COMMON
HTTP --> CRYPTO
HTTP --> GLOBAL
CRYPTO --> GLOBAL
CRYPTO --> SM4
```

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

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

## 核心配置组件

### 全局配置系统

全局配置系统是整个工具包的核心配置中心，提供了统一的配置管理和覆盖机制。

#### 配置结构定义

全局配置包含以下核心参数：

| 配置项 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `base64Key` | String | `"WmdUzPJXbngVNiaSsQrihg=="` | SM4 加密算法的基础密钥 |
| `prefix` | String/Function | `""` | API 请求前缀，可为字符串或函数 |
| `onHttpError` | Function | `() => {}` | HTTP 错误回调处理器 |
| `httpParams` | Function | `() => {}` | 额外 HTTP 参数生成器 |

#### 配置优先级机制

```mermaid
flowchart TD
A[应用启动] --> B[加载默认配置]
B --> C[检查 window.httpConfig]
C --> D{存在自定义配置?}
D --> |是| E[合并自定义配置]
D --> |否| F[使用默认配置]
E --> G[最终配置生效]
F --> G
G --> H[配置缓存]
subgraph "配置合并过程"
I[源配置] --> J[用户配置]
J --> K[深度合并]
K --> L[优先级: 用户配置 > 默认配置]
end
```

**图表来源**
- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)

#### 配置设置方法

配置可以通过以下方式设置：

1. **直接调用 setConfig 方法**
2. **通过 window 对象直接赋值**
3. **在应用初始化时进行批量配置**

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

### 加密配置系统

加密系统基于 SM4 对称加密算法，提供了端到端的数据保护机制。

#### 加密配置参数

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `keyBuffer` | Uint8Array | 是 | 16 字节的密钥缓冲区 |
| `mode` | String | 否 | 加密模式 (`cbc` 或 `ecb`) |
| `cipherType` | String | 否 | 输出类型 (`base64` 或 `text`) |

#### 加密流程图

```mermaid
flowchart TD
A[输入明文数据] --> B[JSON 序列化]
B --> C[字节缓冲区转换]
C --> D[数据填充 (PKCS7)]
D --> E{加密模式选择}
E --> |CBC 模式| F[CBC 加密流程]
E --> |ECB 模式| G[ECB 加密流程]
F --> H[初始向量处理]
H --> I[块级加密]
I --> J[输出 Base64]
G --> K[块级独立加密]
K --> J
J --> L[返回加密结果]
```

**图表来源**
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)

**章节来源**
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)

### HTTP 请求配置

HTTP 请求配置提供了灵活的网络请求参数管理，支持多种配置场景。

#### HTTP 配置参数

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `credentials` | String | `"include"` | Cookie 传输策略 |
| `requestType` | String | `"json"` | 请求数据类型 |
| `headers` | Object | `{}` | 自定义请求头 |
| `params` | Object | `{}` | GET 请求参数 |
| `data` | Object | `{}` | POST 请求数据 |

#### 请求处理流程

```mermaid
sequenceDiagram
participant Client as 客户端
participant HttpUtil as HTTP 工具
participant Crypto as 加密模块
participant Storage as 存储模块
participant Server as 服务器
Client->>HttpUtil : 发送请求
HttpUtil->>HttpUtil : 处理参数
HttpUtil->>Storage : 获取用户令牌
Storage-->>HttpUtil : 返回令牌
alt 需要加密
HttpUtil->>Crypto : 加密请求数据
Crypto-->>HttpUtil : 返回加密数据
end
HttpUtil->>Server : 发送 HTTP 请求
Server-->>HttpUtil : 返回响应
HttpUtil->>HttpUtil : 处理响应
alt 响应需要解密
HttpUtil->>Crypto : 解密响应数据
Crypto-->>HttpUtil : 返回明文数据
end
HttpUtil-->>Client : 返回处理后的结果
```

**图表来源**
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)

**章节来源**
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)

## 架构概览

### 整体架构设计

```mermaid
graph TB
subgraph "应用层"
APP[业务应用]
end
subgraph "配置管理层"
GC[全局配置]
SC[存储配置]
end
subgraph "核心服务层"
HC[HTTP 客户端]
EC[加密引擎]
ST[存储服务]
end
subgraph "工具层"
CM[通用工具]
SM[SM4 实现]
end
subgraph "外部依赖"
UR[umi-request]
B64[base64-js]
end
APP --> GC
APP --> HC
APP --> EC
APP --> ST
GC --> UR
HC --> UR
HC --> EC
HC --> ST
EC --> SM
EC --> B64
ST --> CM
GC --> CM
```

**图表来源**
- [index.js:8-15](file://index.js#L8-L15)
- [package.json:19-22](file://package.json#L19-L22)

### 组件交互关系

```mermaid
classDiagram
class TsGlobalConfig {
+defaultConfig : Object
+getConfig() : Object
+setConfig(obj) : void
}
class TsCrypto {
-sm4 : TsSM4
+encrypt(content) : String
+decrypt(base64) : String
}
class TsHttpUtil {
+req(url, options) : Promise
+get(url, params, options) : Promise
+post(url, data, options) : Promise
+form(url, data, options) : Promise
}
class TsSM4 {
+encrypt(plaintext) : String
+decrypt(ciphertext) : String
}
class TsStorage {
+save(key, value) : void
+get(key, def) : any
+getUserToken() : String
+saveEncryptBody(bool) : void
}
TsHttpUtil --> TsCrypto : 使用
TsHttpUtil --> TsStorage : 读取
TsHttpUtil --> TsGlobalConfig : 读取
TsCrypto --> TsSM4 : 依赖
TsCrypto --> TsGlobalConfig : 读取密钥
```

**图表来源**
- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)
- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
- [TsHttpUtil.js:168-171](file://src/https/TsHttpUtil.js#L168-L171)
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
- [TsStorage.js:47-55](file://src/utils/TsStorage.js#L47-L55)

## 详细配置分析

### 开发环境配置

开发环境推荐配置方案：

#### 基础开发配置

```javascript
// 开发环境基础配置
const devConfig = {
    base64Key: "WmdUzPJXbngVNiaSsQrihg==", // 开发环境密钥
    prefix: "http://localhost:8080/api", // 开发服务器地址
    onHttpError: (res) => {
        console.error("开发环境错误:", res);
    },
    httpParams: () => ({
        debug: true,
        version: "dev"
    })
};
```

#### 加密配置建议

```javascript
// 开发环境加密配置
const devEncryption = {
    encryptBody: false, // 开发阶段关闭加密便于调试
    encryptResponse: false
};
```

### 生产环境配置

生产环境配置需要更加严格的安全控制：

#### 安全生产配置

```javascript
// 生产环境安全配置
const prodConfig = {
    base64Key: process.env.ENCRYPTION_KEY, // 从环境变量读取
    prefix: (url) => {
        // 动态前缀根据域名判断
        if (window.location.hostname.includes('staging')) {
            return 'https://staging-api.example.com';
        }
        return 'https://api.example.com';
    },
    onHttpError: (res) => {
        // 生产环境错误上报
        this.reportError(res);
    },
    httpParams: () => ({
        timestamp: Date.now(),
        nonce: Math.random().toString(36).substr(2, 9)
    })
};
```

#### 加密配置要求

```javascript
// 生产环境强制加密
const prodEncryption = {
    encryptBody: true, // 必须启用请求加密
    encryptResponse: true, // 必须启用响应解密
    encryptionLevel: "high" // 高强度加密
};
```

### 不同使用场景的配置示例

#### 移动端应用配置

```javascript
// 移动端配置优化
const mobileConfig = {
    // 移动端网络优化
    timeout: 10000, // 10秒超时
    retry: 2, // 重试2次
    cache: false, // 禁用缓存
    
    // 移动端安全配置
    base64Key: process.env.MOBILE_ENCRYPTION_KEY,
    encryptBody: true,
    
    // 移动端特殊处理
    httpParams: () => ({
        platform: "mobile",
        appVersion: "1.0.0",
        deviceInfo: navigator.userAgent
    })
};
```

#### 微服务架构配置

```javascript
// 微服务架构配置
const microserviceConfig = {
    // 服务发现集成
    prefix: (url) => {
        const serviceMap = {
            "user": "https://user-service/api",
            "order": "https://order-service/api",
            "product": "https://product-service/api"
        };
        
        const service = Object.keys(serviceMap).find(key => url.includes(key));
        return service ? serviceMap[service] : serviceMap.default;
    },
    
    // 微服务特定配置
    onHttpError: (res) => {
        if (res.code === 503) {
            // 服务不可用，切换到备用服务
            this.switchToBackupService();
        }
    },
    
    httpParams: () => ({
        traceId: this.generateTraceId(),
        correlationId: this.generateCorrelationId()
    })
};
```

### 配置验证和调试方法

#### 配置验证流程

```mermaid
flowchart TD
A[配置输入] --> B[基本格式验证]
B --> C{格式正确?}
C --> |否| D[返回格式错误]
C --> |是| E[参数完整性检查]
E --> F{参数完整?}
F --> |否| G[返回缺失参数]
F --> |是| H[功能可用性测试]
H --> I{功能正常?}
I --> |否| J[返回功能错误]
I --> |是| K[配置验证通过]
subgraph "验证步骤"
L[检查必填参数]
M[验证参数类型]
N[测试加密功能]
O[测试网络连接]
end
```

#### 调试配置选项

```javascript
// 调试模式配置
const debugConfig = {
    // 开启详细日志
    debug: true,
    logLevel: "verbose",
    
    // 开发辅助功能
    enableMock: true,
    mockDelay: 1000,
    
    // 错误监控
    onError: (error) => {
        console.error("配置错误详情:", {
            error: error.message,
            config: error.config,
            stack: error.stack
        });
    }
};
```

**章节来源**
- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)

## 依赖关系分析

### 外部依赖管理

项目依赖关系清晰明确，主要依赖包括：

```mermaid
graph LR
subgraph "核心依赖"
UMI[umi-request@1.4.0]
B64[base64-js@1.5.1]
end
subgraph "内部模块"
HTTP[TsHttpUtil]
CRYPTO[TsCrypto]
GLOBAL[TsGlobalConfig]
SM4[TsSM4]
STORAGE[TsStorage]
COMMON[TsCommon]
end
HTTP --> UMI
CRYPTO --> B64
CRYPTO --> SM4
HTTP --> CRYPTO
HTTP --> STORAGE
HTTP --> GLOBAL
HTTP --> COMMON
GLOBAL --> COMMON
STORAGE --> COMMON
```

**图表来源**
- [package.json:19-22](file://package.json#L19-L22)
- [index.js:1-6](file://index.js#L1-L6)

### 内部模块依赖

内部模块之间的依赖关系遵循单一职责原则：

| 模块 | 依赖模块 | 用途 |
|------|----------|------|
| TsHttpUtil | TsCrypto, TsStorage, TsGlobalConfig, TsCommon | HTTP 请求处理 |
| TsCrypto | TsSM4, TsGlobalConfig | 数据加密解密 |
| TsStorage | TsCommon | 本地存储管理 |
| TsGlobalConfig | TsCommon | 全局配置管理 |

**章节来源**
- [package.json:19-22](file://package.json#L19-L22)
- [index.js:1-16](file://index.js#L1-L16)

## 性能考虑

### 加密性能优化

加密操作是影响性能的关键因素，需要考虑以下优化策略：

#### 加密性能指标

| 操作类型 | 处理时间 | 内存占用 | 推荐场景 |
|----------|----------|----------|----------|
| 小数据加密 (<1KB) | <1ms | <1KB | API 请求 |
| 中等数据加密 (1-10KB) | 1-5ms | 1-10KB | 文件上传 |
| 大数据加密 (>10KB) | 5-50ms | 10-50KB | 批量数据 |

#### 性能优化建议

1. **延迟加密**：仅对敏感数据进行加密
2. **批量处理**：合并多个小请求为批量请求
3. **缓存策略**：对不敏感数据使用缓存
4. **异步处理**：在后台线程中执行加密操作

### 网络请求优化

#### 请求优化策略

```javascript
// 性能优化配置示例
const performanceConfig = {
    // 连接池管理
    maxConnections: 10,
    connectionTimeout: 5000,
    
    // 缓存策略
    cacheStrategy: "smart", // 智能缓存
    cacheTTL: 300000, // 5分钟缓存
    
    // 压缩配置
    enableCompression: true,
    compressionThreshold: 1024,
    
    // 超时配置
    requestTimeout: 10000,
    retryTimeout: 2000,
    
    // 重试策略
    maxRetries: 3,
    retryBackoff: "exponential"
};
```

## 故障排除指南

### 常见配置问题

#### 加密相关问题

| 问题类型 | 症状 | 解决方案 |
|----------|------|----------|
| 密钥不匹配 | 加密失败，抛出异常 | 检查 base64Key 配置 |
| IV 配置错误 | CBC 模式加密异常 | 确认 IV 参数正确设置 |
| 模式不兼容 | 加密/解密失败 | 确保加密和解密使用相同模式 |

#### HTTP 请求问题

| 问题类型 | 症状 | 解决方案 |
|----------|------|----------|
| 跨域问题 | CORS 错误 | 配置正确的 CORS 头 |
| 超时问题 | 请求超时 | 调整 timeout 参数 |
| 认证失败 | 401 错误 | 检查用户令牌配置 |

#### 存储相关问题

| 问题类型 | 症状 | 解决方案 |
|----------|------|----------|
| 存储失败 | 无法保存数据 | 检查浏览器存储权限 |
| 数据丢失 | 重启后数据消失 | 确认使用 localStorage |
| 格式错误 | JSON 解析失败 | 检查数据序列化 |

### 调试工具和方法

#### 配置调试接口

```javascript
// 配置状态检查
const checkConfigStatus = () => {
    return {
        globalConfig: TsGlobalConfig.getConfig(),
        encryptionEnabled: TsStorage.getEncryptBody(),
        userToken: TsStorage.getUserToken(),
        storageAvailable: typeof localStorage !== 'undefined'
    };
};

// 加密功能测试
const testEncryption = (testData) => {
    try {
        const encrypted = TsCrypto.encrypt(testData);
        const decrypted = TsCrypto.decrypt(encrypted);
        return {
            success: testData === decrypted,
            original: testData,
            encrypted: encrypted,
            decrypted: decrypted
        };
    } catch (error) {
        return {
            success: false,
            error: error.message
        };
    }
};
```

#### 日志记录配置

```javascript
// 详细日志配置
const loggingConfig = {
    enableDebugLogs: true,
    logLevels: ["error", "warn", "info", "debug"],
    logToFile: false,
    logToConsole: true,
    maxLogSize: 10485760, // 10MB
    retentionDays: 7
};
```

**章节来源**
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
- [TsStorage.js:47-55](file://src/utils/TsStorage.js#L47-L55)

## 结论

npm-tool 工具包提供了完整的配置管理解决方案，具有以下特点：

### 主要优势

1. **灵活的配置系统**：支持多层级配置和动态覆盖
2. **强大的加密能力**：基于 SM4 算法的安全数据传输
3. **完善的错误处理**：全面的异常捕获和错误恢复机制
4. **环境适配性强**：支持开发、测试、生产多环境部署

### 最佳实践建议

1. **生产环境必须启用加密**：确保数据传输安全
2. **合理配置超时参数**：平衡用户体验和系统性能
3. **实施适当的缓存策略**：提升应用响应速度
4. **建立完善的监控体系**：及时发现和解决问题

### 安全考虑

1. **密钥安全管理**：使用环境变量存储敏感配置
2. **传输安全**：确保所有数据通过 HTTPS 传输
3. **访问控制**：实施严格的权限验证机制
4. **审计日志**：记录重要的配置变更和访问行为

通过遵循本指南提供的配置最佳实践，可以确保 npm-tool 工具包在各种使用场景下都能稳定、安全地运行。