iii-reactive-backend

响应式后端

类似于：Convex、Firebase、Supabase、Appwrite

核心概念

在任务适用时使用以下概念。并非每个响应式后端都需要这里展示的所有触发器或实时界面。

• 状态就是“数据库”——通过 state::set/get/update/delete/list 执行 CRUD 操作
• 状态触发器会在作用域中的任意值发生变化时自动触发
• 副作用（通知、指标、流推送）以响应式方式连接，而非命令式连接
• 流向已连接的客户端实时传送更新

架构

HTTP CRUD endpoints
  → state::set/update/delete (writes to 'todos' scope)
    ↓ (automatic state triggers)
    → on-change → stream::send (push to clients)
    → update-metrics → state::update (aggregate counters)

HTTP GET /metrics → reads from 'todo-metrics' scope
WebSocket clients ← stream 'todos-live'

iii 使用的原语

原语	用途
registerWorker	初始化工作进程并连接到 iii
registerFunction	CRUD 处理程序和响应式副作用
trigger({ function_id: 'state::...', payload })	数据库层
registerTrigger({ type: 'state', config: { scope } })	响应作用域中的任意变化
trigger({ ..., action: TriggerAction.Void() })	向客户端推送流，不等待结果
registerTrigger({ type: 'http' })	REST 端点

参考实现

完整可运行示例见 ../references/reactive-backend.js——一个实时待办应用，包含 CRUD 端点、通过流自动广播变更，以及响应式聚合指标。

常见模式

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

• registerWorker(url, { workerName })——初始化工作进程
• trigger({ function_id: 'state::set/get', payload: { scope, key, value } })——通过状态模块执行 CRUD 操作
• registerTrigger({ type: 'state', function_id, config: { scope } })——状态变更时触发响应式副作用
• 在响应式处理程序中解构事件参数：async (event) => { const { new_value, old_value, key } = event }
• trigger({ function_id: 'stream::send', payload, action: TriggerAction.Void() })——向客户端推送实时更新
• const logger = new Logger()——在处理程序中进行结构化日志记录

调整此模式

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

• 状态触发器会在作用域中的任意变化时触发——使用 event 参数（new_value、old_value、key）来判断发生了什么变化
• 多个函数可以独立响应同一作用域（on-change 和 update-metrics 都监听 todos）
• 流客户端通过 ws://host:port/stream/{stream_name}/{group_id} 连接
• 保持响应式函数快速运行——必要时将繁重工作转交给队列处理

模式边界

• 如果请求重点是通过 registerFunction 注册外部／旧版 HTTP 端点（尤其是包含 { path, id } 等端点列表并进行迭代的情况），优先使用 iii-http-invoked-functions。
• 当状态作用域、状态触发器和实时流更新是核心需求时，使用 iii-reactive-backend。

适用场景

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

边界

• 切勿将此技能用作无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，切勿使用此技能。
• 应用此技能中的示例前，始终确认环境和安全限制。