Mastra工作流智能重试配置教程：错误处理完整指南

Mastra工作流智能重试配置教程错误处理完整指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra跑 Mastra 工作流时取数步骤第 3 次执行超时整个流程直接中断。Mastra 工作流自带两项错误处理能力自动重试与错误追踪。前者让失败的步骤按重试策略重新执行后者帮你定位具体哪一步失败、为什么失败。本文按分类→配置→验证的顺序讲清楚这两件事。错误分类哪些失败会触发重试Mastra 的重试机制面向瞬时错误设计比如步骤调用外部服务时对方临时不可用。判断一个错误值不值得重试可以先按类型归类错误类型典型场景是否自动重试处理建议网络错误请求超时、连接中断、5xx 响应是配置retries或retryConfig交给框架重试业务逻辑错误数据校验失败、必填字段缺失重试通常无意义步骤内抛出MastraNonRetryableError标记不可重试系统资源错误内存不足、依赖服务过载视情况调大delay拉长重试间隔给系统恢复时间关键点只有一个瞬时错误让框架重试确定性错误用MastraNonRetryableError跳过重试。这样能避免对注定失败的调用白白消耗配额。 Mastra重试配置最小可用写法重试配置分两级工作流级和步骤级步骤级会覆盖工作流级。最小可用配置如下import { createWorkflow, createStep } from mastra/core/workflows import { z } from zod const fetchStep createStep({ id: fetch-data, outputSchema: z.object({ value: z.string() }), retries: 3, execute: async () { const res await fetch(https://api.example.com/data) if (!res.ok) throw new Error(请求失败) return { value: await res.text() } }, }) export const demoWorkflow createWorkflow({ retryConfig: { attempts: 5, delay: 2000 }, }) .then(fetchStep) .commit()三个参数各管一件事retries: 3步骤级最大重试次数仅作用于fetch-data这一步。attempts: 5工作流级重试次数作用于所有没单独声明retries的步骤。delay: 2000每次重试之间固定等待 2000 毫秒。注意最后必须调用.commit()否则工作流不会编译重试配置也不会生效。进阶重试策略条件分支与失败告警基础配置只解决要不要重试生产环境还要解决失败后走哪条路。Mastra 提供三类手段。条件分支用条件逻辑根据上一步成功或失败把执行导向不同分支。比如取数失败后转入降级路径返回缓存数据而不是让整个工作流挂掉。指数退避内置的delay是固定间隔。如果你需要指数退避可以在步骤内部根据retryCount自行计算等待时长或在外层循环里放大间隔再抛出错误交给框架重试。失败告警给工作流挂onError回调它只在工作流最终失败重试耗尽时触发options: { onError: async errorInfo { console.error(重试已耗尽, errorInfo.error?.message) await alertService.notify(工作流最终失败请人工介入) }, },这样重试期间的抖动不会打扰你真正重试失败后才会收到通知。 Mastra错误追踪验证重试效果配置完重试策略要验证它是否按预期工作最直接的方式是检查执行结果。工作流运行后先判断result.status。状态为failed时遍历result.steps找到status为failed的步骤读取它的error字段就能看到失败原因和错误堆栈。如果同一工作流被反复重试后仍失败错误信息会保留最后一次尝试的现场。此外给 Mastra 实例接上可观测性 provider 后每次重试都会体现在追踪记录里。你能看到每一步的执行耗时、重试次数和最终状态据此判断某类错误到底是瞬时抖动还是持续故障。完整用法可参考错误处理文档。常见坑现象、原因与解决现象重试完全不生效。原因步骤抛出的是MastraNonRetryableError或忘了.commit()。解决确认错误类型检查工作流定义末尾是否有.commit()调用。现象重试次数过多外部 API 被打挂。原因attempts设得太大、delay太小。解决次数控制在 3~5 次配合更长的固定延迟避免高频重试放大故障。现象工作流超时处理失控整体挂起很久。原因重试没有间隔上限单次请求也没有超时。解决在步骤的fetch里加超时控制让单次失败快速暴露给重试机制而不是无限等待。重试机制的价值不在消除错误而在让瞬时错误自动恢复、让致命错误快速暴露。建议每月复盘一次追踪记录里重试后失败的工作流清单。对反复出现的失败步骤把重试次数和延迟参数重新校准一遍重试策略的投入产出比会明显更高。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考