用途:iii-state 是服务端键值存储 worker,值按 scope(命名空间)与 key 寻址,在所有连接到引擎的 worker 间共享,并通过可插拔适配器持久化。调用方通过 iii.trigger({ function_id: 'state::...', payload }) 使用六个 state::* 函数。
主要能力:state::set 写入或替换值并触发 state:created 或 state:updated;state::get 读取单个值;state::delete 删除键并以旧值触发 state:deleted;state::update 对已存值应用有序原子操作(set、merge、increment、decrement、append、remove);state::list 枚举某 scope 内全部值;state::list_groups 枚举当前含数据的 scope。适配器包括默认 kv(支持 in_memory 或 file_based 持久化)、redis(代理到 Redis 后端)、bridge(转发到远程 iii 引擎),函数接口在各适配器间一致。
使用方式:状态不向 SDK 客户端推送更新,响应式由 state 触发器类型提供,在每次成功变更后触发 state:created、state:updated 或 state:deleted。绑定方式为先用 iii.registerFunction 注册处理函数,再用 iii.registerTrigger 注册触发器,config 支持可选的 scope、key 与 condition_function_id;所有字段可选,过滤越紧处理函数运行越少,监听多个特定键需为每个 scope/key 对注册一个触发器。事件负载结构可对触发器类型或处理函数 id 调用 iii get function info 获取。
适用场景:两个及以上函数需要共享状态而不想单独搭建数据库;计数器或按实体文档需要原子部分更新而非读改写;一个函数的写入应触发其他位置副作用(缓存失效、审计日志、通知、投影);只想在特定 scope/key 变化时被监听并响应。
限制:设计上无 schema,每个值都是不透明 JSON,需要注册 JSON Schema 与校验时应使用 configuration。读取(state::get、state::list、state::list_groups)不触发触发器,只有 set/update/delete 会。触发器投递是异步的,处理函数失败不会回滚写入;删除不存在的键仍会以 null 旧值发出 state:deleted。流式、广播给订阅者的数据应使用 iii-stream 而非本工具。若只需在同一函数内拿到新值,应使用变更操作返回的 old_value / new_value,而非绑定触发器。