# 存储配置

<cite>
**本文档引用的文件**
- [TsStorage.js](file://src/utils/TsStorage.js)
- [TsCrypto.js](file://src/utils/TsCrypto.js)
- [TsSM4.js](file://src/utils/TsSM4.js)
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
- [TsCommon.js](file://src/utils/TsCommon.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. [附录](#附录)

## 简介

本指南专注于 TsStorage 模块的存储配置，这是一个基于 localStorage 的轻量级存储解决方案。该模块提供了完整的数据持久化功能，包括基础存储操作、用户令牌管理、数据加密以及全局配置管理。通过本文档，您将了解如何正确配置和使用存储功能，包括存储前缀、加密开关、存储策略等关键配置选项。

## 项目结构

该项目采用模块化设计，主要包含以下核心文件：

```mermaid
graph TB
subgraph "核心模块"
A[index.js<br/>主入口文件]
B[TsStorage.js<br/>存储模块]
C[TsCrypto.js<br/>加密模块]
D[TsSM4.js<br/>SM4算法实现]
E[TsGlobalConfig.js<br/>全局配置]
F[TsCommon.js<br/>通用工具]
end
subgraph "外部依赖"
G[base64-js<br/>Base64编码]
H[umi-request<br/>HTTP请求]
end
A --> B
A --> C
A --> D
A --> E
A --> F
C --> D
C --> E
B --> F
D --> G
A --> H
```

**图表来源**
- [index.js:1-16](file://index.js#L1-L16)
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
- [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)

## 核心组件

### TsStorage 模块

TsStorage 是整个存储系统的核心模块，提供了以下主要功能：

- **基础存储操作**：提供通用的保存和获取方法
- **用户令牌管理**：专门处理用户认证令牌的存储
- **加密开关控制**：支持启用或禁用数据加密功能
- **数据序列化**：自动处理 JSON 序列化和反序列化

### TsCrypto 模块

负责数据加密和解密的核心模块，基于 SM4 算法实现：

- **SM4 加密算法**：实现中国国家密码标准的 SM4 对称加密
- **密钥管理**：从全局配置中获取和管理加密密钥
- **模式支持**：支持 ECB 和 CBC 两种加密模式

### TsSM4 模块

SM4 算法的具体实现，包含完整的加密和解密逻辑：

- **算法实现**：完整的 SM4 加密算法实现
- **填充机制**：支持 PKCS7 填充标准
- **多种输出格式**：支持 Base64 和文本两种输出格式

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

## 架构概览

存储系统的整体架构采用分层设计，确保了功能的模块化和可维护性：

```mermaid
graph TD
subgraph "应用层"
App[应用程序]
end
subgraph "存储接口层"
Storage[Storage 接口]
Crypto[Crypto 接口]
end
subgraph "业务逻辑层"
Token[用户令牌管理]
Config[配置管理]
Utils[通用工具]
end
subgraph "数据访问层"
LocalStorage[localStorage]
Memory[内存缓存]
end
App --> Storage
App --> Crypto
Storage --> Token
Storage --> Config
Storage --> Utils
Crypto --> SM4
Utils --> LocalStorage
Storage --> LocalStorage
Crypto --> Memory
```

**图表来源**
- [TsStorage.js:26-43](file://src/utils/TsStorage.js#L26-L43)
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)

## 详细组件分析

### 存储配置选项详解

#### 基础存储配置

TsStorage 模块提供了灵活的基础存储配置选项：

**数据序列化配置**
- 自动 JSON 序列化：所有存储的数据都会被自动转换为 JSON 字符串
- 安全反序列化：使用安全的 JSON 解析机制，避免异常导致的应用崩溃
- 默认值处理：支持为不存在的键提供默认值

**存储策略配置**
- 键值映射：每个存储项都以键值对的形式保存在 localStorage 中
- 数据包装：内部使用 `{data: value}` 的包装格式存储原始数据
- 类型保持：通过 JSON 序列化保持数据类型信息

#### 加密存储配置

**加密开关配置**
- `saveEncryptBody(bool)`：设置是否启用数据加密
- `getEncryptBody()`：获取当前加密状态
- 默认启用：加密功能默认处于启用状态

**加密算法配置**
- SM4 算法：采用中国国家密码标准的对称加密算法
- ECB 模式：默认使用 ECB 模式进行加密
- Base64 输出：加密结果以 Base64 格式存储

**密钥配置**
- 全局密钥管理：密钥从全局配置中获取
- Base64 编码：密钥以 Base64 格式存储和传输
- 配置覆盖：支持运行时动态修改密钥

#### 用户令牌配置

**令牌存储配置**
- 专用令牌键：使用固定的 'token' 键存储用户令牌
- 自动序列化：令牌数据自动进行 JSON 序列化
- 空值处理：未找到令牌时返回空字符串

**令牌管理策略**
- 单一令牌模型：系统只支持单一用户令牌
- 简化接口：提供简化的 get/set 方法
- 安全存储：令牌数据同样遵循加密配置

**章节来源**
- [TsStorage.js:9-23](file://src/utils/TsStorage.js#L9-L23)
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)

### 存储场景配置建议

#### 用户会话存储

**配置策略**
- 启用加密：用户会话数据包含敏感信息，必须启用加密
- 设置过期时间：结合业务需求设置合理的过期时间
- 清理策略：定期清理过期的会话数据

**实现示例**
```javascript
// 启用加密存储
Storage.saveEncryptBody(true);

// 存储用户令牌
Storage.saveUserToken(token);

// 获取用户令牌
const token = Storage.getUserToken();
```

#### 应用状态存储

**配置策略**
- 非敏感数据：非敏感的应用状态可以不启用加密
- 性能优化：对于大量数据的存储，考虑启用加密可能影响性能
- 数据压缩：对于大体量数据，考虑先压缩再存储

**实现示例**
```javascript
// 根据数据敏感性选择加密
if (isSensitiveData) {
    Storage.saveEncryptBody(true);
} else {
    Storage.saveEncryptBody(false);
}

// 存储应用配置
Storage.save('appConfig', configData);
```

#### 临时数据存储

**配置策略**
- 短期存储：临时数据适合短期存储，不需要长期保留
- 自动清理：设置合理的过期时间，避免占用过多存储空间
- 批量清理：定期清理过期的临时数据

**章节来源**
- [TsStorage.js:47-54](file://src/utils/TsStorage.js#L47-L54)

### 存储容量限制和清理策略

#### 容量限制

**localStorage 限制**
- 浏览器限制：每个域名下通常有 5-10MB 的存储限制
- 平台差异：不同浏览器的限制可能有所不同
- 存储检查：需要定期检查存储使用情况

**容量监控**
- 使用率计算：监控已用空间与总容量的比例
- 预警机制：当使用率达到一定阈值时发出警告
- 自动清理：超过阈值时自动清理过期数据

#### 清理策略

**定时清理**
- 周期性清理：定期执行清理任务，删除过期数据
- 条件清理：根据存储使用情况触发清理
- 批量清理：一次性清理多个过期项目

**智能清理**
- 优先级清理：优先清理低优先级的过期数据
- 空间回收：清理后释放存储空间
- 性能优化：清理过程不影响正常的数据访问

**章节来源**
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)

### 加密存储配置方法和性能影响

#### 加密配置方法

**基本加密配置**
```javascript
// 创建加密实例
const crypto = new TsCrypto();

// 加密数据
const encrypted = crypto.encrypt("敏感数据");

// 解密数据
const decrypted = crypto.decrypt(encrypted);
```

**高级配置选项**
- 模式选择：ECB 或 CBC 模式的选择
- 输出格式：Base64 或文本格式的输出
- IV 参数：CBC 模式的初始化向量配置

#### 性能影响分析

**CPU 开销**
- 加密开销：加密操作需要额外的 CPU 时间
- 解密开销：解密操作同样消耗 CPU 资源
- 批量处理：批量处理数据时的性能考虑

**内存使用**
- 内存占用：加密算法需要额外的内存空间
- 数据复制：加密过程中可能产生数据副本
- 缓存策略：合理使用缓存减少重复计算

**I/O 影响**
- 序列化成本：JSON 序列化和反序列化的影响
- 存储效率：加密后的数据大小变化
- 网络传输：加密数据在网络传输中的影响

**章节来源**
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)

### 存储配置的安全考虑和最佳实践

#### 安全配置

**密钥管理**
- 密钥强度：确保密钥具有足够的随机性和长度
- 密钥轮换：定期更换加密密钥
- 安全存储：密钥的存储和传输要确保安全

**数据保护**
- 敏感数据：识别和保护敏感数据
- 访问控制：限制对敏感数据的访问权限
- 审计日志：记录重要的数据访问和修改操作

**传输安全**
- HTTPS 传输：确保数据在传输过程中的安全
- 中间人攻击：防范中间人攻击和数据篡改
- 会话管理：安全的会话管理和令牌处理

#### 最佳实践

**配置最佳实践**
- 最小权限原则：只授予必要的存储权限
- 数据最小化：只存储必要的数据
- 及时清理：及时清理不再需要的数据

**性能最佳实践**
- 异步操作：使用异步方式处理存储操作
- 批量处理：批量处理多个存储请求
- 缓存策略：合理使用缓存提高性能

**错误处理最佳实践**
- 异常捕获：妥善处理存储操作中的异常
- 降级策略：在存储失败时提供降级方案
- 用户提示：向用户提供清晰的错误信息

**章节来源**
- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)

### 存储配置的迁移和备份策略

#### 迁移策略

**版本兼容性**
- 数据格式升级：确保新版本能够读取旧版本的数据
- 渐进式迁移：逐步将旧数据迁移到新格式
- 回滚机制：提供数据迁移失败时的回滚方案

**配置迁移**
- 配置项更新：处理配置项的新增、删除和重命名
- 默认值处理：为新配置项设置合理的默认值
- 兼容性测试：确保迁移过程不影响现有功能

#### 备份策略

**数据备份**
- 定期备份：建立定期备份机制
- 多点备份：在多个位置保存备份数据
- 自动恢复：提供自动数据恢复功能

**配置备份**
- 配置导出：支持配置的导出和导入
- 版本管理：管理配置的不同版本
- 快速恢复：提供快速恢复到之前配置的能力

**章节来源**
- [TsStorage.js:26-43](file://src/utils/TsStorage.js#L26-L43)
- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)

### 存储配置的调试和监控方法

#### 调试方法

**存储调试**
- 数据验证：验证存储的数据是否正确
- 格式检查：检查数据的格式是否符合预期
- 性能监控：监控存储操作的性能指标

**加密调试**
- 加密验证：验证加密和解密过程的正确性
- 密钥检查：确认使用的密钥是否正确
- 算法验证：验证加密算法的实现是否正确

#### 监控方法

**性能监控**
- 响应时间：监控存储操作的响应时间
- 错误率：统计存储操作的错误率
- 资源使用：监控存储相关的资源使用情况

**健康监控**
- 存储状态：监控存储系统的健康状态
- 数据完整性：检查数据的完整性和一致性
- 安全监控：监控存储相关的安全事件

**章节来源**
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)

## 依赖关系分析

存储系统的依赖关系相对简单，主要依赖于几个核心模块：

```mermaid
graph LR
subgraph "直接依赖"
A[TsStorage.js]
B[TsCrypto.js]
C[TsSM4.js]
D[TsCommon.js]
end
subgraph "外部依赖"
E[base64-js]
F[umi-request]
end
subgraph "全局配置"
G[TsGlobalConfig.js]
end
A --> D
B --> C
B --> G
C --> E
A --> G
A --> F
```

**图表来源**
- [TsStorage.js:1](file://src/utils/TsStorage.js#L1)
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
- [TsSM4.js:1](file://src/utils/TsSM4.js#L1)
- [TsGlobalConfig.js:1-3](file://src/utils/TsGlobalConfig.js#L1-L3)

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

## 性能考虑

### 存储性能优化

**序列化优化**
- JSON 序列化：使用高效的 JSON 序列化方法
- 数据压缩：对于大数据量考虑压缩存储
- 批量操作：合并多个存储请求减少 I/O 操作

**内存管理**
- 对象复用：复用对象减少内存分配
- 及时释放：及时释放不再使用的对象引用
- 垃圾回收：合理安排垃圾回收时机

**并发处理**
- 异步操作：使用异步方式处理存储操作
- 锁机制：在需要时使用锁机制保证数据一致性
- 队列管理：使用队列管理并发的存储请求

### 加密性能优化

**算法优化**
- 缓存密钥：缓存加密密钥避免重复计算
- 批量加密：批量处理多个数据项
- 异步加密：使用异步方式处理加密操作

**资源配置**
- 线程池：合理配置加密操作的线程池
- 内存池：使用内存池减少内存分配开销
- 缓存策略：合理使用缓存提高加密性能

## 故障排除指南

### 常见问题诊断

**存储失败**
- 检查浏览器兼容性：确认目标浏览器支持 localStorage
- 验证存储空间：检查是否有足够的存储空间
- 检查权限设置：确认应用有足够的存储权限

**数据损坏**
- 验证数据格式：检查存储的数据格式是否正确
- 检查序列化问题：确认 JSON 序列化和反序列化正常
- 处理异常数据：对异常数据进行特殊处理

**加密问题**
- 密钥验证：确认使用的密钥是否正确
- 算法兼容性：检查加密算法的兼容性
- 性能问题：监控加密操作的性能表现

### 调试技巧

**日志记录**
- 关键操作日志：记录重要的存储操作
- 错误日志：详细记录存储操作中的错误
- 性能日志：记录存储操作的性能指标

**监控工具**
- 浏览器开发者工具：使用开发者工具监控存储操作
- 性能分析器：使用性能分析器分析存储性能
- 日志分析：定期分析存储相关的日志

**章节来源**
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)

## 结论

TsStorage 模块提供了一个功能完整、配置灵活的存储解决方案。通过本文档的详细说明，您可以：

1. **正确配置存储选项**：理解存储前缀、加密开关和存储策略的配置方法
2. **优化存储性能**：掌握性能优化的最佳实践和注意事项
3. **确保存储安全**：实施有效的安全措施和最佳实践
4. **制定迁移策略**：规划数据迁移和备份的完整方案
5. **有效调试监控**：建立完善的调试和监控体系

该模块的设计充分考虑了实际应用场景的需求，在保证功能完整性的同时，也注重了性能和安全性的平衡。通过合理配置和使用，可以满足大多数应用的存储需求。

## 附录

### 配置参考表

| 配置项 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| base64Key | string | WmdUzPJXbngVNiaSsQrihg== | 加密密钥（Base64编码） |
| prefix | string | "" | 存储键前缀 |
| encrypt_body | boolean | true | 是否启用数据加密 |
| token | string | "" | 用户令牌存储 |

### 使用示例路径

- [基础存储操作:31-43](file://src/utils/TsStorage.js#L31-L43)
- [用户令牌管理:9-15](file://src/utils/TsStorage.js#L9-L15)
- [加密开关配置:17-23](file://src/utils/TsStorage.js#L17-L23)
- [全局配置管理:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)