iii-state-management

状态管理

可比较的产品：Redis、DynamoDB、Memcached

核心概念

在适合任务的情况下使用以下概念。并非每种状态操作都需要用到所有概念。

• 状态是通过内置触发函数访问的作用域化键值存储
• state::set 用于写入值；state::get 用于读取值（键不存在时返回 null）
• state::list 用于获取作用域中的所有键；state::delete 用于移除一个键
• state::update 使用 ops 数组执行部分合并，以进行细粒度更改
• 载荷使用 scope、key 和 value 来定位状态条目
• 所有函数共享状态，因此请使用有意义的作用域名称来避免冲突

架构

Function
  → trigger('state::set', { scope, key, value })
  → trigger('state::get', { scope, key })
  → trigger('state::update', { scope, key, ops })
  → trigger('state::delete', { scope, key })
  → trigger('state::list', { scope })
    → StateModule → KvStore / Redis adapter

使用的 iii 原语

原语	用途
trigger({ function_id: 'state::set', payload })	将值写入状态
trigger({ function_id: 'state::get', payload })	从状态读取值
trigger({ function_id: 'state::list', payload })	列出作用域中的所有键
trigger({ function_id: 'state::delete', payload })	从状态中移除一个键
trigger({ function_id: 'state::update', payload: { ops } })	使用操作数组进行部分合并

参考实现

完整可运行示例请参见 ../references/state-management.js — 其中的函数可在共享作用域中读取、写入、更新和删除状态条目。

另有 Python 版本：../references/state-management.py

另有 Rust 版本：../references/state-management.rs

常见模式

根据需要，使用此模式的代码通常包括：

• registerWorker(url, { workerName }) — 初始化 worker
• trigger({ function_id: 'state::set', payload: { scope, key, value } }) — 写入状态
• trigger({ function_id: 'state::get', payload: { scope, key } }) — 读取状态（缺失时返回 null）
• trigger({ function_id: 'state::update', payload: { scope, key, ops } }) — 部分合并
• trigger({ function_id: 'state::list', payload: { scope } }) — 枚举键
• trigger({ function_id: 'state::delete', payload: { scope, key } }) — 移除条目
• const logger = new Logger() — 结构化日志记录

调整此模式

在适用时使用以下调整方式。

• 根据你的领域为作用域命名（例如 user-sessions、order-data、config）
• 使用带有 null 检查的 state::get，妥善处理缺失的键
• 使用带有 ops 的 state::update 进行部分更新，而不是执行读取-修改-写入循环
• 与 iii-queue-processing 结合，在异步任务完成后持久化结果

引擎配置

必须在 iii-config.yaml 中启用 StateModule，并配置 KvStore 适配器（基于文件或 Redis）。完整的注释配置参考请参见 ../references/iii-config.yaml。

模式边界

• 如果任务需要在状态变化时触发响应式副作用，请优先使用 iii-state-reactions。
• 如果任务需要在数据更新时实时向客户端推送，请优先使用 iii-realtime-streams。
• 如果主要需求是读取和写入持久化键值数据，请使用 iii-state-management。

适用场景

• 当任务主要涉及 iii 引擎中的 iii-state-management 时，使用此技能。
• 当请求直接提出此模式或要求等效实现时触发。

边界

• 切勿将此技能用作无关任务的通用回退方案。
• 如果有更具体的 iii 技能更适合，就不得使用此技能。
• 应用此技能中的示例前，务必先确认环境和安全约束。