dbos-golang

DBOS Go 最佳实践

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

适用场景

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

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

按优先级划分的规则类别

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

关键规则

安装

安装 DBOS Go 模块（v1）：

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

连接到 DBOS Conductor（设置 ConductorAPIKey 或在 DBOS Cloud 中运行）需要导入 go.dbos.dev/dbos-enterprise-go（go get go.dbos.dev/dbos-enterprise-go），并在程序中的任意位置进行空白导入；否则，dbos.NewContext 会因初始化错误而失败：

import _ "go.dbos.dev/dbos-enterprise-go"

DBOS 配置与启动

DBOS 应用程序必须创建上下文、注册工作流，并在运行任何工作流前启动：

package main

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

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

func main() {
	ctx, err := dbos.NewContext(context.Background(), dbos.Config{
		AppName:            "my-app",
		ApplicationVersion: "0.1.0",
		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)
	}
}

创建新应用程序时，将 ApplicationVersion 设置为 "0.1.0"。如果省略，DBOS 会根据二进制文件生成一个不透明哈希。编辑现有应用程序时，保留其已配置的版本不变——更改版本属于部署决策（参见 references/advanced-application-versions.md）。

DatabaseURL 接受 Postgres/CockroachDB URL 或 SQLite URL（sqlite:/path/to.db、sqlite::memory:；SQLite 需要空白导入 github.com/dbos-inc/dbos-transact-golang/dbos/driver/sqlite）。有关所有配置选项（包括 Conductor 设置以及如何单独于应用程序运行架构迁移），请参见 references/lifecycle-config.md。

dbos.Context 扩展了 dbos.Client：管理函数（Enqueue、ListWorkflows、CancelWorkflow、队列和计划管理等）接受 dbos.Client，并可使用 Context 或通过 dbos.NewClient 创建的独立客户端（参见 references/client-setup.md）。

AppName 用于标识应用程序，并拥有它创建的一切。多个应用程序（可使用任何语言）可以共享一个系统数据库，并通过应用程序名称隔离（v1.2.0+，参见 references/advanced-shared-database.md）。

工作流和步骤结构

工作流由步骤组成。任何执行复杂操作或访问外部服务的函数，都必须通过 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.Context, input string) (string, error) {
	result, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
	if err != nil {
		return "", err
	}
	return result, nil
}

必须恰好执行一次的数据库写入应放在数据源事务（dbos.RunAsTransaction）中，而不是步骤中（参见 references/step-transactions.md）。

关键约束

• 不要在步骤中启动或排队工作流
• 不要在步骤中调用 dbos.RunAsTransaction、handle.GetResult 或 dbos.CloseStream（允许读取、调用 dbos.SetEvent 和 dbos.WriteStream）
• 不要使用不受控的 goroutine 启动工作流——应使用带队列的 dbos.RunWorkflow，或使用 dbos.Go/dbos.Select 执行并发步骤
• 工作流必须具有确定性——非确定性操作应放在步骤中
• 不要在工作流或步骤中修改全局变量
• 调用 Launch() 之前，必须注册所有工作流，并使用 dbos.NewDataSource 创建所有数据源；队列通过 dbos.RegisterQueue 注册并持久化到数据库中
• 使用已被占用的 ID 启动工作流时，默认返回现有工作流；传入 dbos.WithWorkflowIDReusePolicy(dbos.WorkflowIDReusePolicyReject)，则会返回 dbos.ErrWorkflowIDInUse（参见 references/pattern-idempotency.md）
• 工作流中发生 panic 不会导致进程崩溃：DBOS 会将其记录为工作流错误（dbos.ErrWorkflowPanic）

使用方法

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

references/lifecycle-config.md
references/workflow-determinism.md
references/step-transactions.md
references/queue-concurrency.md
references/workflow-control.md

参考资料

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