Temporal Go SDK (temporal-golang-pro)

Visão Geral

Guia de nível especialista para construir sistemas distribuídos resilientes, escaláveis e determinísticos usando o Temporal Go SDK. Essa habilidade transforma requisitos vagos de orquestração em implementações Go prontas para produção, focando em execução durável, determinismo rigoroso e configuração de workers em escala empresarial.

Quando Usar Esta Habilidade

• Projetando Sistemas Distribuídos: Ao construir microsserviços que exigem estado durável e orquestração confiável.
• Implementando Workflows Complexos: Usando o Go SDK para lidar com processos de longa duração (dias/meses) ou padrões Saga complexos.
• Otimizando Desempenho: Quando os workers precisam de concorrência ajustada, segurança mTLS ou interceptores personalizados.
• Garantindo Confiabilidade: Implementando atividades idempotentes, tratamento de erros gracioso e políticas de retentativa sofisticadas.
• Manutenção e Evolução: Versionando workflows em execução ou realizando atualizações de workers sem tempo de inatividade.

Não use esta habilidade quando

• Usando Temporal com outros SDKs (Python, Java, TypeScript) - consulte suas habilidades -pro específicas.
• A tarefa é uma simples requisição/resposta sem necessidade de durabilidade ou coordenação.
• Design de alto nível sem implementação (use workflow-orchestration-patterns).

Guia Passo a Passo

1. Reúna o Contexto: Pergunte proativamente sobre:
   • Cluster Temporal de destino (Cloud vs. Auto-hospedado) e Namespace.
   • Nomes das Task Queues e vazão esperada.
   • Requisitos de segurança (caminhos mTLS, autenticação).
   • Modos de falha e políticas de retentativa/timeout desejadas.
2. Verifique o Determinismo: Antes de sugerir código de workflow, verifique contra estas 5 Regras:
   • Sem concorrência nativa Go (goroutines).
   • Sem tempo nativo (time.Now, time.Sleep).
   • Sem iteração de mapa não determinística (as chaves devem ser ordenadas).
   • Sem I/O externo direto ou chamadas de rede.
   • Sem números aleatórios não determinísticos.
3. Implemente Incrementalmente: Comece com classes Protobuf/Dados compartilhadas, depois Atividades, depois Workflows e, finalmente, Workers.
4. Aproveite os Recursos: Se a implementação exigir padrões avançados (Sagas, Interceptores, Teste de Replay), consulte explicitamente o playbook de implementação e as estratégias de teste.

Capacidades

Implementação do Go SDK

• Gerenciamento de Workers: Conhecimento profundo de worker.Options, incluindo MaxConcurrentActivityTaskPollers, WorkerStopTimeout e StickyScheduleToStartTimeout.
• Interceptores: Implementação de interceptores de Cliente, Worker e Workflow para preocupações transversais (logging, tracing, auth).
• Conversores de Dados Personalizados: Integração de Protobuf, payloads criptografados ou marshaling JSON personalizado.

Padrões Avançados de Workflow

• Concorrência Durável: Usando workflow.Go, workflow.Channel e workflow.Selector em vez de primitivas nativas.
• Versionamento: Implementação de evolução de código segura usando workflow.GetVersion e workflow.GetReplaySafeLogger.
• Processamento em Larga Escala: Padrão para ContinueAsNew para gerenciar limites de tamanho de histórico (padrões: 50MB ou 50K eventos).
• Child Workflows: Gerenciamento de ciclo de vida, cancelamento e propagação de sinais pai-filho.

Teste e Observabilidade

• Domínio da Testsuite: Usando WorkflowTestSuite para testes unitários e funcionais com controle de tempo determinístico.
• Mocking: Estratégias sofisticadas de mocking de atividades e child workflows.
• Teste de Replay: Validação de alterações de código contra históricos de eventos de produção.
• Métricas: Configuração de exportadores Prometheus/OpenTelemetry para rastreamento de desempenho de workers.

Exemplos

Exemplo 1: Workflow Versionado (Determinístico)

// Nota: imports omitidos. Requer 'go.temporal.io/sdk/workflow', 'go.temporal.io/sdk/temporal', e 'time'.
func SubscriptionWorkflow(ctx workflow.Context, userID string) error {
    // 1. Versionamento para evolução da lógica (v1 = DefaultVersion)
    v := workflow.GetVersion(ctx, "billing_logic", workflow.DefaultVersion, 2)

    for i := 0; i < 12; i++ {
        ao := workflow.ActivityOptions{
            StartToCloseTimeout: 5 * time.Minute,
            RetryPolicy: &temporal.RetryPolicy{MaximumAttempts: 3},
        }
        ctx = workflow.WithActivityOptions(ctx, ao)

        // 2. Execução da Atividade (Sempre trate erros)
        err := workflow.ExecuteActivity(ctx, ChargePaymentActivity, userID).Get(ctx, nil)
        if err != nil {
            workflow.GetLogger(ctx).Error("Pagamento falhou", "Erro", err)
            return err
        }


…