📘 GENTBO Cache Tool

GB.Cache 是一个轻量级浏览器缓存管理工具。

基于浏览器原生 localStorage 实现缓存数据管理，提供：

• 数据读取
• 数据写入
• 数据更新
• 数据删除
• 缓存有效期管理
• 多缓存空间隔离

适用于：

• 页面状态缓存
• 用户信息缓存
• 配置信息缓存
• 接口数据缓存
• 临时数据存储

特点

• 🚀 零依赖
• ⚡ 轻量高效
• 💾 基于 localStorage 持久化存储
• 🧠 内存缓存减少重复读取
• 🔒 Class Private Field 私有化数据
• ⏱ 支持缓存有效期控制
• 📦 支持多个缓存空间隔离
• 🔗 简单易用 API
• 🌐 支持浏览器环境

安装

直接引入：

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

npm：

npm i @gentbo/cache

import "@gentbo/cache";

使用方式

创建缓存实例：

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

其中：

user

为缓存名称，同时也是：

• localStorage 主键
• 缓存命名空间

例如：

GB.Cache("user");

GB.Cache("config");

GB.Cache("token");

三个缓存空间相互独立。

缓存机制

GB.Cache 使用双层缓存结构：

GB.Cache

    |
    |
    +-- 内存缓存

    |
    |
    +-- localStorage 持久化缓存

工作流程：

1. 创建缓存实例时读取 localStorage。

2. 如果缓存存在且未过期，则加载到内存。

3. 后续操作优先使用内存数据。

4. 设置有效期后同步保存到 localStorage。

5. 超过有效期自动删除缓存。

缓存有效期

所有涉及持久化的方法均支持 expiry 参数。

| 值 | 说明 | | --- | --- | | false | 仅操作当前内存缓存，不处理持久化 | | 0 | 删除持久化缓存 | | -1 | 永久缓存 | | 大于0 | 指定秒数有效 |

示例：

GB.Cache("user")
.set(
    {
        name:"zhoubo"
    },
    3600
);

表示：

缓存有效时间 3600 秒

API

GB.Cache(name)

创建缓存实例。

参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | name | string | 缓存名称 |

示例：

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

返回：

Cache

expiry()

设置缓存有效期。

参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | expiry | number | 有效期秒数 |

示例：

GB.Cache("user")
.expiry(3600);

说明：

| 参数 | 效果 | | --- | --- | | -1 | 永久缓存 | | >0 | 指定秒数缓存 | | 0 | 删除持久化缓存 |

get()

获取缓存数据。

参数

| 参数 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | key | string/null | null | 缓存字段名称 | | expiry | number/false | false | 自动刷新有效期 |

获取全部缓存

const data = GB.Cache("user")
.get();

返回：

{
    name:"zhoubo",
    age:18
}

获取指定字段

const name = GB.Cache("user")
.get("name");

返回：

zhoubo

不存在时：

null

set()

重置缓存数据。

参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | data | object | 缓存数据 | | expiry | number/false | 有效期 |

示例：

GB.Cache("user")
.set(
    {
        id:1,
        name:"zhoubo"
    },
    3600
);

add()

添加或修改单个缓存字段。

参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | key | string | 字段名称 | | data | any | 字段数据 | | expiry | number/false | 有效期 |

示例：

GB.Cache("user")
.add(
    "token",
    "abcdef",
    3600
);

缓存结果：

{
    token:"abcdef"
}

delete()

删除缓存字段。

参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | key | string | 字段名称 | | expiry | number/false | 有效期 |

示例：

GB.Cache("user")
.delete(
    "token"
);

clear()

清空当前缓存。

示例：

GB.Cache("user")
.clear();

执行后：

• 清空内存缓存
• 删除 localStorage 数据

综合示例

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


// 保存用户信息

cache.set(
    {
        id:1,
        name:"zhoubo"
    },
    3600
);


// 获取全部数据

const user = cache.get();

console.log(user);


// 获取指定字段

console.log(
    cache.get("name")
);


// 添加 Token

cache.add(
    "token",
    "abcdef",
    3600
);


// 删除 Token

cache.delete(
    "token"
);


// 清空缓存

cache.clear();

多缓存空间

不同缓存名称相互独立。

示例：

const user =
GB.Cache("user");


const config =
GB.Cache("config");


const token =
GB.Cache("token");

对应：

localStorage

    user

    config

    token

不会相互覆盖。

缓存实例复用

同一个缓存名称只创建一个实例。

例如：

const a =
GB.Cache("user");


const b =
GB.Cache("user");

结果：

a === b

返回：

true

注意事项

数据类型

缓存数据最终通过：

JSON.stringify()

进行序列化保存。

支持：

• Object
• Array
• String
• Number
• Boolean

不建议保存：

• Function
• DOM 节点
• 循环引用对象

存储限制

localStorage 存储空间由浏览器限制。

不建议用于：

• 大量文件
• 图片数据
• 超大 JSON 数据
• 高频写入数据

数据覆盖

使用 set() 方法会直接覆盖当前缓存数据。

例如：

GB.Cache("user")
.set({
    name:"zhoubo"
});

原数据：

{
    id:1,
    name:"zhoubo",
    token:"abcdef"
}

执行后：

{
    name:"zhoubo"
}

如果需要保留原数据，请使用：

add()

安全说明

localStorage 数据可以被用户查看。

不建议保存：

• 密码
• 私钥
• 高敏感数据
• 明文身份认证信息

浏览器支持

支持：

• Chrome
• Edge
• Firefox
• Safari
• 微信浏览器
• 支付宝浏览器
• 国产 Chromium 浏览器

要求：

• ES2020+
• Class Private Field (#)
• localStorage

Gentbo Custom License

Copyright (c) 2016-Present Zhou Bo
Website: https://developer.gentbo.com

Permission is granted to use this software for personal, educational, and commercial projects without modification.

You may not:

1. Modify this software.
2. Reverse engineer, decompile, or create derivative works based on this software.
3. Redistribute, resell, sublicense, or publish this software or modified versions.
4. Remove or alter copyright notices.

This software is provided "as is", without warranty of any kind. For commercial redistribution, OEM licensing, or special authorization:

Email: [email protected] QQ: 18486685 QQGroup: 431849998