用途:为 Inngest 持久化函数添加横切关注点,如结构化日志、追踪、Sentry 错误跟踪、依赖注入、数据加解密与校验、认证等。中间件可注册在客户端级(影响所有函数)或函数级(影响特定函数),执行顺序为先客户端后函数,按声明顺序运行。
主要能力:通过 InngestMiddleware 的 init() 返回生命周期钩子,包括 onFunctionRun(beforeExecution、afterExecution、transformOutput)和 onSendEvent(transformInput),可在函数执行与事件发送的关键节点插入逻辑。官方提供 dependencyInjectionMiddleware(内置)、@inngest/middleware-encryption(自动加密步骤数据、函数输出与事件 data.encrypted,支持 fallbackDecryptionKeys 轮换密钥)、@inngest/middleware-sentry(捕获异常、为每次运行添加追踪,需 @sentry/* >=8.0.0)。
使用方式:安装对应包后,在 new Inngest({ id, middleware: [...] }) 中注册;加密中间件用 npm install @inngest/middleware-encryption,Sentry 用 npm install @inngest/middleware-sentry。依赖注入示例中,函数上下文可直接解构注入的 openai、db 等实例。
适用场景:可观测性、指标与性能统计、错误处理与告警、认证与权限校验、外部服务熔断、功能开关、用户上下文增强等。
限制:资料聚焦 TypeScript,Python 或 Go 需参考 Inngest 官方文档;中间件系统在 v4 大幅重写,钩子反映 v4 API,从 v3 迁移需查阅迁移指南。Realtime 应使用 inngest-realtime 技能,v4 原生支持 step.realtime.publish,不要在 v4 项目安装 @inngest/realtime,否则运行时报 TypeError: Cls is not a constructor。中间件应保持单一职责、优雅处理错误、关注性能并充分测试。测试可用 createMockContext、createMockFunction。具体实现细节与高级模式见依赖注入与内置中间件参考文档。