iii-workflow-orchestration

工作流编排与持久化执行

可与以下工具相媲美：Temporal、Airflow、Inngest

核心概念

在适合任务的情况下使用以下概念。并非每个工作流都需要此处展示的所有持久化或跟踪机制。

• 每个流水线步骤都是一个已注册函数，通过命名队列串联，并由配置驱动重试
• 步骤进度通过共享状态跟踪，并通过流广播
• Cron 触发器用于处理计划维护任务（例如，清理过期订单）
• 队列行为（重试、退避、并发、FIFO）在 iii-config.yaml 中按队列定义

架构

HTTP (create order)
  → Enqueue(order-validate) → validate
    → Enqueue(order-payment) → charge-payment
      → Enqueue(order-ship) → ship
        → publish(order.fulfilled)

Cron (hourly) → cleanup-stale

Queue configs (iii-config.yaml):
  order-validate:  max_retries: 2
  order-payment:   max_retries: 5, type: fifo, concurrency: 2
  order-ship:      max_retries: 3

使用的 iii 原语

原语	用途
registerWorker	初始化工作器并连接到 iii
registerFunction	定义每个流水线步骤
trigger({ ..., action: TriggerAction.Enqueue({ queue }) })	通过命名队列实现持久化步骤串联
trigger({ function_id: 'state::...', payload })	跟踪步骤进度
trigger({ ..., action: TriggerAction.Void() })	触发即忘的流事件并发布
registerTrigger({ type: 'cron' })	计划维护
registerTrigger({ type: 'http' })	入口点

参考实现

完整可运行示例见 ../references/workflow-orchestration.js：一个订单履行流水线，包含 validate → charge → ship 步骤、重试配置、基于流的进度跟踪，以及每小时清理过期订单。

常见模式

相关代码通常会在适用时包含：

• registerWorker(url, { workerName }) — 工作器初始化
• trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) }) — 通过命名队列实现持久化步骤串联
• trigger({ function_id: 'state::update', payload: { scope, key, ops } }) — 跟踪步骤进度
• 命名队列，并附有注释说明 iii-config.yaml 中的重试／并发设置
• const logger = new Logger() — 对每个步骤进行结构化日志记录
• 每个步骤都作为独立的 registerFunction，各自只负责一项工作
• trigger({ function_id: 'publish', payload, action: TriggerAction.Void() }) — 广播完成事件

调整此模式

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

• 每个步骤应只处理一项工作，并在成功后将下一个函数加入队列
• 当步骤需要不同的重试／并发设置时，在 iii-config.yaml 中定义不同的命名队列
• 在需要时捕获入队回执（messageReceiptId），以便观测和关联 DLQ
• trackStep 辅助函数模式（状态更新 + 流事件）可用于任何流水线
• 失败的作业在重试耗尽后会移入 DLQ — 参见 dead-letter-queues HOWTO
• Builtin 和 RabbitMQ 适配器为命名队列提供 DLQ 支持（Redis 仅支持发布／订阅）
• Cron 表达式采用 7 位数字格式：0 0 * * * * *（每小时一次）

引擎配置

流水线步骤的命名队列在 iii-config.yaml 的 queue_configs 下声明，并为每个队列单独设置重试、并发和 FIFO 参数。完整的注释版配置参考见 ../references/iii-config.yaml。

模式边界

• 如果任务是“将 HTTP 端点建模为通过 HTTP 调用的 registerFunction 函数”（包括迭代 { path, id } 数组并注册），优先使用 iii-http-invoked-functions。
• 当持久化步骤编排、队列重试／退避和工作流进度跟踪是主要关注点时，使用 iii-workflow-orchestration。

适用场景

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

边界

• 切勿将此技能用作处理无关任务的通用后备方案。
• 如果有更具体的 iii 技能更适合，则不得使用此技能。
• 使用此技能中的示例前，务必核实环境和安全限制。