iii-realtime-streams

实时流

可与以下服务相媲美：Socket.io、Pusher、Firebase Realtime

核心概念

在适合任务的情况下使用以下概念。并非每种流配置都需要全部概念。

• StreamModule 在端口 3112 上提供 WebSocket 连接
• 客户端通过 ws://host:3112/stream/{stream_name}/{group_id} 连接
• stream::set / stream::get / stream::list / stream::delete 为流项目提供 CRUD 操作
• stream::send 将事件推送给流组中的所有已连接客户端
• createStream 为非默认流后端注册自定义适配器
• 每个流项目由 stream_name、group_id、item_id 和 data 定位

架构

函数
  → trigger('stream::set', { stream_name, group_id, item_id, data })
  → trigger('stream::send', { stream_name, group_id, data })
    → StreamModule
      → WebSocket 推送
        → 连接到 /stream/{stream_name}/{group_id} 的客户端

使用的 iii 原语

原语	用途
trigger({ function_id: 'stream::set', payload })	创建或更新流项目
trigger({ function_id: 'stream::get', payload })	读取流项目
trigger({ function_id: 'stream::list', payload })	列出流组中的项目
trigger({ function_id: 'stream::delete', payload })	移除流项目
trigger({ function_id: 'stream::send', payload })	向已连接客户端推送事件
createStream	注册自定义流适配器

参考实现

完整可运行示例请参阅 ../references/realtime-streams.js：此流会向 WebSocket 客户端推送实时更新，并通过 CRUD 操作管理流项目。

也提供 Python 版本：../references/realtime-streams.py

也提供 Rust 版本：../references/realtime-streams.rs

常见模式

使用此模式的代码通常会在适用时包含：

• registerWorker(url, { workerName }) — 初始化工作器
• trigger({ function_id: 'stream::set', payload: { stream_name, group_id, item_id, data } }) — 写入流项目
• trigger({ function_id: 'stream::send', payload: { stream_name, group_id, data } }) — 向客户端推送事件
• trigger({ function_id: 'stream::get', payload: { stream_name, group_id, item_id } }) — 读取流项目
• trigger({ function_id: 'stream::list', payload: { stream_name, group_id } }) — 列出组中的项目
• createStream(name, adapter) — 为专用后端创建自定义适配器
• const logger = new Logger() — 结构化日志记录

调整此模式

在适用于任务的情况下使用以下调整方式。

• 根据你的领域为流命名（例如 chat-messages、dashboard-metrics、notifications）
• 使用 group_id 按用户、房间或租户划分流
• 与 iii-state-reactions 结合，在状态发生变化时推送流事件
• 默认适配器不适用时使用 createStream（例如需要自定义持久化或扇出逻辑）

引擎配置

必须在 iii-config.yaml 中启用 StreamModule，并配置端口和适配器（KvStore 或 Redis）。完整的注释版配置参考请参阅 ../references/iii-config.yaml。

模式边界

• 如果任务涉及不需要实时推送的持久化键值数据，请优先使用 iii-state-management。
• 如果任务需要在状态变化时触发响应式操作（服务器端），请优先使用 iii-state-reactions。
• 如果主要需求是向已连接客户端推送实时更新，请继续使用 iii-realtime-streams。

适用场景

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

适用范围

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