DBOS Go工作流错误处理指南:12个哨兵错误如何优雅处理取消、超时与非确定性
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)。
处理超时有两个关键要点:
- 超时是持久化的。
WithEnqueueTimeout设置的 deadline 会写入系统数据库,跨进程重启依然生效——工作流即使被另一台机器恢复执行,超时照样会到期。 - 超时错误同时匹配标准库哨兵。每个
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 重放。
错误处理最佳实践清单 ✅
- 永远用
errors.Is+ 哨兵错误判断类型,不要用字符串匹配错误信息; - 需要上下文字段(
WorkflowID、StepName、MaxRetries)时用errors.As取出*dbos.Error; - 取消类错误视为正常业务分支,超时类错误可重试,其余错误才告警;
- 超时判断优先
errors.Is(err, context.DeadlineExceeded),它是跨 DB 持久化后依然可靠的; - 出现
ErrUnexpectedWorkflow/ErrStepNondeterminism时立即检查确定性,这是代码缺陷而非运行故障; - 为 Step 和恢复次数都配置上限,并建立死信队列的告警与回放流程。
延伸阅读
- 哨兵错误定义:dbos/errors.go
- 统一错误类型与错误码:dbos/internal/models/errors.go
- v0 → v1 错误 API 迁移对照:docs/go-v1-migration-guide.md
- 工作流与 Step 使用示例:dbos/doc.go
- 错误往返持久化测试:dbos/errors_test.go