Files

曾文豪 523cc777f8 docs(readme): 重构README并补充详细文档内容

2026-04-29 11:20:18 +08:00

16 KiB

Raw Blame History

存储访问问题

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

简介

本指南专注于存储访问相关的故障排除，涵盖localStorage访问失败、数据读取错误、存储空间不足、数据格式异常等问题的诊断和解决方法。该工具包提供了完整的本地存储解决方案，包括数据序列化、加密存储、错误处理等功能。

项目结构

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

graph TB
subgraph "主入口"
Index[index.js]
end
subgraph "存储模块"
Storage[TsStorage.js]
Common[TsCommon.js]
end
subgraph "网络模块"
HttpUtil[TsHttpUtil.js]
Crypto[TsCrypto.js]
SM4[TsSM4.js]
Config[TsGlobalConfig.js]
end
subgraph "外部依赖"
UmiRequest[umi-request]
Base64[base64-js]
end
Index --> Storage
Index --> HttpUtil
Index --> Crypto
Index --> Config
Storage --> Common
HttpUtil --> Storage
HttpUtil --> Crypto
Crypto --> SM4
Crypto --> Config
HttpUtil --> UmiRequest
Crypto --> Base64

图表来源

章节来源

核心组件

存储管理器 (TsStorage)

存储管理器提供了完整的localStorage操作接口，支持数据的保存、读取和用户令牌管理。

主要功能特性：

数据序列化和反序列化
用户令牌存储和获取
加密开关控制
错误处理和默认值机制

通用工具 (TsCommon)

提供了基础的JavaScript工具函数，特别是JSON解析和数据验证功能。

关键功能：

安全的JSON解析
空值检测
字符串处理工具

网络请求 (TsHttpUtil)

集成了存储功能的HTTP客户端，支持自动数据加密和令牌管理。

核心特性：

自动令牌注入
条件数据加密
统一错误处理
配置化参数处理

架构概览

sequenceDiagram
participant Client as 客户端应用
participant Storage as 存储管理器
participant Common as 通用工具
participant Crypto as 加密模块
participant HTTP as HTTP客户端
Client->>Storage : 保存数据
Storage->>Storage : 序列化数据
Storage->>Storage : 写入localStorage
Client->>Storage : 读取数据
Storage->>Storage : 从localStorage读取
Storage->>Common : 解析JSON
Common-->>Storage : 返回数据
Storage-->>Client : 返回结果
Client->>HTTP : 发送请求
HTTP->>Storage : 获取用户令牌
Storage-->>HTTP : 返回令牌
HTTP->>Crypto : 加密数据(可选)
Crypto-->>HTTP : 返回加密结果
HTTP-->>Client : 返回响应

图表来源

详细组件分析

存储组件深度分析

classDiagram
class TsStorage {
+save(key, value) void
+get(key, def) string
+saveUserToken(token) void
+getUserToken() string
+saveEncryptBody(bool) void
+getEncryptBody() boolean
}
class TsCommon {
+parseJSON(value, def) Object
+isEmpty(value) boolean
+getParamFormUrl(key, host) string
+isDevelopment() boolean
}
class TsHttpUtil {
+req(url, options) Promise
+get(url, params, options) Promise
+post(url, data, options) Promise
+form(url, data, options) Promise
}
class TsCrypto {
+encrypt(content) string
+decrypt(base64) string
}
class TsSM4 {
+encrypt(plaintext) string
+decrypt(ciphertext) string
}
TsStorage --> TsCommon : 使用
TsHttpUtil --> TsStorage : 依赖
TsHttpUtil --> TsCrypto : 使用
TsCrypto --> TsSM4 : 使用

图表来源

章节来源

存储访问故障排除指南

常见存储问题诊断

1. localStorage 访问失败

症状表现：

页面加载时报错，提示localStorage不可用
数据无法保存或读取
浏览器控制台出现安全错误

诊断步骤：

检查浏览器隐私模式设置
验证跨域访问权限
确认浏览器扩展程序影响
检查HTTPS环境要求

解决方案：

// 检查localStorage可用性
function checkLocalStorage() {
    try {
        const test = 'test';
        localStorage.setItem(test, test);
        localStorage.removeItem(test);
        return true;
    } catch (e) {
        return false;
    }
}

// 降级方案：使用sessionStorage
if (!checkLocalStorage()) {
    console.warn('localStorage不可用，使用sessionStorage作为替代');
}

2. 数据读取错误

症状表现：

读取到空值或undefined
JSON解析失败
数据类型不匹配

诊断流程：

flowchart TD
Start([开始诊断]) --> CheckKey["检查键名是否存在"]
CheckKey --> KeyExists{"键存在？"}
KeyExists --> |否| CreateDefault["创建默认值"]
KeyExists --> |是| CheckFormat["检查数据格式"]
CheckFormat --> FormatOK{"格式正确？"}
FormatOK --> |否| ParseError["JSON解析错误"]
FormatOK --> |是| DataType["检查数据类型"]
DataType --> TypeOK{"类型匹配？"}
TypeOK --> |否| ConvertData["转换数据类型"]
TypeOK --> |是| Success["诊断完成"]
CreateDefault --> Success
ParseError --> FixParse["修复JSON格式"]
FixParse --> Success
ConvertData --> Success

