浏览器缓存工具

Cache 是基于 localStorage 的轻量缓存工具。它以缓存空间隔离数据，并提供内存复用、过期控制、字段更新和清理能力，适合保存页面状态、用户偏好及不频繁变化的接口数据。

快速开始

先创建一个具名缓存实例，再通过 set() 保存对象。相同名称始终复用同一个实例，不同名称之间的数据互不影响。

const userCache = GB.Cache('user');

userCache.set({
  id: 1,
  name: 'zhoubo'
}, 3600);

console.log(userCache.get('name'));
// zhoubo

安装与引入

浏览器直接引入

在业务脚本之前引入，之后即可使用全局方法 GB.Cache(name)。

<script src="https://cloud.m775.net/js/cache.js"></script>

npm 项目

npm i @gentbo/cache

import '@gentbo/cache';

缓存空间与实例复用

GB.Cache(name) 中的 name 是缓存空间名称，也是对应的 localStorage 主键。请按业务用途命名，例如用户、配置和令牌分别使用独立空间。

GB.Cache('user')保存当前用户的基础信息、界面偏好等数据。

GB.Cache('config')保存应用配置，不会与用户缓存互相覆盖。

GB.Cache('token')创建独立的令牌缓存空间；敏感令牌仍应谨慎保存。

const first = GB.Cache('user');
const second = GB.Cache('user');

console.log(first === second);
// true

有效期规则

涉及持久化的方法都可传入 expiry。未过期的数据会从 localStorage 加载到内存；之后的读取优先使用内存，减少重复解析。

expiry: false只操作当前内存数据，不写入或删除 localStorage。

expiry: -1永久保存，除非主动清理。

expiry: 0删除对应的持久化缓存。

expiry: > 0以秒为单位设置有效期；过期后缓存会自动删除。

// 将用户信息保存 1 小时
GB.Cache('user').set({ name: 'zhoubo' }, 3600);

// 永久保存主题配置
GB.Cache('config').add('theme', 'dark', -1);

读取与写入数据

.get(key?, expiry?)读取全部缓存或指定字段；字段不存在时返回 null。传入 expiry 可在读取时刷新有效期。

.set(data, expiry?)重置整个缓存空间。原有字段会被新对象完全替换。

.add(key, data, expiry?)新增或更新一个字段，适合在保留已有缓存的前提下补充数据。

.expiry(expiry)直接调整当前缓存空间的持久化有效期。

const cache = GB.Cache('user');

cache.set({ id: 1, name: 'zhoubo' }, 3600);
cache.add('token', 'abcdef', 3600);

console.log(cache.get());
// { id: 1, name: 'zhoubo', token: 'abcdef' }

console.log(cache.get('token'));
// abcdef

删除与清空

.delete(key, expiry?)删除指定字段，其余字段保持不变。

.clear()清空当前实例的内存数据，并移除对应的 localStorage 数据。

const cache = GB.Cache('user');

cache.delete('token');
cache.clear();

适合缓存什么

页面状态列表筛选条件、当前标签页、滚动位置或用户的界面偏好。

配置信息主题、语言、壁纸和不频繁变化的应用配置。

接口结果适合短期复用且允许存在一定时效性的接口数据。

临时业务数据跨刷新保留的小型草稿、步骤进度或表单状态。

使用边界

Cache 最终通过 JSON.stringify() 持久化，建议保存 Object、Array、String、Number 和 Boolean 等可序列化数据。函数、DOM 节点和循环引用对象不适合保存。

localStorage 空间由浏览器限制，不应用于大文件、图片、超大 JSON 或高频写入场景。数据可被用户在浏览器中查看，因此不要存储密码、私钥或明文身份认证信息。