Back to Details

dbos-golang

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DBOS Go Best Practices

DBOS Go 最佳实践

Guide for building reliable, fault-tolerant Go applications with DBOS durable workflows.
本指南介绍如何使用 DBOS 持久化工作流构建可靠、容错的 Go 应用。

When to Use

使用场景

Reference these guidelines when:
  • Adding DBOS to existing Go code
  • Creating workflows and steps
  • Using queues for concurrency control
  • Implementing workflow communication (events, messages, streams)
  • Configuring and launching DBOS applications
  • Using the DBOS Client from external applications
  • Testing DBOS applications
在以下场景中可参考本指南：
  • 为现有 Go 代码添加 DBOS 集成
  • 创建工作流与步骤
  • 使用队列进行并发控制
  • 实现工作流通信（事件、消息、流）
  • 配置与启动 DBOS 应用
  • 从外部应用使用 DBOS 客户端
  • 测试 DBOS 应用

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1LifecycleCRITICAL
lifecycle-
2WorkflowCRITICAL
workflow-
3StepHIGH
step-
4QueueHIGH
queue-
5CommunicationMEDIUM
comm-
6PatternMEDIUM
pattern-
7TestingLOW-MEDIUM
test-
8ClientMEDIUM
client-
9AdvancedLOW
advanced-
优先级类别影响程度前缀
1生命周期关键
lifecycle-
2工作流关键
workflow-
3步骤高
step-
4队列高
queue-
5通信中
comm-
6模式中
pattern-
7测试低-中
test-
8客户端中
client-
9高级低
advanced-

Critical Rules

关键规则

Installation

安装

Install the DBOS Go module:
bash
go get github.com/dbos-inc/dbos-transact-golang/dbos@latest
安装 DBOS Go 模块：
bash
go get github.com/dbos-inc/dbos-transact-golang/dbos@latest

DBOS Configuration and Launch

DBOS 配置与启动

A DBOS application MUST create a context, register workflows, and launch before running any workflows:
go
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 应用必须先创建上下文、注册工作流，然后启动，之后才能运行任何工作流：
go
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)
	}
}

Workflow and Step Structure

工作流与步骤结构

Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using 
dbos.RunAsStep
:
go
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
}
工作流由步骤组成。任何执行复杂操作或访问外部服务的函数都必须通过 
dbos.RunAsStep
以步骤形式运行：
go
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
}

Key Constraints

关键约束

  • Do NOT start or enqueue workflows from within steps
  • Do NOT use uncontrolled goroutines to start workflows - use 
    dbos.RunWorkflow
    with queues or 
    dbos.Go
    /
    dbos.Select
    for concurrent steps
  • Workflows MUST be deterministic - non-deterministic operations go in steps
  • Do NOT modify global variables from workflows or steps
  • All workflows and queues MUST be registered before calling 
    Launch()
  • 请勿在步骤内部启动或入队工作流
  • 请勿使用不受控的 goroutine 启动工作流 - 应使用带队列的 
    dbos.RunWorkflow
    或 
    dbos.Go
    /
    dbos.Select
    处理并发步骤
  • 工作流必须是确定性的 - 非确定性操作应放在步骤中
  • 请勿从工作流或步骤中修改全局变量
  • 所有工作流与队列必须在调用 
    Launch()
    之前完成注册

How to Use

使用方法

Read individual rule files for detailed explanations and examples:
references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md
阅读单个规则文件获取详细说明与示例：
references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md

References

参考资料