图表来源

解决方案：

实施默认值机制
添加数据类型验证
实现错误边界处理

3. 存储空间不足

症状表现：

保存数据时报错
随机数据丢失
性能明显下降

诊断方法：

检查localStorage使用量
分析数据增长趋势
识别大体积数据项

优化策略：

// 存储容量监控
function checkStorageCapacity() {
    const storage = localStorage;
    let totalSize = 0;
    
    for (let key in storage) {
        if (storage.hasOwnProperty(key)) {
            totalSize += storage[key].length;
        }
    }
    
    return totalSize;
}

// 清理过期数据
function cleanupExpiredData() {
    const now = Date.now();
    const maxAge = 7 * 24 * 60 * 60 * 1000; // 7天
    
    for (let key in localStorage) {
        if (localStorage.hasOwnProperty(key)) {
            try {
                const item = JSON.parse(localStorage.getItem(key));
                if (item.timestamp && (now - item.timestamp) > maxAge) {
                    localStorage.removeItem(key);
                }
            } catch (e) {
                // 忽略格式错误的数据
            }
        }
    }
}

4. 数据格式异常

症状表现：

JSON解析抛出异常
数据损坏或不完整
版本升级后数据不兼容

诊断步骤：

验证数据完整性
检查版本兼容性
分析数据结构变化

修复方法：

// 安全的数据读取
function safeGet(key, defaultValue = null) {
    try {
        const item = localStorage.getItem(key);
        if (!item) return defaultValue;
        
        const parsed = JSON.parse(item);
        return parsed.data || defaultValue;
    } catch (error) {
        console.error(`读取存储项 ${key} 失败:`, error);
        return defaultValue;
    }
}

// 数据格式验证
function validateDataStructure(data) {
    const requiredFields = ['data'];
    return requiredFields.every(field => data.hasOwnProperty(field));
}

浏览器兼容性问题

1. 不同浏览器的差异

问题类型：

Safari隐私模式限制
IE/Edge兼容性问题
移动端存储限制

解决方案：

// 跨浏览器兼容性检查
function isStorageSupported() {
    const testKey = '__storage_test__';
    
    try {
        if ('localStorage' in window && window['localStorage'] !== null) {
            localStorage.setItem(testKey, testKey);
            localStorage.removeItem(testKey);
            return true;
        }
        return false;
    } catch (e) {
        return false;
    }
}

// 功能检测而非浏览器检测
function getStorageImplementation() {
    if (isStorageSupported()) {
        return localStorage;
    } else if (typeof sessionStorage !== 'undefined') {
        return sessionStorage;
    } else {
        // 无存储支持，使用内存存储
        return createMemoryStorage();
    }
}

2. 存储权限限制

常见场景：

第三方Cookie限制
HTTPS环境要求
用户隐私设置

处理策略：

// 权限检查和降级
function handleStoragePermissions() {
    const permissions = {
        localStorage: false,
        sessionStorage: false,
        cookies: false
    };
    
    // 检查localStorage
    try {
        localStorage.setItem('permission_test', 'test');
        localStorage.removeItem('permission_test');
        permissions.localStorage = true;
    } catch (e) {
        permissions.localStorage = false;
    }
    
    // 检查cookies
    try {
        document.cookie = 'permission_test=test';
        permissions.cookies = true;
    } catch (e) {
        permissions.cookies = false;
    }
    
    return permissions;
}

数据序列化失败

1. JSON序列化问题

常见原因：

循环引用
函数和undefined
复杂对象类型

诊断方法：

flowchart TD
Start([序列化开始]) --> CheckCircular["检查循环引用"]
CheckCircular --> HasCircular{"存在循环引用？"}
HasCircular --> |是| RemoveCircular["移除循环引用"]
HasCircular --> |否| CheckTypes["检查数据类型"]
CheckTypes --> HasInvalid{"包含无效类型？"}
HasInvalid --> |是| FilterInvalid["过滤无效类型"]
HasInvalid --> |否| SafeStringify["安全字符串化"]
RemoveCircular --> SafeStringify
FilterInvalid --> SafeStringify
SafeStringify --> Complete["序列化完成"]

图表来源

TsStorage.js:31-33

解决方案：

// 安全的JSON序列化
function safeStringify(obj) {
    const seen = new WeakSet();
    
    return JSON.stringify(obj, (key, value) => {
        if (typeof value === "object" && value !== null) {
            if (seen.has(value)) {
                return "[Circular Reference]";
            }
            seen.add(value);
        }
        return value;
    });
}

