Desenvolva com o SDK Durable Task for Go

Ao usar o Durable Task SDK for Go, você pode definir orquestrações, atividades e entidades duráveis como funções do Go. Hospede a aplicação na sua própria plataforma de computação. O Durable Task Scheduler armazena o histórico de execução e despacha o trabalho para seus workers em Go.

Importante

O SDK do Go está em beta. Este artigo e o quickstart do Go usam a v1.0.0-beta3. A beta não é um substituto direto para a v0.6.0: não suporta backends SQLite e PostgreSQL embarcados nem o host gRPC standalone. Go não é uma linguagem Durable Functions.

Pré-requisitos e instalação

Instale a beta lançada a partir de um módulo Go existente:

go get github.com/microsoft/durabletask-go@v1.0.0-beta3

Depois de adicionar importações de SDK ao seu código, execute go mod tidy para registrar dependências transitivas e somas de verificação.

Para uma aplicação completa que inicia um trabalhador, agenda atividades paralelas, lê seus resultados e desliga, veja Criar um aplicativo com SDKs de Tarefas Duráveis - Go.

Modelo de programação

O SDK é enviado como um único módulo Go. Seus principais pacotes são:

Package Purpose
task Orquestração, atividade e contextos de entidade; registro de tarefas; primitivas de workflow duráveis.
durabletaskscheduler Opções de conexão, e conexões separadas de clientes e trabalhadores para o Durable Task Scheduler.
client Configuração de trabalhadores, incluindo concorrência, versionamento e filtros de itens de trabalho.
api IDs de instância e entidade, metadados de orquestração e opções de requisição de gerenciamento.

Um orquestrador tem a assinatura func(*task.OrchestrationContext) (any, error). Uma atividade tem a assinatura func(task.ActivityContext) (any, error). Uma entidade baseada em funções tem a assinatura func(*task.EntityContext) (any, error). Leia a entrada tipada com GetInput, e retorne um resultado serializável ou um erro. JSON é o formato padrão de dados.

Registrar e executar tarefas

Crie um Registro com task.NewTaskRegistry. Registre nomes estáveis com AddOrchestratorN, AddActivityN e AddEntityN e verifique erros de registro. Os nomes usados em chamadas de atividade e agendamento de clientes devem corresponder às inscrições.

Analise sintaticamente a cadeia de conexão com durabletaskscheduler.NewOptionsFromConnectionString. Passe as opções para:

  • durabletaskscheduler.NewClient para iniciar e gerenciar instâncias de orquestração.
  • durabletaskscheduler.NewWorker para executar tarefas registradas.

Chame Start no worker para começar a processar os itens de trabalho. Use client.WithAutoWorkItemFilters() para derivar filtros de roteamento de workers a partir do registry. Não deixe um trabalhador consumir tarefas registradas apenas por outro aplicativo.

O cliente e o trabalhador possuem conexões separadas. Feche o aplicativo cliente quando terminar. Drene o worker com Shutdown, usando um contexto novo e limitado se o contexto de execução da aplicação expirou. O guia de início rápido verifica os erros das duas operações.

Escrever orquestradores determinísticos

Use o contexto de orquestração para operações Durable:

Operation Go API Learn more
Sequenciar atividades ctx.CallActivity(...).Await(&result) Encadeamento de funções
Fan-out e fan-in Agende todas as tarefas, depois ctx.WhenAll(tasks...) e leia os resultados com Await Fan-out/fan-in
Atraso ctx.CreateTimer(duration).Await(nil) Temporizadores duráveis
Espere por um evento ctx.WaitForSingleEvent(name, timeout).Await(&result) Eventos externos
Chame um fluxo de trabalho filho ctx.CallSubOrchestrator(...).Await(&result) Sub-orquestrações
Repetir uma atividade task.WithActivityRetryPolicy Tratamento de erros e novas tentativas
Comece um novo histórico ctx.ContinueAsNew Orquestrações eternas
Progresso do relatório ctx.SetCustomStatusValue Status personalizado
Chame ou sinalize uma entidade ctx.CallEntity e ctx.SignalEntity Entidades duráveis

Não realize chamadas de rede, I/O de arquivos, leituras de variáveis de ambiente ou outros trabalhos não determinísticos em um orquestrador. Coloque esse trabalho em atividades. Use as primitivas de concorrência durável do SDK em vez de goroutines nativas, canais, sync.WaitGroup ou time.Sleep, no código do orquestrador. Use ctx.Logger() para registro com reconhecimento de replay. Para detalhes, veja restrições de código do Orchestrator.

As atividades podem realizar E/S Go comum, mas podem ser executadas mais de uma vez. Faça com que os efeitos colaterais externos sejam idempotentes.

Ler os resultados da conclusão

WaitForOrchestrationCompletion retornando sem erro significa que a instância atingiu um estado terminal, não necessariamente que o fluxo de trabalho foi bem-sucedido. Solicite cargas úteis com api.WithFetchPayloads(true), verifique se RuntimeStatus é api.RUNTIME_STATUS_COMPLETED, e então decodifique a saída com ReadOutput.

Para casos de falha, inspecione FailureDetails. Não informe uma orquestração fracassada ou encerrada como resultado bem-sucedido. Veja Gerenciamento de instâncias.

Conecte-se ao emulador ou ao Azure

O quickstart usa a cadeia de conexão Endpoint=http://localhost:8080;TaskHub=default;Authentication=None. Use Authentication=None para desenvolvimento local de emuladores, não para acesso autenticado ao Azure.

Para o Azure, use o endpoint HTTPS do seu agendador e o nome do hub de tarefas. Selecione Authentication=DefaultAzure para a cadeia de credenciais Azure Identity ou Authentication=AzureCLI para uma identidade de desenvolvimento logada pelo CLI do Azure. O Go SDK também suporta identidade gerenciada e identidade de carga de trabalho. Para detalhes de configuração e modos de autenticação suportados, consulte o guia de conexão do Go SDK.

O quickstart lê a cadeia de conexão da DTS_CONNECTION_STRING variável ambiente e a passa para NewOptionsFromConnectionString. O SDK não lê essa variável automaticamente.

Exemplos

O repositório do Go SDK inclui amostras executáveis para suas áreas de funcionalidades, incluindo sequências de atividade, fan-out/fan-in, eventos externos, novas tentativas, entidades duráveis, agendamentos, payloads grandes, exportação de histórico e rastreamento distribuído. Para a lista completa, pré-requisitos e instruções de execução, veja os exemplos do Go SDK.

Orquestrações de teste

O SDK não inclui um backend de armazenamento, então as orquestrações rodam apenas contra o Durable Task Scheduler ou seu emulador. Teste atividades e outras lógicas de negócios com testes unitários comuns do Go. Para verificar o comportamento da orquestração, incluindo reexecução, execute testes de integração no emulador ou em um hub de tarefas dedicado.

Considerações de compatibilidade da versão beta

  • Agendamentos: Os agendamentos do Go não compartilham seu formato de estado persistente com outros SDKs. Use um hub de tarefas apenas para Go para tarefas agendadas.
  • Bloqueios de entidade: Go e Python usam uma ordenação de bloqueio multi-entidade diferente do .NET. Não adquira conjuntos de bloqueios sobrepostos simultaneamente entre orquestrações Go/Python e .NET.
  • Retroceder: O trabalhador do Go rejeita conservadoramente históricos com eventos adicionais que não são de ciclo de vida após uma atividade ou operação filha fracassada. Uma solicitação de rewind aceita não prova a recuperação; verifique um novo ID de execução e a saída bem-sucedida.
  • APIs de gerenciamento de emuladores: Listagem de instâncias e purga filtrada têm limitações de emulador documentadas. Prefira limpeza com escopo de instância para exemplos, e não limpe um hub compartilhado.
  • Exportação de histórico (prévia): Use um hub de tarefas isolado, apenas Go, e um destino de exportação para que os jobs de exportação não possam exportar ou excluir dados de aplicação não relacionados.

Consulte a matriz de recursos e guia de transporte do SDK Go para compatibilidade detalhada e comportamento do ciclo de vida.

Conteúdo relacionado

  • Última atualização em