# LocalCacheManager **Repository Path**: chen--eleven/local-cache-manager ## Basic Information - **Project Name**: LocalCacheManager - **Description**: 本地缓存管理器是一个简化应用数据缓存流程的工具库，提供键值对存储、图片缓存和自动过期策略，帮助开发者轻松实现数据持久化和离线访问。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-08-28 - **Last Updated**: 2025-09-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 本地缓存管理器 ## 项目描述 本地缓存管理器是一个简化应用数据缓存流程的工具库，提供键值对存储、图片缓存和自动过期策略，帮助开发者轻松实现数据持久化和离线访问。 ## 作者 **冬梅** ## 主要功能 - **键值对存储**：支持存储和读取各种类型的数据，包括字符串、数字、布尔值、对象等 - **图片缓存**：高效缓存和管理图片资源，减少网络请求和内存占用 - **自动过期策略**：支持设置缓存数据的过期时间，自动清理过期数据 - **数据持久化**：支持将数据持久化到本地存储，实现离线访问 - **缓存大小管理**：监控和控制缓存大小，防止过度占用存储空间 ## 技术栈 - 鸿蒙应用开发框架 - @ohos.storage API - @ohos.cache API ## 使用场景 - 网络请求数据缓存 - 用户配置和偏好设置存储 - 图片和资源文件缓存 - 离线数据访问 ## 创意与市场分析 ### 创意来源 本项目的创意源于解决移动应用开发中的常见痛点：数据加载速度慢、网络请求频繁导致的流量消耗、以及离线场景下的用户体验问题。通过提供一个统一、高效的缓存管理解决方案，我们希望简化开发者的工作流程，同时提升应用的性能和用户体验。 ### 目标用户 1. **鸿蒙应用开发者**：需要高效缓存解决方案的独立开发者和开发团队 2. **企业级应用开发团队**：构建需要处理大量数据和图片资源的商业应用 3. **学习鸿蒙开发的学生和教育机构**：作为学习缓存管理和数据持久化的教学工具 ### 市场分析 随着鸿蒙生态的快速发展，对于专业化、高性能的开发工具库需求日益增长。本地缓存管理器填补了以下市场空白： 1. **性能优化需求**：随着应用功能日益复杂，用户对应用启动速度和响应性的要求越高，高效的缓存管理成为关键 2. **流量敏感市场**：在许多新兴市场，移动数据流量成本较高，减少不必要的网络请求具有明显的用户价值 3. **离线场景支持**：在网络连接不稳定的环境下，良好的缓存策略可以显著提升用户体验 4. **开发效率提升**：标准化的缓存解决方案可以减少开发者的重复工作，加速应用开发周期 ### 竞争优势 - **鸿蒙原生支持**：专为鸿蒙生态设计，充分利用平台特性 - **轻量级设计**：最小化依赖，降低应用包大小 - **易于集成**：简洁的API设计，降低学习和使用门槛 - **全面的缓存策略**：同时支持内存缓存和持久化存储，满足不同场景需求 ## 下载安装 ### 方式一：通过HAR包安装 1. 下载项目中的 `lib_har/localcache.har` 文件 2. 将HAR文件复制到你的项目根目录下的 `libs` 文件夹中 3. 在项目的 `oh-package.json5` 文件中添加依赖： ```json { "dependencies": { "localcache": "file:./libs/localcache.har" } } ``` 4. 执行 `ohpm install` 安装依赖 ### 方式二：源码集成 1. 克隆或下载本项目源码 2. 将 `localcache` 模块文件夹复制到你的项目中 3. 在项目配置文件中添加模块引用 ## 使用说明 ### 基础用法 #### 1. 导入缓存管理器 ```typescript import { SimpleCacheManager, LocalCacheManager, CacheStats } from 'localcache'; ``` #### 2. 初始化缓存管理器 ```typescript // 使用简单缓存管理器（仅内存缓存） const simpleCache = new SimpleCacheManager(); // 使用本地缓存管理器（内存+持久化） const localCache = new LocalCacheManager(getContext()); await localCache.init(); ``` #### 3. 存储数据 ```typescript // 存储字符串 await cache.set('username', 'john_doe'); // 存储对象 await cache.set('userInfo', { name: '张三', age: 25 }); // 设置过期时间（毫秒） await cache.set('tempData', 'temporary', 60000); // 1分钟后过期 ``` #### 4. 读取数据 ```typescript const result = await cache.get('username'); if (result.success && result.data) { console.log('用户名:', result.data); } else { console.log('获取失败:', result.error?.message); } ``` #### 5. 删除数据 ```typescript await cache.remove('username'); ``` #### 6. 清空缓存 ```typescript await cache.clear(); ``` ### 图片缓存使用 ```typescript import { ImageCacheManager } from 'localcache'; const localCache = new LocalCacheManager(getContext()); await localCache.init(); const imageCache = new ImageCacheManager(localCache); // 缓存图片 const result = await imageCache.cacheImage('https://example.com/image.jpg'); if (result.success && result.data) { // 使用 PixelMap console.log('图片缓存成功'); } // 获取缓存的图片 const cachedImage = await imageCache.getImage('https://example.com/image.jpg'); ``` ### 缓存统计 ```typescript const stats = cache.getStats(); if (stats.success && stats.data) { console.log('命中次数:', stats.data.hitCount); console.log('未命中次数:', stats.data.missCount); console.log('命中率:', stats.data.hitRate); } ``` ## 接口说明 ### SimpleCacheManager #### 构造函数 ```typescript constructor(maxSize?: number, maxItemSize?: number) ``` - `maxSize`: 最大缓存大小（字节），默认 50MB - `maxItemSize`: 单个缓存项最大大小（字节），默认 10MB #### 主要方法 ##### set(key: string, value: T, ttl?: number): Promise> 存储数据到缓存 - `key`: 缓存键 - `value`: 要缓存的数据 - `ttl`: 过期时间（毫秒），可选 - 返回: Promise> ##### get(key: string): Promise> 从缓存获取数据 - `key`: 缓存键 - 返回: Promise> ##### remove(key: string): Promise> 删除缓存项 - `key`: 缓存键 - 返回: Promise> ##### clear(): Promise> 清空所有缓存 - 返回: Promise> ##### getStats(): CacheResult 获取缓存统计信息 - 返回: CacheResult ### LocalCacheManager 继承自 SimpleCacheManager，额外提供持久化功能。 #### 构造函数 ```typescript constructor(context: Context, maxSize?: number, maxItemSize?: number) ``` - `context`: 应用上下文 - `maxSize`: 最大缓存大小（字节），默认 50MB - `maxItemSize`: 单个缓存项最大大小（字节），默认 10MB #### 额外方法 ##### init(): Promise> 初始化缓存管理器（必须调用） - 返回: Promise> ##### cleanupExpired(): Promise> 清理过期数据 - 返回: Promise> - 返回清理的项目数量 ### ImageCacheManager #### 构造函数 ```typescript constructor(cacheManager: LocalCacheManager) ``` - `cacheManager`: LocalCacheManager 实例 #### 主要方法 ##### cacheImage(url: string, ttl?: number): Promise> 缓存网络图片 - `url`: 图片URL - `ttl`: 过期时间（毫秒），可选 - 返回: Promise> ##### getImage(url: string): Promise> 获取缓存的图片 - `url`: 图片URL - 返回: Promise> ##### clearImageCache(): Promise> 清空图片缓存 - 返回: Promise> ### 数据类型 #### CacheResult ```typescript interface CacheResult { success: boolean; data: T | null; error: CacheError | null; } ``` #### CacheStats ```typescript interface CacheStats { hitCount: number; // 命中次数 missCount: number; // 未命中次数 hitRate: number; // 命中率 currentSize: number; // 当前缓存大小（字节） itemCount: number; // 缓存项数量 } ``` #### CacheError ```typescript class CacheError { code: CacheErrorCode; message: string; context: object | null; } ``` #### CacheErrorCode ```typescript enum CacheErrorCode { INVALID_PARAMETER = 'INVALID_PARAMETER', KEY_NOT_FOUND = 'KEY_NOT_FOUND', CACHE_SIZE_EXCEEDED = 'CACHE_SIZE_EXCEEDED', SERIALIZATION_ERROR = 'SERIALIZATION_ERROR', DESERIALIZATION_ERROR = 'DESERIALIZATION_ERROR', STORAGE_ACCESS_DENIED = 'STORAGE_ACCESS_DENIED', CACHE_INITIALIZATION_FAILED = 'CACHE_INITIALIZATION_FAILED', CACHE_EXPIRED = 'CACHE_EXPIRED', CACHE_CLEANUP_FAILED = 'CACHE_CLEANUP_FAILED', NETWORK_ERROR = 'NETWORK_ERROR', IMAGE_LOAD_FAILED = 'IMAGE_LOAD_FAILED', IMAGE_NOT_FOUND = 'IMAGE_NOT_FOUND' } ``` ## 开源声明 本项目采用 **Apache License 2.0 开源许可证**，允许任何人自由使用、修改和分发本软件。 ### 许可证条款 - ✅ 商业使用 - ✅ 修改代码 - ✅ 分发软件 - ✅ 私人使用 - ✅ 专利使用 ### 致谢 感谢所有为本项目做出贡献的开发者和用户！ --- **Copyright © 2024 冬梅. All rights reserved.**