// 自定义序列化器
function customSerializer(data) {
    return {
        data: data,
        timestamp: Date.now(),
        version: "1.0"
    };
}

依赖关系分析

graph LR
subgraph "核心依赖"
A[umi-request] --> B[TsHttpUtil]
C[base64-js] --> D[TsCrypto]
end
subgraph "内部模块"
E[TsStorage] --> F[TsCommon]
B --> E
B --> G[TsCrypto]
G --> H[TsSM4]
G --> I[TsGlobalConfig]
end
J[index.js] --> E
J --> B
J --> G
J --> I

图表来源

章节来源

性能考虑

存储性能优化

批量操作优化
- 合并多个存储操作
- 使用事务性操作
- 避免频繁的读写
数据压缩
- 对大对象进行压缩
- 实现增量更新
- 使用索引优化查询
缓存策略
- 实现内存缓存
- 设置合理的过期时间
- 支持LRU淘汰算法

数据迁移最佳实践

flowchart TD
Start([开始迁移]) --> CheckVersion["检查当前版本"]
CheckVersion --> VersionOK{"版本兼容？"}
VersionOK --> |是| DirectCopy["直接复制数据"]
VersionOK --> |否| TransformData["转换数据格式"]
TransformData --> ValidateData["验证数据完整性"]
DirectCopy --> ValidateData
ValidateData --> MigrationOK{"迁移成功？"}
MigrationOK --> |是| UpdateVersion["更新版本号"]
MigrationOK --> |否| Rollback["回滚操作"]
UpdateVersion --> Complete["迁移完成"]
Rollback --> Complete

图表来源

TsStorage.js:41-43

故障排除指南

常见错误信息解读

错误类型	可能原因	解决方案
SecurityError	跨域访问限制	检查域名和协议一致性
QuotaExceededError	存储空间不足	清理旧数据或使用压缩
InvalidStateError	存储状态异常	重启浏览器或清除缓存
TypeError	数据格式错误	实施数据验证和转换

诊断工具和方法

// 存储状态检查
function diagnoseStorage() {
    const diagnostics = {
        localStorage: false,
        sessionStorage: false,
        quota: 0,
        items: 0,
        totalSize: 0
    };
    
    // 检查localStorage
    try {
        localStorage.setItem('diagnostics', 'test');
        localStorage.removeItem('diagnostics');
        diagnostics.localStorage = true;
    } catch (e) {
        diagnostics.localStorage = false;
    }
    
    // 检查存储配额和使用情况
    if (navigator.webkitTemporaryStorage) {
        navigator.webkitTemporaryStorage.queryUsageAndQuota(
            (usage, quota) => {
                diagnostics.quota = quota;
                diagnostics.used = usage;
            }
        );
    }
    
    // 统计存储项数量和大小
    for (let key in localStorage) {
        if (localStorage.hasOwnProperty(key)) {
            diagnostics.items++;
            diagnostics.totalSize += key.length + localStorage[key].length;
        }
    }
    
    return diagnostics;
}

// 数据完整性验证
function validateStorageIntegrity() {
    const errors = [];
    const keys = Object.keys(localStorage);
    
    keys.forEach(key => {
        try {
            JSON.parse(localStorage.getItem(key));
        } catch (e) {
            errors.push({
                key: key,
                error: e.message,
                value: localStorage.getItem(key)
            });
        }
    });
    
    return errors;
}

最佳实践建议

错误处理
- 实施全面的try-catch包装
- 提供优雅降级机制
- 记录详细的错误日志
数据保护
- 实施数据备份策略
- 使用版本控制
- 定期数据健康检查
性能监控
- 监控存储使用率
- 跟踪访问模式
- 优化热点数据

章节来源

结论

存储访问问题的解决需要系统性的方法和完善的监控机制。通过实施本文档提供的诊断流程、故障排除方法和最佳实践，可以有效预防和解决大多数存储相关问题。关键在于建立完善的错误处理机制、实施数据验证和转换、以及持续监控存储状态。

建议在生产环境中：

实施多层次的错误处理
建立存储使用监控
定期进行数据完整性检查
制定数据迁移和备份策略

这样可以确保应用程序的稳定性和可靠性，为用户提供更好的体验。

16 KiB Raw Blame History Unescape Escape

存储访问问题

目录

简介

项目结构

核心组件

存储管理器 (TsStorage)

通用工具 (TsCommon)

网络请求 (TsHttpUtil)

架构概览

详细组件分析

存储组件深度分析

存储访问故障排除指南

常见存储问题诊断

1. localStorage 访问失败

2. 数据读取错误

3. 存储空间不足

4. 数据格式异常

浏览器兼容性问题

1. 不同浏览器的差异

2. 存储权限限制

数据序列化失败

1. JSON序列化问题

依赖关系分析

性能考虑

存储性能优化

数据迁移最佳实践

故障排除指南

常见错误信息解读

诊断工具和方法

最佳实践建议

结论

16 KiB

Raw Blame History