dbos-golang

DBOS Go 最佳实践

使用 DBOS 持久化工作流构建可靠、容错的 Go 应用指南。

适用场景

在以下情况下参考这些指南：

• 将 DBOS 添加到现有 Go 代码中
• 创建工作流和步骤
• 使用队列进行并发控制
• 实现工作流通信（事件、消息、流）
• 配置和启动 DBOS 应用
• 在外部应用中使用 DBOS 客户端
• 测试 DBOS 应用

可靠性与版本边界

在采用这些示例片段之前，请固定并验证 DBOS Go SDK 版本；当前 SDK 文档使用 dbos.Context，而此快照使用 dbos.DBOSContext。辅助函数、导入、注册和特定于应用的函数均已省略。不要声称这些代码片段可以作为完整应用编译。使用句柄或结果前，请检查每个返回的错误。工作流 ID 和检查点步骤并不能确保外部支付/API 副作用恰好执行一次：如果在远程操作完成后、写入检查点前发生崩溃，该操作可能会重放。请使用服务提供商的幂等键并进行对账。在调用 Send 前验证并去重 webhook 消息；将工作流访问权限限制在调用方范围内。队列限制约束的是工作流启动次数，而不是工作流内部的每次请求/重试。取消操作无法撤销已提交的副作用。工作流输入、输出和错误负载中不得包含机密信息或不必要的个人数据。未经授权，不得启用管理端点、计划任务、付费调用或管理类变更。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	生命周期	严重	lifecycle-
2	工作流	严重	workflow-
3	步骤	高	step-
4	队列	高	queue-
5	通信	中	comm-
6	模式	中	pattern-
7	测试	低至中	test-
8	客户端	中	client-
9	高级	低	advanced-

关键规则

安装

安装 DBOS Go 模块：

go get github.com/dbos-inc/dbos-transact-golang/dbos@latest

DBOS 配置与启动

DBOS 应用必须创建上下文、注册工作流并启动，然后才能运行任何工作流：

package main

import (
	"context"
	"log"
	"os"
	"time"

	"github.com/dbos-inc/dbos-transact-golang/dbos"
)

func main() {
	ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
		AppName:     "my-app",
		DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
	})
	if err != nil {
		log.Fatal(err)
	}
	defer dbos.Shutdown(ctx, 30*time.Second)

	dbos.RegisterWorkflow(ctx, myWorkflow)

	if err := dbos.Launch(ctx); err != nil {
		log.Fatal(err)
	}
}

工作流与步骤结构

工作流由步骤组成。任何执行复杂操作或访问外部服务的函数都必须使用 dbos.RunAsStep 作为步骤运行：

func fetchData(ctx context.Context) (string, error) {
	resp, err := http.Get("https://api.example.com/data")
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	return string(body), nil
}

func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
	result, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
	if err != nil {
		return "", err
	}
	return result, nil
}

关键约束

• 不得在步骤中启动或入队工作流
• 不得使用不受控的 goroutine 启动工作流；请使用带队列的 dbos.RunWorkflow，或使用 dbos.Go/dbos.Select 执行并发步骤
• 工作流必须具有确定性；非确定性操作应放在步骤中
• 不得在工作流或步骤中修改全局变量
• 调用 Launch() 前必须注册所有工作流和队列

使用方法

阅读各个规则文件，了解详细说明和示例：

references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md

参考资料

• https://docs.dbos.dev/
• https://github.com/dbos-inc/dbos-transact-golang

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不得将输出视为针对特定环境进行验证、测试或专家评审的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请暂停并请求澄清。