封装通用 localstorage 缓存管理类,统一处理序列化、反序列化、ttl 过期校验与错误边界,支持自动 json 转换、命名空间隔离、批量操作及静默降级。

直接封装一个通用的 LocalStorage 缓存管理类,核心是统一处理序列化、反序列化、过期逻辑和错误边界,避免每次手动 JSON.stringify 和 JSON.parse,同时支持设置 TTL(Time-To-Live)。
支持自动序列化与类型安全
LocalStorage 只支持字符串,所以读写必须做类型转换。封装时应默认对任意值(对象、数组、数字、布尔、null)执行 JSON 序列化,读取时尝试解析,失败则返回 null 或原始字符串(视需求而定)。
- 写入时:非字符串值自动
JSON.stringify(),字符串原样保留(可加标识区分原生字符串) - 读取时:先尝试
JSON.parse(),捕获异常后返回null,不抛错 - 可选:用前缀或包装结构标记数据类型(如
{"v": ..., "t": "json", "e": 171xxxx}),便于扩展
内置 TTL 过期控制
原生 LocalStorage 不支持过期,需手动存时间戳并读取时校验。推荐在存值时一并保存过期时间,读取时对比当前时间。
- 存值时:额外存一个
key + "_expires"的时间戳,或把 value 和 expires 打包成对象统一存 - 读值时:先检查是否过期,过期则自动移除并返回
null - 注意:不能只依赖读时判断,要配合写时清理逻辑,避免过期数据长期残留
提供简洁易用的 API 接口
对外暴露类似 Map 的方法,降低使用成本,比如 set(key, value, expires?)、get(key)、remove(key)、clear(),全部带错误静默处理(如 Storage 不可用时不报错)。
-
set(key, value, ttlMs):支持毫秒级 TTL,0 或负数表示永不过期 -
get(key):返回解析后的值,过期或无效时返回undefined -
has(key):检查 key 是否存在且未过期 - 所有操作包裹
try/catch,localStorage 不可用(如无痕模式)时降级为内存缓存或静默失败
可选增强:命名空间与批量操作
大型项目中多个模块共用 LocalStorage 易冲突,可通过前缀隔离;高频读写场景下支持批量 set/get 能减少重复序列化开销。
- 初始化时传入
namespace(如"user:"),所有 key 自动拼接前缀 - 提供
setMany(entries)和getMany(keys),内部复用同一 try/catch 和序列化逻辑 - 暴露
keys()和size()(过滤掉 expires 辅助键)便于调试和清理
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











