DBOS Go工作流错误处理指南:12个哨兵错误如何优雅处理取消、超时与非确定性

原创2026-10-25 23:14:351,859 阅读

DBOS Go工作流错误处理指南:12个哨兵错误如何优雅处理取消、超时与非确定性

在 Go 中使用 DBOS(dbos-transact-golang)编写持久化工作流时,错误处理是可靠性的关键一环。本文带你快速掌握 DBOS Go 工作流的 12 个常用哨兵错误(sentinel errors),学会用 errors.Is 匹配错误,优雅处理取消、超时、非确定性三大典型故障场景。

为什么需要哨兵错误?

DBOS 把所有错误统一封装为 *dbos.Error 类型,每个错误都带有一个 ErrorCode 错误码。它的匹配逻辑很简单:只比较错误码(见 dbos/internal/models/errors.go 中的 Is 方法),因此一个哨兵错误可以匹配任何携带相同错误码的 DBOS 错误,即使具体的 WorkflowID、StepName 等上下文字段各不相同。

这意味着你不需要解析错误信息文本,也不需要构造 &dbos.Error{Code: ...} 探针,一行标准库代码就能判断错误类型:

if errors.Is(err, dbos.ErrWorkflowCancelled) {
    // 优雅处理:清理资源、给用户友好提示
}

所有公开的哨兵错误定义在 dbos/errors.go,错误码常量别名见 dbos/aliases.go。

12 个常用哨兵错误速查表 📋

# 哨兵错误 错误码 触发场景 常见应对
1 ErrWorkflowCancelled WorkflowCancelled 工作流执行中被取消 清理状态,向用户说明已取消
2 ErrAwaitedWorkflowCancelled AwaitedWorkflowCancelled 等待(await)一个已被取消的工作流 走备用流程或提示用户
3 ErrTimeout Timeout 等待事件/结果超时 重试或降级
4 ErrNonExistentWorkflow NonExistentWorkflow 查询不存在的工作流 ID 返回 404 或引导用户
5 ErrUnexpectedWorkflow UnexpectedWorkflow 工作流 ID 被复用于不同函数/队列(非确定性) 检查代码是否确定性
6 ErrStepNondeterminism StepNondeterminism 同一执行中同一 Step 记录了不同结果 移除步骤中的随机/时间逻辑
7 ErrConflictingWorkflowID ConflictingID 工作流所有权发生冲突 交给其他执行方继续
8 ErrWorkflowIDInUse WorkflowIDInUse 复用策略为 Reject 时 ID 已存在 换 ID 或调整复用策略
9 ErrMaxStepRetriesExceeded MaxStepRetriesExceeded Step 重试次数耗尽 告警 + 人工介入
10 ErrDeadLetterQueue DeadLetterQueue 工作流恢复次数超限,移入死信队列 监控死信,定期回放
11 ErrQueueDeduplicated QueueDeduplicated 入队时因去重 ID 被去重 视为"已提交"而非失败
12 ErrQueueNotFound QueueNotFound 引用了不存在的队列 检查队列注册配置

💡 此外还有 ErrScheduleNotFound、ErrNoApplicationVersions、ErrInvalidOption、ErrWorkflowPanic 等哨兵错误,完整列表同样在 dbos/errors.go 中。

优雅处理取消错误

主动取消工作流

DBOS 提供了 CancelWorkflow 接口来取消运行中或已入队的工作流:它把状态置为 CANCELLED 并从队列移除,工作流会在下一个 Step 开始时停止,正在执行的 Step 不会被强杀(见 dbos/workflow.go)。

err := dbos.CancelWorkflow(ctx, "workflow-to-cancel")

取消后,正在等待结果的一方会拿到两类不同的错误:

  • 工作流自身:后续执行返回 ErrWorkflowCancelled;
  • 等待它的调用方:通过 GetResult 等到的错误是 ErrAwaitedWorkflowCancelled。

⚠️ 一个容易忽略的细节:取消原因会随错误持久化。如果工作流是因为带 context.Canceled 的原因被取消的,DBOS 会把该原因记录在错误中(CauseKind 机制,见 dbos/internal/models/errors.go),即使错误从数据库读回来,errors.Is(err, context.Canceled) 依然成立。所以你可以统一用标准库哨兵区分"用户主动取消"和"超时"。

取消 ≠ 失败

在业务代码中,建议把取消类错误单独分支,不要和真正的业务失败混在一起统计:

