键值存储

支持 TTL 的快速键值存储。适用于缓存、会话和临时状态。

存储配置请参阅 存储。

加载

local store = require("store")

获取存储

通过注册表 ID 获取存储资源：

local cache, err = store.get("app:cache")
if err then
    return nil, err
end

cache:set("user:123", {name = "Alice"}, 3600)
local user = cache:get("user:123")

cache:release()

返回: Store, error

存储值

存储值并可选设置 TTL：

local cache = store.get("app:cache")

-- 简单设置
cache:set("user:123:name", "Alice")

-- 设置 TTL（300 秒后过期）
cache:set("session:abc", {user_id = 123, role = "admin"}, 300)

返回: boolean, error

获取值

通过键获取值：

local user = cache:get("user:123")
if not user then
    -- 键不存在或已过期
end

返回: any, error

如果键不存在或已过期，返回 nil 和一个 errors.NOT_FOUND 错误。

检查存在

检查键是否存在而不获取值：

if cache:has("lock:" .. resource_id) then
    return nil, errors.new({ kind = errors.CONFLICT, message = "Resource is locked" })
end

返回: boolean, error

删除键

从存储中删除键：

cache:delete("session:" .. session_id)

返回: boolean, error

如果删除成功返回 true，如果键不存在返回 false。

读取 Entry 元数据

entry 返回值及其 version——一个用于乐观并发控制的不透明字符串：

local e, err = cache:entry("user:123")
if e then
    print(e.key, e.value, e.version)
end

返回: Entry, error — {key: string, value: any, version: string}

列出键

按确定的键顺序列出条目，支持分页：

local page, err = cache:list({ prefix = "session:", limit = 100 })
for _, e in ipairs(page.items) do
    print(e.key, e.value)
end

-- next page
if page.has_more then
    page = cache:list({ prefix = "session:", after = page.cursor })
end

返回: Page, error — {items: Entry[], cursor: string, has_more: boolean}

条件写入

put 写入一个值并返回其新的 Entry。选项可启用乐观并发控制：

-- create only if the key does not exist
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == errors.ALREADY_EXISTS then
    -- someone else holds it
end

-- compare-and-set: write only if the version still matches
local cur = cache:entry("config")
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == errors.CONFLICT then
    -- a concurrent writer changed it; re-read and retry
end

only_if_absent 和 if_version 互斥。

返回: Entry, error

存储能力

info 报告后端及其支持的功能，使代码可以适配所绑定的任何存储：

local info = cache:info()
-- info.backend      -> one of store.backend.* (e.g. "kv.raft")
-- info.consistency  -> one of store.consistency.* (e.g. "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (booleans)

返回: Info, error — {id, backend, consistency, durable, list, versioned, conditional_put, ttl}

常量

if cache:info().consistency == store.consistency.LINEARIZABLE then
    -- safe to use compare-and-set
end

存储方法

权限

存储操作受安全策略评估约束。

错误

store.get() 以及存储句柄上的所有方法（get、entry、set、put、list、has、delete、info）都返回结构化错误（使用 err:kind()），但 store.get、get、set、has 和 delete 中的权限拒绝会抛出 Lua 错误而非返回错误。

错误处理请参阅 错误处理。