用途:在 iii 引擎中实现持久化的作用域键值存储,用于在函数之间保存和共享数据,可类比 Redis、DynamoDB、Memcached。
主要能力:通过内置触发函数操作状态。state::set 写入值;state::get 读取值,键不存在时返回 null;state::list 列出某个作用域内的全部键;state::delete 删除键;state::update 使用 ops 数组进行细粒度部分合并。数据载荷通过 scope、key、value 定位状态条目。状态在所有函数间共享,因此应使用有意义的 scope 名称避免冲突。
使用方式:调用 trigger,传入 function_id 与 payload,例如 trigger({ function_id: 'state::set', payload: { scope, key, value } })、trigger({ function_id: 'state::get', payload: { scope, key } })、trigger({ function_id: 'state::update', payload: { scope, key, ops } })、trigger({ function_id: 'state::list', payload: { scope } })、trigger({ function_id: 'state::delete', payload: { scope, key } })。常见做法包括用 registerWorker(url, { workerName }) 初始化 worker,用 new Logger() 做结构化日志。参考实现提供 JavaScript、Python、Rust 版本。
适用场景:需要读写持久化键值数据时使用;可按领域命名 scope(如 user-sessions、order-data、config);用 state::get 加 null 检查处理缺失键;用 state::update 的 ops 做部分更新以替代读改写循环;可与 iii-queue-processing 结合,在异步任务完成后持久化结果。
限制:iii-state 必须在 iii-config.yaml 中启用,并配置 kv 适配器(基于文件或内存)或单独的 redis 适配器。若需要状态变化时的响应式副作用,应改用 iii-state-reactions;若需要数据更新时向客户端实时推送,应改用 iii-realtime-streams。本技能仅适用于主要需求为读写持久化键值数据的任务,不应作为无关任务的通用回退,也不应在更具体的 iii 技能更合适时使用。应用示例前需先确认环境与安全约束。