SuperAPI AI 工具集

inngest-steps

智能体与模型

查看项目

更新于 10-16 07:05

技能介绍

Inngest Steps 是 Inngest 的步骤方法(step methods)集合,用于构建健壮、持久的 TypeScript 工作流。每个 step 是独立的 HTTP 请求,可以被单独重试和监控。该技能聚焦 TypeScript;Python 或 Go 请参考 Inngest 官方文档的语言专属指南,核心概念跨语言通用。

核心概念 每次 step 执行都会从头重新运行整个函数。因此必须把全部非确定性代码(API 调用、数据库查询、随机逻辑)放进 step 内部,绝不能放在 step 外部。函数最多支持 1,000 个 step,单个 step 数据上限 4MB。资料给出的错误示例中,写在 step 外的 console.log 会随每次 step 重复执行 4 次;正确做法是把它也包进 step.run。

主要能力与使用方式 step.run():将一个可重试的代码块作为 step 执行,同一个 step ID 可以重复使用,Inngest 自动处理计数器。文档建议返回对后续步骤有用的数据,副作用可不返回。不宜把确定性逻辑无必要地放进 step,也不要忘记每个 step 是一次独立 HTTP 请求。

step.sleep():暂停执行且不消耗计算时间,支持时长字符串(如 "24h"、"30s"、"7d")。step.sleepUntil():暂停到指定日期时间,可从事件数据中构造时间。

step.waitForEvent():等待事件,但只能捕获该 step 执行之后发送的事件;执行之前发送的事件不会被捕获。必须设置合理超时,并处理返回 null(表示超时、事件从未到达)的情况。支持简单匹配(match,如 data.invoiceId)和基于 CEL 语法的表达式匹配(if,其中 event 为原始触发事件,async 为正在匹配的新事件)。建议使用唯一 ID(userId、sessionId、requestId)进行匹配,生产环境中始终设置超时,并可与 Realtime 配合实现人机协同流程。

step.waitForSignal():等待唯一信号而非事件,更适合 1:1 匹配。需指定 signal、timeout 和 onConflict("replace" 覆盖待处理信号,"fail" 抛出错误)。选择上,waitForEvent 适合多个函数可能处理同一事件的场景,waitForSignal 适合精确 1:1 指向特定函数运行的场景。

step.sendEvent():向其他函数扇出事件而不等待结果,可一次发送单个或多个事件,适用于触发其他函数但当前函数不需要其结果的场景。

step.invoke():调用其他函数并处理其结果,适合函数组合。可直接传入导入的函数引用并获取强类型结果;跨应用调用时可使用 referenceFunction({ appId, functionId })。注意 v4 破坏性变更:step.invoke() 不再支持字符串函数 ID(如 function: "my-app-other-fn"),需改用导入的函数引用或 referenceFunction()。适用于把复杂工作流拆成可组合函数、复用逻辑、Map-Reduce 模式。

常用模式 循环中使用 step:复用同一 step ID(如 "fetch-page"),Inngest 自动处理计数器,可配合游标分页循环拉取数据。

并行执行:创建 step 时不立即 await,再用 Promise.all 并行运行。v4 默认优化并行步骤执行。需要注意 Promise.race() 在 v4 优化并行下的行为:所有 promise 都会 settle 后 race 才 resolve,若需真正的 race 语义应使用 group.parallel()。可在客户端(new Inngest({ id: "app", optimizeParallelism: false }))或函数级(optimizeParallelism: false)关闭优化并行。

分块作业:用 chunkArray 把大数据集切块,对每个分块用 step.run 并行处理,最后合并结果,适合批量处理。

关键注意事项 函数会重新执行:step 外的代码在每次 step 执行时都会运行。 事件时序:waitForEvent 只捕获该 step 运行之后发送的事件。 Step 限制:每个函数最多 1,000 个 step,单个 step 输出 4MB,单次函数运行总计 32MB。 HTTP 请求:v4 默认启用 checkpointing 以减少 HTTP 开销;在 serverless 平台需在客户端配置 maxRuntime。 Step ID:可在循环中复用,Inngest 处理计数器。 并行:用 Promise.all 并行;Promise.race() 会等待全部 settle,真正 race 用 group.parallel()。

常见用例 人机协同(waitForEvent 配合 Realtime UI)、多步引导(步骤间 sleep,等待用户行为事件)、数据处理(并行分块)、外部集成(step.run 实现可靠 API 调用)、AI 工作流(step.ai 进行持久 LLM 编排)、函数组合(step.invoke 构建复杂工作流)。资料强调,step 让函数具备持久性、可观测性和可调试性。

限制与暂未提供内容 资料未提供具体收费、价格、平台支持细节或安装命令;waitForSignal 发送信号的 API 细节仅提到通过 Inngest API 或 SDK 的 POST /v1/events,未给出完整示例。表达式的完整语法、操作符与模式需参考 Expression Syntax Reference,资料未展开。