uni-storage 0.1.0 发布：TTL过期管理+多实例隔离

v0.1.0 为首个可用版本：以 uni.setStorage
系列原生 API 为唯一底层依赖、不重造存储栈，把 TTL 过期管理、key 命名规范、Promise 化、多实例隔离这些每次都要重写的重复劳动收进一套 axios 心智的 API。Web 端 22 项功能验证日志全部通过；Android
Kotlin 编译链已打通，云打包 release 编译零错误，真机用例验证待进行。

一、为什么做这个库

直接用 uni.setStorage 写业务，四件事反复发生：

回调风格：原生 API 是 success/fail 回调，异步编排与错误处理全靠业务手工包装
无过期管理：缓存写进去就是永久的，TTL 轮转要自己包时间戳、自己扫过期
key 裸奔：命名无规范，clear() 一键清库会误伤框架与其他模块数据（uni- / dcloud_ 保留前缀冲突）
无多实例：不同业务域的缓存共享一个扁平 key 空间，隔离全靠约定

unix-storage 把这些收敛成一套库：写过 axios 的开发者看一眼 API 就能上手；clear / 清理只作用于本命名空间；全链路强类型标注。

二、核心能力

Promise 化全量 API

import { set, get } from '@/uni_modules/ux-storage'

await set('token', tokenInfo, 3600_000)
const token = await get('token') // 未命中 / 已过期返回 null，不 reject

set / get<T> / remove / clear / info / keys / clearExpired 全量 async/await，业务侧不再手写 success/fail 包装。

TTL 过期管理

record 包裹过期时间戳，读取惰性判断（Date.now() > expire 即移除并返回 null）；clearExpired() 全量扫描返回清理条数。TTL 三级回退：调用级 ttl → 实例 defaultTTL → 内置永不过期，对齐 unix-request 三级合并心智。

key 前缀命名空间

默认前缀 mx_storage:（规避 uni- / dcloud_ 平台保留前缀，非法前缀在操作期以 ERR_PARAM 拦截）；keys() 剥前缀返回原始 key；clear() 按前缀过滤后逐个移除——只清理本命名空间，不触碰其他数据。

多实例

import { createStorage } from '@/uni_modules/ux-storage'
import type { StorageDefaults } from '@/uni_modules/ux-storage'

const cacheStore = createStorage({ keyPrefix: 'api_cache:', defaultTTL: 300_000 } as StorageDefaults)
await cacheStore.set('user:1', user, null) // 前缀独立，与默认实例互不可见

默认实例开箱即用，configureStorage 配置全局默认；createStorage(defaults) 创建隔离实例，心智对标 axios.create。

统一可预测的错误结构

StorageError 收敛 2 类错误码（ERR_PARAM 参数 / 保留前缀拦截、ERR_NATIVE 原生失败），原生 errCode 经 nativeErrCode 原值透传不翻译，errSubject 固定 unix-storage，key
挂载关联业务原始 key——错误定位不用翻底层日志。

兼容策略

读到非本库写入格式的数据（业务直写原生 API 的存量数据）按「无过期」原样返回，不报错、不误删。

三、平台支持现状

平台	状态
Web	✅ 编译产物验证，22 项功能验证日志全部通过（基础存取 / TTL / 命名空间与多实例 / 全局配置 / clearExpired / 错误路径六个验证页）
微信小程序	代码全端同构（`uni.setStorage` 系列全端统一），待实测
Android	✅ 云打包 release 编译零错误；真机用例验证待进行
iOS / 鸿蒙	⏳ 代码已适配，受环境限制暂未实测（iOS 需 macOS、鸿蒙需 DevEco Studio）

四、快速上手

pnpm add @meng-xi/unix-storage
mkdir -p uni_modules && cp -R node_modules/@meng-xi/unix-storage uni_modules/ux-storage

import { set, get, configureStorage } from '@/uni_modules/ux-storage'
import type { StorageDefaults, StorageError } from '@/uni_modules/ux-storage'

// 项目启动时配置一次全局默认（如 App.uvue onLaunch；null 表示沿用内置默认）
configureStorage({
	keyPrefix: null, // null 沿用内置默认 'mx_storage:'
	defaultTTL: null // null 永不过期
})

set('theme', 'dark', null).then(() => {
	console.log('已写入')
}).catch((err) => {
	const e = err as StorageError
	console.log(e.code, e.errMsg)
})

不想搭工程？安卓真机可直接下载体验 App：下载体验 App（APK）——上述示例工程的云打包产物，安装后即可在真机运行全部用例。

五、文档与资源

📖 完整文档（指南 11 篇 + API 3 篇，中英双语，从入门到精通）
📝 更新日志

六、交流与关注

想了解设计思路与实现原理（record 包裹与惰性过期、命名空间实现、UTS 跨语言编译红线等）？公众号「梦曦工作室」有系列解析，扫码关注：

PedroQue99