前言

缓存是提升应用性能的重要手段，合理的缓存策略可以减少网络请求和重复计算。@pura/harmony-utils 的 CacheUtil 封装了内存缓存管理方法，支持过期时间和容量控制。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、CacheUtil核心API

CacheUtil 提供了以下缓存管理方法：

方法	说明	返回类型	使用场景
put(key, value, expireMs)	写入缓存	void	数据缓存
get(key)	读取缓存	Object	缓存查询
remove(key)	删除缓存	void	缓存清理
clear()	清空缓存	void	全量清理
size()	获取缓存数量	number	容量监控

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 过期控制：支持设置缓存过期时间

1.2 缓存策略对照

策略	说明	适用场景
定时过期	设置过期时间	API响应缓存
手动清理	调用clear()	数据刷新
容量控制	监控size()	内存管理

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 写入缓存

import { CacheUtil } from '@pura/harmony-utils';

Button('写入缓存')
  .width('100%')
  .onClick(() => {
    try {
      CacheUtil.put('user_info', { name: '张三', age: 25 }, 60000);
      this.result = '缓存写入成功 ✅\n有效期: 60秒';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 读取缓存

Button('读取缓存')
  .width('100%')
  .onClick(() => {
    try {
      let value = CacheUtil.get('user_info');
      this.result = value ? `缓存命中 ✅\n${JSON.stringify(value)}` : '缓存未命中 ❌\n已过期或不存在';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.4 清空缓存

Button('清空缓存')
  .width('100%')
  .onClick(() => {
    try {
      CacheUtil.clear();
      this.result = '缓存已清空 🧹';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { CacheUtil } from '@pura/harmony-utils';

@Entry
@Component
struct CacheDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('写入缓存').width('100%').onClick(() => {
        CacheUtil.put('test', 'Hello Cache!', 30000);
        this.result = `写入成功，数量: ${CacheUtil.size()}`;
      });
      Button('读取缓存').width('100%').onClick(() => {
        let v = CacheUtil.get('test');
        this.result = v ? `命中: ${v}` : '未命中';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 API响应缓存

import { CacheUtil } from '@pura/harmony-utils';

async function fetchWithCache(url: string, expireMs: number = 60000): Promise<Object> {
  let cached = CacheUtil.get(url);
  if (cached) return cached;
  let response = await fetch(url);
  let data = await response.json();
  CacheUtil.put(url, data, expireMs);
  return data;
}

4.2 缓存预热

function warmUpCache(): void {
  CacheUtil.put('config', loadConfig(), 300000);
  CacheUtil.put('dictionary', loadDictionary(), 600000);
}

五、注意事项

1. 内存缓存：CacheUtil为内存缓存，应用退出后数据丢失
2. 过期时间：过期时间单位为毫秒
3. 容量控制：注意监控缓存数量，避免内存溢出
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 线程安全：多线程访问需注意并发安全

六、常见问题

Q1: 缓存数据在应用重启后还在吗？

不在，CacheUtil是内存缓存，应用退出后数据丢失。持久化请使用Preferences或数据库。

Q2: 如何设置永不过期的缓存？

不传expireMs参数或设置为0，缓存将不会自动过期。

Q3: 缓存占用内存过大怎么办？

定期调用clear()清理，或使用LRUCacheUtil替代。

Q4: get()返回null是什么原因？

可能是缓存已过期、已被删除、或从未写入。

总结

CacheUtil 的缓存管理方法为应用性能优化提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用缓存，可以显著提升应用响应速度。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。