可视化工作流/错误处理、重试与补偿机制
5.12 错误处理、重试与补偿机制（Error Handling, Retry & Compensation）
在构建工作流时，错误处理是确保流程稳定运行的关键环节。Pop 工作流内置了多层级的错误捕获、自动重试与补偿机制，使开发者能够从容应对：
- 第三方接口波动
- AI 模型超时 / 限流
- 文件 I/O 问题
- 用户输入错误
- PSL 脚本异常
- 业务逻辑不满足条件导致的中断
本章将介绍 Pop 中所有与错误处理相关的功能与技巧。
🔍 一、工作流中的错误类型
工作流执行期间可能出现以下错误类型：
| 错误类型 | 说明 | 常见场景 |
|---|---|---|
| 配置错误（Config Error） | 节点配置缺失或字段不合法 | 未填写模型 / URL / 必填项 |
| 输入错误（Input Error） | 上游节点传入的数据格式错误 | 字段为空、类型不匹配 |
| 脚本错误（PSL Error） | PSL 执行时出现异常 | 未检查 null、访问无效属性 |
| 运行时错误（Runtime Error） | 执行中发生外部异常 | HTTP 超时、文件不存在 |
| 业务逻辑错误（Business Error） | 用户自定义的失败条件 | 状态码不正确、返回内容不满足 |
Pop 运行日志会明确展示每个错误的类型、堆栈与位置，便于快速定位问题。
🔁 二、节点级自动重试（Retry）
许多节点支持 自动重试策略，用于应对偶发性问题（网络波动、AI 超时等）。
你可以在节点右侧属性中配置：
| 配置项 | 说明 |
|---|---|
| 重试次数（retryCount） | 默认 0，可设置 1–5 次 |
| 重试间隔（retryInterval） | 重试之间等待的毫秒数 |
| 重试条件（可选） | 仅对特定错误触发，例如 HTTP 500 |
适合用于：
- AI 调用超时
- HTTP 请求偶尔失败
- 文件读取延迟
- 网络波动导致的 I/O 错误
示例：
retryCount: 3
retryInterval: 1000
🛑 三、错误捕获（Try-Catch Node）
为了更细粒度的控制异常处理，你可以使用 Try / Catch 节点。
Try-Catch 的结构：
[Try Node]
↓ 错误时自动进入
[Catch Node]
用途：
- 捕获某节点或子流程的全部异常
- 在 Catch 中进行补偿
- 在 Catch 中发送告警（短信、邮箱、飞书、Webhook）
- 让流程不中断继续执行后续步骤
示例 Catch 输出数据结构：
{
"error": {
"message": "HTTP request failed",
"stack": "...",
"node": "http-request-2"
}
}
🔄 四、补偿节点（Compensation）
补偿机制用于：
在失败时执行一段逻辑，用于撤销、回滚或提示用户。
常见业务场景：
- 写数据库失败 → 回滚之前写入的缓存
- 调用第三方 API 失败 → 执行通知
- 文件移动失败 → 恢复原始文件位置
- 生成文档失败 → 删除中间文件
补偿节点通常由以下节点实现：
- 脚本节点（执行撤销逻辑）
- HTTP/Webhook（通知开发者）
- 文件节点（恢复文件状态）
- 自定义的撤销逻辑模块（Module）
示例补偿脚本：
globals.set("rollback", true);
return { status: "rolled_back" };
🧩 五、Fail-Safe 安全节点
某些场景你希望：
- 即使失败也不要中断流程
- 失败时使用默认值继续执行
可以使用：
Safe Node（安全执行）
它提供两个输出端：
成功 → success
失败 → fallback
适用于：
- AI 超时，使用“默认回答”
- HTTP 请求失败，使用“缓存内容”
- 文件读取失败，继续执行空值逻辑
示例：
fallbackValue: { "useCache": true }
🧪 六、PSL 中的错误处理
PSL 提供 try/catch 风格的写法：
try {
const data = nodes.sn(5).output.items;
return { ok: true, items: data };
} catch (e) {
return { ok: false, error: e.message };
}
你可以用此方式让脚本节点始终返回“安全的结构”，避免中断整个工作流。
🧭 七、错误定位与调试技巧
✔ 1. 查看红色节点日志
错误节点边框会变红。
展开运行日志即可查看堆栈。
✔ 2. 使用右键「运行此节点」
逐节点排查最有效方式。
✔ 3. 使用“字典节点”打印调试值
例如：
{
"debug_input": {{input.first}},
"node_output": {{nodes.sn(8).output}}
}
✔ 4. 使用分支节点提前阻断异常
例如：
- 当字段为空 → 走 error 分支
- 状态码不正确 → 走 fallback 分支
🧱 八、健壮性设计最佳实践
| 建议 | 说明 |
|---|---|
| 设置必要的默认值 | 避免 null 引起脚本报错 |
| 对所有外部接口设置重试 | AI / HTTP / 文件网络操作 |
| 使用 Try-Catch 节点隔离风险 | 局部失败不影响全局流程 |
| 对大任务拆分模块 | 便于调试、复用、隔离错误 |
| 使用 modules 实现幂等逻辑 | 防止重复运行引起问题 |
| 记录错误到日志中心 | 用于后续排查 |
🎯 九、小结
Pop 的错误处理体系覆盖：
- 自动重试
- Try/Catch 流程化捕获
- 补偿逻辑
- PSL 脚本异常控制
- Fail-Safe 安全执行
- 柔性分支与默认值
- 完整可追踪的执行日志
掌握这些能力，将帮助你构建更可靠、更稳定、更可维护的自动化流程系统。