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

Crie workflows em Go com o SDK Temporal

Conteúdo da página

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

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

Este guia explica como implementar aplicações de fluxo de trabalho com Temporal em Go, abordando 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 fluxos de trabalho projetado para construir aplicações distribuídas de longa duração e tolerantes a falhas. O Temporal gerencia o estado, repetições, temporizadores e recuperação de falhas nos bastidores, permitindo que os desenvolvedores se concentrem na lógica da aplicação sem código de orquestração repetitivo. Ele suporta Go, entre outras linguagens, através do SDK Go do Temporal.

Ao usar o Temporal com Go:

  • Os fluxos de trabalho são duráveis e podem ser reproduzidos.
  • As repetições e tempos de espera 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: Fluxos de Trabalho, Atividades e Workers

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

Fluxos de Trabalho (Workflows)

Um Fluxo de Trabalho (Workflow) é uma lógica de coordenação durável que invoca atividades. Ele deve ser determinístico - o motor do Temporal pode reproduzi-lo com confiabilidade. Em Go, os fluxos de trabalho são funções Go regulares com um parâmetro especial workflow.Context.

Atividades (Activities)

Atividades são as unidades de trabalho que contêm operações não determinísticas (E/S, chamadas de API externas). As atividades executam fora do fluxo de trabalho e retornam resultados para a lógica do fluxo de trabalho.

Workers (Trabalhadores)

Um Worker hospeda e executa funções de Fluxo de Trabalho e Atividades. Os Workers consultam as filas de tarefas do servidor Temporal e processam as tarefas. Eles devem registrar fluxos de trabalho e atividades antes de iniciar.

Filas de Tarefas (Task Queues)

Uma Fila de Tarefas (Task Queue) é como um worker recebe tarefas do servidor Temporal. Fluxos de trabalho 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 na 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 o 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 fluxo de trabalho devem usar o mesmo nome de fila de tarefas.

Exemplos em Go: Fluxos de Trabalho e Atividades

Definir um Fluxo de Trabalho 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 Fluxo de Trabalho

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

Implantando Temporal e Workers em Go

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

  • Cluster Temporal Auto-hospedado: Configure os serviços do 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 homologação 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 balanceador de carga. Workers escalam horizontalmente ao se juntar às mesmas filas de tarefas e compartilhar a carga de trabalho.

Testando Fluxos de Trabalho e Atividades em Go

O Temporal inclui uma suíte 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 suítes de testes garante a determinação e confiabilidade do código do fluxo de trabalho antes da implantação.

Melhores Práticas para Produção

  • Tempos de Espera e Políticas de Retentativa: Defina tempos de espera e retentativas sensatas para atividades e fluxos de trabalho.
  • Log Estruturado: Emita logs com IDs de rastreamento e metadados de correlação.
  • IDs de Fluxo de Trabalho: Use IDs de fluxo de trabalho significativos para rastreabilidade.
  • Fluxos de Trabalho Filhos e ContinueAsNew: Divida a 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.

Solução de Problemas Comuns

Worker Não Consultando (Not Polling)

  • Garanta o nome correto da fila de tarefas.
  • Confirme a conectividade de rede ao servidor Temporal.

Falha ao Iniciar o Fluxo de Trabalho

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

Falhas de Atividade

  • Verifique a configuração da política de retentativa.
  • Examine a Interface Web para rastros de pilha de erros.

Erros de Fluxo de Trabalho Não Determinísticos

O Temporal exige execução determinística de fluxos de trabalho. Revise o código quanto a:

  • Uso de math/rand
  • Goroutines dentro da lógica do fluxo de trabalho
  • Chamadas de sistemas externos dentro de fluxos de trabalho

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

Implementar aplicações de fluxo de trabalho com Temporal em Go permite que você construa lógica de negócios com estado, resiliente e escalável usando idiomáticos Go familiares. Com o modelo de execução garantido do Temporal, retentativas integradas, 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 fluxos de trabalho e atividades simples e escale com confiança para orquestração distribuída complexa.