Storage 存储方法 API

本文逐项记录 @fast-china/utils 的 Storage 存储公开函数。

configureStorage 存储配置

在首次 Storage 操作前可选配置 Local 与 Session。

签名

export function configureStorage(options: StorageConfiguration = {}): void;

示例

import { configureStorage } from "@fast-china/utils";

configureStorage({ prefix: "admin:", crypto: false });

输入

输入值	输入值类型	必填/默认值	输入值说明
options	StorageConfiguration	否，默认 {}	可选的全局键前缀、Codec、Base64 混淆选项与时钟。

返回： void。

isStorageConfigured 存储配置

返回全局 Storage 是否已激活；显式配置或第一次 Storage 操作都会激活它。

签名

export function isStorageConfigured(): boolean;

示例

import { isStorageConfigured } from "@fast-china/utils";

const result = isStorageConfigured();

输入： 无参数。

返回

返回值	返回值类型	返回值说明
result	boolean	已显式配置或因首次操作激活时为 true。

Local.get / Session.get 读取

读取并解码当前命名空间的业务值；过期记录会被删除。

签名

get<Value = string>(key: string, options?: StorageReadOptions): Value | undefined;

示例

import { Local } from "@fast-china/utils";

const result = Local.get<{ name: string }>("profile");

输入

输入值	输入值类型	必填/默认值	输入值说明
key	string	是	不含全局前缀的非空业务键。
options	StorageReadOptions	否	单次 Base64 Codec 覆盖，必须与写入时一致。

返回

返回值	返回值类型	返回值说明
result	Value | undefined	解码后的业务值；键缺失或过期时返回 undefined。

Local.set / Session.set 写入

编码并写入业务值，可附加 TTL。

签名

set<Value>(key: string, value: Value, options?: StorageWriteOptions): void;

示例

import { Local } from "@fast-china/utils";

Local.set("profile", { name: "Fast" }, { ttlMs: 3_600_000 });

输入

输入值	输入值类型	必填/默认值	输入值说明
key	string	是	不含全局前缀的非空业务键。
value	Value	是	当前 Codec 能够序列化的业务值。
options	StorageWriteOptions	否	单次 Codec 与有效毫秒数。

返回： void。非法键、TTL、值或后端失败时抛错。

Local.has / Session.has 存在

判断键是否存在、未过期且存储包络有效；不执行值的 Codec 解码。

签名

has(key: string): boolean;

示例

import { Local } from "@fast-china/utils";

const result = Local.has("profile");

输入

输入值	输入值类型	必填/默认值	输入值说明
key	string	是	不含全局前缀的非空业务键。

返回

返回值	返回值类型	返回值说明
result	boolean	键存在且包络有效时为 true。

Local.keys / Session.keys 键名

枚举当前命名空间的业务键。

签名

keys(): string[];

示例

import { Local } from "@fast-china/utils";

const result = Local.keys();

输入： 无参数。

返回

返回值	返回值类型	返回值说明
result	string[]	移除物理前缀并按字典序排列的新数组。

Local.remove / Session.remove 删除

幂等删除单个业务键。

签名

remove(key: string): void;

示例

import { Local } from "@fast-china/utils";

Local.remove("profile");

输入

输入值	输入值类型	必填/默认值	输入值说明
key	string	是	不含全局前缀的非空业务键。

返回： void。

Local.removeByPrefix / Session.removeByPrefix 按前缀删除

删除当前命名空间中以指定文本开头的全部业务键。

签名

removeByPrefix(keyPrefix: string): void;

示例

import { Local } from "@fast-china/utils";

Local.removeByPrefix("profile:");

输入

输入值	输入值类型	必填/默认值	输入值说明
keyPrefix	string	是	不含全局前缀的非空业务键前缀。

返回： void。不会影响命名空间以外的键。

Local.pruneExpired / Session.pruneExpired 清理过期

扫描并删除当前命名空间的全部过期记录。

签名

pruneExpired(): number;

示例

import { Local } from "@fast-china/utils";

const result = Local.pruneExpired();

输入： 无参数。

返回

返回值	返回值类型	返回值说明
result	number	本次实际删除的记录数量。

Local.clear / Session.clear 清空

清空当前命名空间，不影响同一后端的其他应用键。

签名

clear(): void;

示例

import { Session } from "@fast-china/utils";

Session.clear();

输入： 无参数。

返回： void。

共享行为与边界

configureStorage 必须在第一次 Storage 操作之前调用；默认使用 fast__ 前缀与 JSON Codec。 配置激活后，相同配置重复调用幂等，不同配置抛错。get 的泛型只影响静态类型，不验证或转换实际业务结构。 set/get 的单次 crypto 选项必须配对；包络不记录 Codec。Base64 混淆不能保护敏感数据。 读取过期条目可能删除该条目。clear 只清理当前前缀；uni-app 不提供 Session 后端，Session 操作会抛错。 存储配额、隐私策略、非法 JSON 和后端不可用等错误按实际操作传播，不能把失败当作缓存未命中。