Melhores Práticas do DBOS Go

Guia para construir aplicações Go confiáveis e tolerantes a falhas com fluxos de trabalho duráveis do DBOS.

Quando Usar

Consulte estas diretrizes quando:

• Adicionar DBOS a código Go existente
• Criar fluxos de trabalho e etapas
• Usar filas para controle de concorrência
• Implementar comunicação de fluxo de trabalho (eventos, mensagens, streams)
• Configurar e iniciar aplicações DBOS
• Usar o Cliente DBOS de aplicações externas
• Testar aplicações DBOS

Categorias de Regras por Prioridade

Regras Críticas

Instalação

Instale o módulo DBOS Go:

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

Configuração e Lançamento do DBOS

Uma aplicação DBOS DEVE criar um contexto, registrar fluxos de trabalho e iniciar antes de executar quaisquer fluxos de trabalho:

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)
	}
}

Estrutura de Fluxo de Trabalho e Etapa

Fluxos de trabalho são compostos por etapas. Qualquer função que execute operações complexas ou acesse serviços externos deve ser executada como uma etapa usando 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
}

Restrições Chave

• NÃO inicie ou enfileire fluxos de trabalho de dentro de etapas
• NÃO use goroutines não controladas para iniciar fluxos de trabalho - use dbos.RunWorkflow com filas ou dbos.Go/dbos.Select para etapas concorrentes
• Fluxos de trabalho DEVEM ser determinísticos - operações não determinísticas vão para as etapas
• NÃO modifique variáveis globais de fluxos de trabalho ou etapas
• Todos os fluxos de trabalho e filas DEVEM ser registrados antes de chamar Launch()

Como Usar

Leia os arquivos de regras individuais para explicações detalhadas e exemplos:

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

Referências

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

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão especializada.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.