switch {
case errors.Is(err, dbos.ErrWorkflowCancelled),
     errors.Is(err, dbos.ErrAwaitedWorkflowCancelled):
    // 正常业务分支:无需告警
case errors.Is(err, dbos.ErrTimeout):
    // 可重试分支
default:
    // 真正需要告警的错误
}

优雅处理超时错误

DBOS 的超时错误(ErrTimeout)覆盖多种场景:Recv/GetEvent 等待事件超时、GetResult 句柄超时(通过 WithHandleTimeout 设置,见 dbos/workflow.go)、以及入队工作流的持久超时(通过 WithEnqueueTimeout 设置,见 dbos/workflow.go)。

处理超时有两个关键要点:

  1. 超时是持久化的。WithEnqueueTimeout 设置的 deadline 会写入系统数据库,跨进程重启依然生效——工作流即使被另一台机器恢复执行,超时照样会到期。
  2. 超时错误同时匹配标准库哨兵。每个 ErrTimeout 都包了一个标准库 cause,因此 errors.Is(err, context.DeadlineExceeded) 和 errors.Is(err, context.Canceled) 也能命中(含从数据库读回的错误)。测试用例 dbos/errors_test.go 完整验证了这个行为。

实用建议:先用标准库哨兵写通用超时逻辑,再用 ErrTimeout 区分"DBOS 操作超时"和普通 context 超时,前者可以针对性地重试入队操作,后者则应向上传播。

诊断非确定性错误

非确定性是持久化工作流最隐蔽的陷阱。当工作流恢复执行时的行为与首次执行不一致,DBOS 会返回两类错误:

  • ErrUnexpectedWorkflow:同一个 Workflow ID 之前被另一个工作流函数或另一个队列使用过。错误信息会直接提示 "Check that your workflow is deterministic";
  • ErrStepNondeterminism:同一次执行中,某个 Step 序号被记录了不同的结果,通常意味着 Step 划分或调用顺序不稳定。

最常见的根因

根因 症状 修复方法
工作流函数中直接调用 time.Now()、随机数、HTTP 请求 恢复时 Step 记录对不上 把非确定性操作放进 RunAsStep
循环次数依赖运行时数据 Step 序号错位 循环上界改用输入或 Step 结果
复用 Workflow ID 但换了函数 ErrUnexpectedWorkflow ID 派生规则保持稳定

💡 核心原则:工作流函数本身只做确定性的流程编排,所有非确定性操作(API 调用、随机数、当前时间)都必须包在 Step 里。DBOS 会自动把 Step 结果记录到数据库,恢复时直接回放,从而规避非确定性。更多工作流管理操作(取消、恢复、Fork)的说明见 dbos/doc.go。

重试与死信队列:让错误有出口

对于瞬时失败,DBOS 提供两层重试机制(定义见 dbos/workflow.go):

  • Step 级重试:WithStepMaxRetries(3),带指数退避,重试耗尽后返回 ErrMaxStepRetriesExceeded,适合网络抖动等瞬时故障;
  • 工作流恢复级重试:WithMaxRecoveryAttempts(n),限制中断工作流被恢复的次数,超限后工作流进入死信队列(状态 MAX_RECOVERY_ATTEMPTS_EXCEEDED),对应错误 ErrDeadLetterQueue。死信判定逻辑见 dbos/queue.go。

⚠️ 注意区分:WithStepMaxRetries 是"Step 内部重试",WithMaxRecoveryAttempts 是"崩溃后恢复次数",两者互不影响,生产环境建议都设置。

监控侧的做法很简单:定期 ListWorkflows 过滤 WorkflowStatusError 状态,对 ErrDeadLetterQueue 的工作流人工排查后可用 ResumeWorkflow 重放。

错误处理最佳实践清单 ✅

  1. 永远用 errors.Is + 哨兵错误判断类型,不要用字符串匹配错误信息;
  2. 需要上下文字段(WorkflowID、StepName、MaxRetries)时用 errors.As 取出 *dbos.Error;
  3. 取消类错误视为正常业务分支,超时类错误可重试,其余错误才告警;
  4. 超时判断优先 errors.Is(err, context.DeadlineExceeded),它是跨 DB 持久化后依然可靠的;
  5. 出现 ErrUnexpectedWorkflow / ErrStepNondeterminism 时立即检查确定性,这是代码缺陷而非运行故障;
  6. 为 Step 和恢复次数都配置上限,并建立死信队列的告警与回放流程。

延伸阅读

登录后查看全文
dbos-transact-golang