Implementando Aplicações de Workflow com Temporal em Go: Um Guia Completo

Construa fluxos de trabalho em Go com o SDK do Temporal

Conteúdo da página

Temporal é um motor de workflow de código aberto, empresarial, que permite que desenvolvedores construam aplicações de workflow duráveis, escaláveis e tolerantes a falhas usando linguagens de programação familiares, como Go.

E aplicações distribuídas com transições de estado complexas e retenções exigem um framework de orquestração confiável.

Este guia explica como implementar aplicações de workflow com Temporal em Go, abrangendo configuração, código de exemplo, estratégias de implantação, melhores práticas e solução de problemas.

Go Workplace

O que é o Temporal e por que usá-lo com Go

Temporal é um framework de orquestração de workflow projetado para construir aplicações distribuídas de longa duração e tolerantes a falhas. O Temporal gerencia estado, retenções, temporizadores e recuperação de falhas em segundo plano, permitindo que os desenvolvedores se concentrem na lógica da aplicação sem precisar de código de orquestração redundante. Ele suporta Go, entre outras linguagens, por meio do Temporal Go SDK.

Ao usar o Temporal com Go:

  • Os workflows são duráveis e reexecutáveis.
  • As retenções e tempos limite de atividades são gerenciados automaticamente.
  • O estado do sistema persiste mesmo em falhas.
  • A lógica de orquestração de tarefas vive em código Go idiomático.

Conceitos Principais: Workflows, Atividades, Workers

Antes de construir sua primeira aplicação Temporal em Go, compreenda esses conceitos-chave:

Workflows

Um Workflow é a lógica de coordenação durável que invoca atividades. Ele deve ser determinístico — o motor Temporal pode reexecutá-lo de forma confiável. Em Go, workflows são funções Go regulares com um parâmetro especial workflow.Context.

Atividades

Atividades são unidades de trabalho que contêm operações não determinísticas (I/O, chamadas de API externa). As atividades são executadas fora do workflow e retornam resultados para a lógica do workflow.

Workers

Um Worker aloca e executa funções de Workflow e Atividade. Os workers sondam as filas de tarefas do servidor Temporal e processam tarefas. Eles devem registrar workflows e atividades antes de iniciar.

Filas de Tarefas

Uma Fila de Tarefas é como um worker recebe tarefas do servidor Temporal. Workflows e atividades especificam o nome da fila de tarefas que usarão.

Configuração do Seu Projeto Go com Temporal

Pré-requisitos

  • Go (1.16+)
  • Servidor Temporal (local ou em nuvem)
  • Docker (para servidor local)
  • Dependência go.temporal.io/sdk

Instale o SDK Temporal Go

go get go.temporal.io/sdk

Inicie o Servidor de Desenvolvimento Temporal

Para desenvolvimento local:

docker run -d --network host temporalio/temporal-server

Ou use o CLI Temporal:

temporal server start-dev

Isso inicia o servidor Temporal e a interface Web por padrão.

Configuração: Clientes e Filas de Tarefas

Crie um Cliente Temporal

c, err := client.NewClient(client.Options{
    HostPort: "localhost:7233",
})
if err != nil {
    log.Fatal(err)
}
defer c.Close()

Escolha uma Fila de Tarefas

Defina uma fila de tarefas única para seu worker:

const TaskQueue = "order-processing-queue"

Workers e iniciadores de workflow devem usar o mesmo nome da fila de tarefas.

Exemplos em Go: Workflows e Atividades

Defina um Workflow Simples

func SampleWorkflow(ctx workflow.Context, input string) (string, error) {
    ao := workflow.ActivityOptions{
        TaskQueue:           TaskQueue,
        ScheduleToCloseTimeout: time.Minute,
    }
    ctx = workflow.WithActivityOptions(ctx, ao)

    var result string
    err := workflow.ExecuteActivity(ctx, SampleActivity, input).Get(ctx, &result)
    if err != nil {
        return "", err
    }
    return result, nil
}

Defina uma Atividade

func SampleActivity(ctx context.Context, message string) (string, error) {
    return fmt.Sprintf("Hello %s!", message), nil
}

Registre e Execute o Worker

w := worker.New(c, TaskQueue, worker.Options{})
w.RegisterWorkflow(SampleWorkflow)
w.RegisterActivity(SampleActivity)

err = w.Start()
if err != nil {
    log.Fatal(err)
}

Inicie a Execução do Workflow

we, err := c.ExecuteWorkflow(context.Background(), client.StartWorkflowOptions{
    ID:        "sample-workflow-id",
    TaskQueue: TaskQueue,
}, SampleWorkflow, "Developer")

Implantação de Temporal e Workers em Go

Opções de Implantação em Produção

  • Cluster Temporal Auto-hospedado: Configure os serviços Temporal (frontend, histórico, correspondência) com armazenamento persistente (Cassandra, MySQL).
  • Temporal Cloud: Serviço gerenciado Temporal com SLA e escalabilidade.
  • Docker Compose ou Kubernetes: Para ambientes de staging ou produção.

Certifique-se de configurar:

  • Camada de persistência
  • Configuração de namespace
  • TLS/autenticação segura (chaves API, mTLS)

Escalabilidade de Workers

Implante múltiplos workers atrás de um balanceador de carga. Os workers escalam horizontalmente ao se juntarem às mesmas filas de tarefas e compartilharem a carga de trabalho.

Testando Workflows e Atividades em Go

Temporal inclui um conjunto de testes:

testSuite := testsuite.WorkflowTestSuite{}
env := testSuite.NewTestWorkflowEnvironment()

env.RegisterWorkflow(SampleWorkflow)
env.RegisterActivity(SampleActivity)

env.ExecuteWorkflow(SampleWorkflow, "Tester")

Afirme os resultados:

var result string
require.NoError(t, workflowRun.Get(context.Background(), &result))
require.Equal(t, "Hello Tester!", result)

Testar com suites de testes garante a determinismo e a confiabilidade do código de workflow antes da implantação.

Melhores Práticas para Produção

  • Timeouts & Políticas de Retentativa: Defina timeout e políticas de retenção sensíveis para atividades e workflows.
  • Logs Estruturados: Emita logs com IDs de rastreamento e metadados de correlação.
  • IDs de Workflow: Use IDs de workflow significativos para rastreabilidade.
  • Workflows Filhos & ContinueAsNew: Divida lógica complexa em execuções modulares para reduzir o tamanho do histórico.
  • Métricas & Monitoramento: Integre com Prometheus ou outras ferramentas de observabilidade.

Solução de Problemas comuns

Worker Não Está Sondando

  • Certifique-se de que o nome da fila de tarefas esteja correto.
  • Confirme a conectividade de rede com o servidor Temporal.

Workflow Não Consegue Iniciar

  • Valide o registro do workflow antes de iniciar o worker.
  • Confirme os parâmetros de conexão do cliente.

Falhas em Atividades

  • Verifique a configuração da política de retenção.
  • Examine a interface Web para rastrear pilhas de erros.

Erros de Workflow Não Determinístico

Temporal exige a execução determinística dos workflows. Revise o código para:

  • Uso de math/rand
  • Goroutines dentro da lógica do workflow
  • Chamadas a sistemas externos dentro dos workflows

Sempre garanta que os workflows sejam código de orquestração puro enquanto invocam sistemas externos por meio de atividades.

Implementar aplicações de workflow com Temporal em Go permite que você construa lógica de negócios estável, resiliente e escalável usando idiomas familiares de Go. Com o modelo de execução garantido do Temporal, retenções integradas, filas de tarefas e suporte à observabilidade, você pode se concentrar na lógica central da sua aplicação sem reinventar a orquestração. Comece com workflows e atividades simples e escale para orquestrações distribuídas complexas com confiança.