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

Construa fluxos de trabalho em Go com o SDK Temporal

Conteúdo da página

Temporal é um mecanismo de workflow de código aberto e nível empresarial que permite aos desenvolvedores construir aplicações de workflow duráveis, escaláveis e tolerantes a falhas, utilizando linguagens de programação familiares como Go.

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

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

Go Workplace

O que é 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, retries, temporizadores e recuperação de falhas nos bastidores, permitindo que os desenvolvedores se concentrem na lógica da aplicação sem código boilerplate de orquestração. Ele suporta Go, entre outras linguagens, através do SDK Go do Temporal.

Ao usar o Temporal com Go:

  • Workflows são duráveis e replayáveis.
  • Retries e timeouts de atividades são tratados automaticamente.
  • O estado do sistema persiste através de falhas.
  • A lógica de orquestração de tarefas reside em código Go idiomático.

Conceitos Principais: Workflows, Atividades, Workers

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

Workflows

Um Workflow é a lógica de coordenação durável que invoca atividades. Ele deve ser determinístico — o motor do Temporal pode reproduzi-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 as unidades de trabalho que contêm operações não determinísticas (E/S, chamadas de API externas). As atividades são executadas fora do workflow e retornam resultados para a lógica do workflow.

Workers

Um Worker hospeda e executa funções de Workflow e Activity. Os workers fazem polling nas filas de tarefas do servidor Temporal e processam as 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 utilizarão.

Configurando 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

Instalar o SDK Go do Temporal

go get go.temporal.io/sdk

Iniciar o Servidor de Desenvolvimento do Temporal

Para desenvolvimento local:

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

Ou use a CLI do Temporal:

temporal server start-dev

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

Configuração: Clientes e Filas de Tarefas

Criar um Cliente Temporal

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

Escolher 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 de fila de tarefas.

Exemplos em Go: Workflows e Atividades

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

Definir uma Atividade

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

Registrar e Executar o Worker

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

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

Iniciar a Execução do Workflow

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

Implantando Workers do Temporal e Go

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

  • Cluster Temporal Auto-hospedado: Configure serviços Temporal (frontend, history, matching) com armazenamento persistente (Cassandra, MySQL).
  • Temporal Cloud: Serviço Temporal gerenciado 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
  • Autenticação segura/TLS (chaves de API, mTLS)

Escalabilidade do Worker

Implante múltiplos workers atrás de um load balancer. Os workers escalam horizontalmente ao juntar-se às mesmas filas de tarefas e compartilhar a carga de trabalho.

Testando Workflows e Atividades em Go

O Temporal inclui um suite de testes:

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

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

env.ExecuteWorkflow(SampleWorkflow, "Tester")

Afirmar resultados:

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

Testar com suites de teste garante o determinismo e a confiabilidade do código do workflow antes da implantação. Para os serviços Go que sustentam atividades do Temporal — particularmente aqueles com loops de retry, prazos de contexto e lógica baseada em temporizadores — Testando Código Go Concorrente com testing/synctest cobre como testar unitariamente esse comportamento dependente de tempo de forma isolada usando relógios falsos e bolhas isoladas.

Melhores Práticas para Produção

  • Timeouts e Políticas de Retry: Defina timeouts e retries sensíveis para atividades e workflows.
  • Log Estruturado: Emita logs com IDs de rastreamento e metadados de correlação.
  • IDs de Workflow: Use IDs de workflow significativos para rastreabilidade.
  • Workflows Filhos e ContinueAsNew: Divida lógica complexa em execuções modulares para reduzir o tamanho do histórico.
  • Métricas e Monitoramento: Integre com Prometheus ou outras ferramentas de observabilidade.
  • Publicação confiável de eventos a partir de atividades: Quando uma atividade escreve em um banco de dados e também precisa notificar outro serviço, use o padrão de outbox transacional para garantir que o evento não seja perdido entre o commit do banco de dados e a publicação no broker.

Solução de Problemas Comuns

Worker Não Faz Polling

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

Workflow Falha ao Iniciar

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

Falhas de Atividade

  • Verifique a configuração da política de retry.
  • Examine a Interface Web para rastrear pilhas de erro.

Erros de Workflow Não Determinísticos

O Temporal impõe execução determinística de workflows. Revise o código quanto a:

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

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

Implementar aplicações de workflow com Temporal em Go permite que você construa lógica de negócios com estado, resiliente e escalável usando idioms Go familiares. Com o modelo de execução garantido do Temporal, retries integrados, filas de tarefas e suporte a observabilidade, você pode focar na lógica central da sua aplicação sem reinventar a orquestração. Comece com workflows e atividades simples e escale para orquestração distribuída complexa com confiança.

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.