企业官网建设流程全解析

Mastra工作流重试完整指南：3步配置错误处理与自动重试

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

工作流第3步失败，就要从头重跑？一次API瞬时超时就能让长流程中断。Mastra 工作流重试与错误处理机制，让失败的步骤自动重试，而不是整个流程推倒重来。本文讲清它的原理、配置方法和观察手段。

为什么需要工作流重试：三个常见失败场景

• 外部API瞬时超时：调用模型或支付接口，偶尔返回 5xx 或连接重置。过几秒再试通常就能成功。
• 上游数据未就绪：前置服务还在写入，当前步骤读到空数据直接报错，立即失败其实不划算。
• 资源竞争：数据库连接池打满、触发限流。同样的请求稍作延迟即可通过。

这三类错误的共同点是“瞬时性”，重试几次就能自愈，不该让一次抖动打断整个流程。

重试原理：如何区分可重试错误

Mastra 的运行结果对象有四种状态：success、failed、suspended、tripwire。只有failed与重试相关——步骤抛出错误后，执行器先检查重试次数，没耗尽就等待一段时间后重跑该步骤。

重试本质上是一个“受限循环”，配置分两级：

需要注意：内置间隔是固定值，不提供开箱即用的指数退避策略。想要延迟递增，可以配合do-while这类循环控制结构自己实现。对本来就不该重试的错误（校验失败、权限不足），建议在步骤内捕获后用branch()走降级分支。

三步配置 Mastra 工作流重试

第一步：给整个工作流设默认重试策略。

export const testWorkflow = createWorkflow({ id: 'data-pipeline', retryConfig: { attempts: 3, delay: 2000 }, }) .then(step1) .commit();

第二步：对调用不稳定外部服务的步骤，用retries单独提高次数（会覆盖工作流级attempts）：

const fetchStep = createStep({ id: 'fetch-data', retries: 5, execute: async () => { const res = await fetch('https://api.example.com/data'); if (!res.ok) throw new Error(`HTTP ${res.status}`); return { data: await res.json() }; }, });

第三步：挂上回调做集中告警。onFinish在任意结束状态都会触发，onError仅在失败时触发。回调里可以发通知、写监控平台；回调内抛出的异常只会被记录，不会影响工作流结果。

如何观察重试与排障路径

• 运行后检查结果对象：看result.status判断成败，遍历result.steps就能定位哪个步骤是failed，并取出该步骤的error。
• 实时观察：run.stream()可消费执行流，逐步看到每个步骤的输出与统计，适合长时间运行的工作流。
• 排障路径：出问题时先看onError里的状态与错误信息，判断是瞬时错误（值得重试）还是逻辑错误（应修代码）。字段细节参考错误处理官方文档，执行细节见工作流源码。

工作流错误处理配置的常见坑

1. 默认以为会重试：attempts默认是 0，不配置就一次失败直接结束。
2. 以为内置指数退避：delay是固定间隔，想要退避需自己实现，别按错误处理配置文档的想象来写。
3. 对不可重试错误盲目重试：校验失败、4xx 权限错误重试再多次也不会好，应先捕获或用branch()走降级。
4. 告警里没定位失败步骤：onError给的是工作流级错误，想知道具体步骤要看steps字段。
5. 把回调异常当告警通道：onError里抛出的异常只会被记录，若你的告警服务本身不可用，通知就静默丢失了。

重试机制要记住的只有一点：让瞬时错误自愈，让持续性错误清晰暴露在哪一步、为什么失败。配置时把 attempts 控制在 2~5 次、delay 别设得太小，再给不可重试的错误留一条降级出路，工作流的可恢复性就有了基本保障。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra