Desarrolla con el SDK de Tareas Duraderas para Go

Usando el SDK de Tareas Duraderas para Go, puedes definir orquestaciones, actividades y entidades duraderas como funciones de Go. Aloja la aplicación en tu propia plataforma de cómputo. El Durable Task Scheduler almacena el historial de ejecución y envía el trabajo a tus workers de Go.

Importante

El SDK de Go está en beta. Este artículo y el inicio rápido de Go usan la versión 1.0.0-beta3. La beta no es un sustituto directo de la v0.6.0: no soporta backends embebidos de SQLite y PostgreSQL ni el host gRPC independiente. Go no es un lenguaje Durable Functions.

Requisitos previos e instalación

Instala la versión beta publicada desde un módulo de Go existente:

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

Después de añadir importaciones de SDK a tu código, ejecuta go mod tidy para registrar dependencias transitivas y sumas de comprobación.

Para una aplicación completa que inicia un worker, programa actividades paralelas, lee sus resultados y se cierra, consulta Crear una aplicación con SDKs de tareas duraderas - Go.

Modelo de programación

El SDK se distribuye como un solo módulo Go. Sus paquetes principales son:

Package Purpose
task Contextos de orquestación, actividad y entidad; registro de tareas; primitivas de flujo de trabajo duradero.
durabletaskscheduler Opciones de conexión, y conexiones separadas de clientes y trabajadores a Durable Task Scheduler.
client Configuración de los trabajadores, incluyendo concurrencia, versionado y filtros de elementos de trabajo.
api IDs de instancia y entidad, metadatos de orquestación y opciones de solicitud de gestión.

Un orquestador tiene la firma func(*task.OrchestrationContext) (any, error). Una actividad tiene la firma func(task.ActivityContext) (any, error). Una entidad basada en funciones tiene la firma func(*task.EntityContext) (any, error). Lee la entrada tipada con GetInput, y devuelve un resultado serializable o un error. JSON es el formato de datos por defecto.

Registrar y ejecutar tareas

Cree un registro con task.NewTaskRegistry. Registre nombres estables con AddOrchestratorN, AddActivityN y AddEntityN, y compruebe los errores de registro. Los nombres que se usan en las llamadas a actividades y en la programación del cliente deben coincidir con los registros.

Analiza la cadena de conexión con durabletaskscheduler.NewOptionsFromConnectionString. Transmite las opciones a:

  • durabletaskscheduler.NewClient para iniciar y gestionar instancias de orquestación.
  • durabletaskscheduler.NewWorker para ejecutar tareas registradas.

Llame a Start en el rol de trabajo para empezar a procesar los elementos de trabajo. Use client.WithAutoWorkItemFilters() para derivar los filtros de enrutamiento del rol de trabajo a partir del registro. No dejes que un trabajador consuma tareas registradas solo por otra aplicación.

El cliente y el trabajador poseen conexiones separadas. Cierra la aplicación cuando termines. Drene el rol de trabajo con Shutdown, usando un contexto nuevo y limitado si el contexto de ejecución de la aplicación ha expirado. El inicio rápido comprueba los errores de ambas operaciones.

Escribe orquestadores deterministas

Utiliza el contexto de orquestación para operaciones duraderas:

Operation Go API Más información
Actividades de secuencia ctx.CallActivity(...).Await(&result) Encadenamiento de funciones
Distribución ramificada de salida y de entrada Programe todas las tareas, luego ctx.WhenAll(tasks...) y lea los resultados con Await Fan-out/fan-in
Delay ctx.CreateTimer(duration).Await(nil) Temporizadores duraderos
Esperar un evento ctx.WaitForSingleEvent(name, timeout).Await(&result) Eventos externos
Llama a un flujo de trabajo hijo ctx.CallSubOrchestrator(...).Await(&result) Sub-orquestaciones
Reintentar una actividad task.WithActivityRetryPolicy Gestión de errores y reintentos
Empieza un historial nuevo ctx.ContinueAsNew Orquestaciones eternas
Informar progreso ctx.SetCustomStatusValue Estado personalizado
Llamar o emitir una señal a una entidad ctx.CallEntity y ctx.SignalEntity Entidades duraderas

No realices llamadas de red, E/S de archivos, lecturas de variables de entorno ni otros trabajos no deterministas en un orquestador. Coloque ese trabajo en actividades. Use las primitivas de simultaneidad duraderas del SDK en lugar de goroutines nativas, canales, sync.WaitGroup o time.Sleep en el código del orquestador. Use ctx.Logger() para el registro con reconocimiento de reproducción. Para más detalles, véase las restricciones de código de Orchestrator.

Las actividades pueden realizar operaciones de E/S normales de Go, pero pueden ejecutarse más de una vez. Haz que los efectos secundarios externos sean idempotentes.

Leer los resultados de finalización

WaitForOrchestrationCompletion Devolver sin error significa que la instancia alcanzó un estado terminal, no necesariamente que el flujo de trabajo haya tenido éxito. Solicita cargas útiles con api.WithFetchPayloads(true), comprueba que RuntimeStatus es api.RUNTIME_STATUS_COMPLETED, y luego decodifica la salida con ReadOutput.

Para instancias fallidas, inspecciona FailureDetails. No informes de una orquestación fallida o terminada como resultado exitoso. Consulta Gestión de instancias.

Conéctate al emulador o a Azure

El inicio rápido utiliza la cadena de conexión Endpoint=http://localhost:8080;TaskHub=default;Authentication=None. Use Authentication=None para el desarrollo con el emulador local, no para el acceso autenticado a Azure.

Para Azure, usa el endpoint HTTPS y el nombre del hub de tareas de tu planificador. Selecciona Authentication=DefaultAzure para la cadena de credenciales de identidad de Azure, o Authentication=AzureCLI para una identidad de desarrollo que ha iniciado sesión a través de CLI de Azure. El Go SDK también soporta identidad gestionada e identidad de carga de trabajo. Para detalles de configuración y modos de autenticación compatibles, consulte la guía de conexión del Go SDK.

La guía de inicio rápido lee la cadena de conexión de la variable de entorno DTS_CONNECTION_STRING y la pasa a NewOptionsFromConnectionString. El SDK no lee esta variable automáticamente.

Ejemplos

El repositorio del SDK de Go incluye ejemplos ejecutables para sus funcionalidades, como secuencias de actividad, fan-out/fan-in, eventos externos, reintentos, entidades duraderas, programaciones, cargas de datos grandes, exportación del historial y trazado distribuido. Para la lista completa, los requisitos previos e instrucciones de ejecución, consulta los ejemplos del SDK Go.

Orquestaciones de prueba

El SDK no incluye un backend de almacenamiento, por lo que las orquestaciones solo se ejecutan contra Durable Task Scheduler o su emulador. Pruebe las actividades y otra lógica de negocio con pruebas unitarias ordinarias de Go. Para verificar el comportamiento de la orquestación, incluido el replay, ejecuta pruebas de integración contra el emulador o un hub de tareas dedicado.

Consideraciones de compatibilidad en beta

  • Programaciones: Las programaciones de Go no comparten su formato de estado persistente con otros SDK. Usa un centro de tareas solo para Go para tareas programadas.
  • Bloqueos de entidad: Go y Python usan un orden de bloqueo multi-entidad diferente de .NET. No adquieras conjuntos de bloqueos superpuestos simultáneamente en orquestaciones de Go/Python y .NET.
  • Retroceder: El trabajador de Go rechaza de forma conservadora los historiales con eventos adicionales no relacionados con el ciclo de vida tras una actividad fallida o una operación hija. Una solicitud de rebobinado aceptada no demuestra la recuperación; compruebe que haya un nuevo identificador de ejecución y una salida correcta.
  • APIs de gestión de emuladores: El listado de instancias y la purga filtrada tienen limitaciones del emulador documentadas. Prefiera la limpieza con alcance de instancia para los ejemplos y no borre un hub compartido.
  • Exportación del historial (versión preliminar): Utiliza un centro de tareas aislado exclusivo de Go y un destino de exportación para que los trabajos de exportación no puedan exportar ni eliminar datos no relacionados de la aplicación.

Consulta la matriz de características y la guía de transporte del SDK de Go para detalles de compatibilidad y comportamiento en el ciclo de vida.

Contenido relacionado

  • Última actualización el