Introducción

La fiabilidad en una arquitectura orientada a eventos exige más que publicar mensajes y esperar que todo funcione. Necesito pensar en la entrega al menos una vez, la idempotencia, la transacción local con Outbox, los estados observables, el orden por clave y la compensación. Cuando dejo estos puntos de lado, el sistema se convierte en un laboratorio de duplicados, reintentos mal gestionados y estados inconsistentes entre una operación local y el siguiente procesamiento asíncrono.

Este artículo muestra un camino práctico para construir un flujo con PostgreSQL y Azure Service Bus Emulator, manteniendo la complejidad en un laboratorio reproducible. La idea central es simple: registro el efecto local y la intención de publicar en una única transacción, y después proceso los eventos con inbox y saga, sin fingir que exactly-once es una promesa real en sistemas distribuidos.

Requisitos previos

Recomiendo Docker Desktop o Docker Engine, Compose, .NET 10 y un entorno local con memoria suficiente para ejecutar PostgreSQL, SQL Server para el emulador y la API. El ejemplo completo está disponible en el repositorio de ejemplos del blog: BlogSamples/Messaging/EventDriven/.

Infraestructura y estructura necesarias para una implementación robusta

Una implementación robusta de eventos no es solo un endpoint HTTP y un worker. Necesita una pequeña plataforma local con cuatro bloques bien definidos:

  1. una API para aceptar el comando de negocio y persistir el efecto local;
  2. una base de datos PostgreSQL como fuente de verdad del estado del pedido, de la saga y de los mensajes de integración;
  3. un broker local, en este caso el Azure Service Bus Emulator, para transporte, enrutamiento, sesiones y DLQ;
  4. workers para publicar los mensajes del Outbox y procesar mensajes de forma idempotente.

La estructura mínima del ejemplo debe contemplar:

  • Endpoints/ para crear y consultar pedidos;
  • Contracts/ con envelopes versionados y DTOs;
  • Persistence/ con DbContext, migrations y modelos de pedido, outbox, inbox y saga;
  • Saga/ con el orquestador y las transiciones de estado;
  • ServiceBus/ con publisher, consumidores y adaptadores para el emulador;
  • docker-compose.yml y README.md para levantar el stack localmente.

Además, la solución necesita algunos componentes operativos que muchos ejemplos dejan de lado:

  • tablas separadas para pedido, stock, pago, saga, outbox e inbox;
  • correlation IDs y causation IDs en todos los eventos;
  • reintentos controlados, DLQ y tratamiento explícito de fallos transitorios;
  • una política de idempotencia local para cada consumidor;
  • observabilidad suficiente para responder “¿dónde se quedó atascada la saga?”.

Sin estos bloques, el flujo puede parecer correcto en un escenario simple y fallar en producción cuando la red, el broker o el estado del sistema empiezan a variar.

Por qué una arquitectura orientada a eventos se convierte en caos

El caos empieza cuando confío en dos escrituras separadas y espero que la segunda ocurra. En sistemas distribuidos, un mensaje puede enviarse, la base de datos puede fallar en el commit y la aplicación puede intentarlo de nuevo. Sin tratamiento, termino con un estado local diferente de lo que se publicó. El patrón Outbox resuelve este problema al convertir la publicación en parte de la transacción local. El patrón Inbox resuelve la duplicación en el consumidor, que es uno de los problemas más comunes en entregas al menos una vez.

Este tipo de problema aparece cuando necesito integrar dominios diferentes, como pedido, stock, pago y notificación, y cada uno tiene su propio ciclo de procesamiento. El error común es pensar que el evento es solo un detalle operativo. En la práctica, debe tratarse como parte del contrato de negocio. Si no pienso en reintentos, compensación, orden, observabilidad e idempotencia desde el principio, la aplicación empieza a acumular estados inadvertidos y con cada fallo gano más ruido que valor.

También veo equipos que intentan resolverlo todo con polling, reintentos agresivos y logs dispersos. Eso suele empeorar la situación. Una arquitectura orientada a eventos no es un mecanismo mágico para volver todo distribuido y resiliente; es una forma de organizar la complejidad cuando la operación necesita desacoplarse y tolerar fallos temporales. Si no tengo un flujo con estados explícitos, la experiencia del usuario se convierte en una mezcla de transacciones en curso y fallos invisibles.

La arquitectura del ejemplo con PostgreSQL y Azure Service Bus

El ejemplo local usa PostgreSQL como base de datos de la aplicación y un tópico del Azure Service Bus Emulator con subscriptions filtradas. La API crea un pedido, registra un evento en el Outbox y un orquestador consume el flujo. El flujo es simple, pero ya cubre las decisiones que más suelen causar problemas: orden por pedido, compensación, reintentos y DLQ.

Comparación entre el happy path y el camino de compensación de una saga

La decisión de usar PostgreSQL como sistema de verdad de la aplicación viene de que necesito una transacción local fuerte para registrar el efecto de negocio y, al mismo tiempo, persistir la intención de publicar. Azure Service Bus actúa como capa de entrega asíncrona y orquestación entre pasos independientes. Este diseño funciona bien cuando necesito una línea de tiempo observable y un punto único donde consultar el estado del pedido. En otras palabras, la base de datos se encarga del estado; el broker, de la propagación.

Esta combinación me resulta útil cuando el flujo involucra múltiples sistemas, cada uno con un tiempo de respuesta variable, y necesito evitar que el fallo de un subsistema tumbe toda la operación. La cuestión no es volverlo todo distribuido por gusto; la cuestión es separar lo que debe ser consistente localmente de lo que puede procesarse de forma asíncrona y compensable.

⚠️ Atención: si tu problema todavía es simple, con una única transacción y sin necesidad de desacoplamiento, no empezaría por esta arquitectura. El coste de operar Outbox, Inbox y Saga es real y debe justificarse por un problema de negocio o de integración.

📂 Código Fuente: El ejemplo completo está disponible en el repositorio de ejemplos del blog: BlogSamples/Messaging/EventDriven/

Entrega al menos una vez y mensajes duplicados

La entrega al menos una vez significa que un mensaje puede recibirse más de una vez. No es un bug; es el coste de operar con reintentos y fallos temporales. Lo que necesito hacer es tratar la duplicación como un caso normal. El Inbox es la herramienta correcta para esto, porque almacena el identificador del mensaje y el consumidor, impidiendo un reprocesamiento indebido.

Cuando digo “al menos una vez”, quiero decir que el sistema puede recibir el mismo mensaje más de una vez y, por eso, todo efecto colateral debe ser idempotente. Esto vale para escrituras en base de datos, actualizaciones de estado, envío de correos, creación de registros de auditoría y cualquier acción que no pueda repetirse sin cuidado. El broker puede confirmar la entrega y después el proceso local fallar antes de registrar el estado. En ese caso, en el siguiente intento, recibiré el mismo mensaje otra vez. Sin un mecanismo de deduplicación, puedo crear dos reservas, dos autorizaciones o dos registros de pago para la misma intención original.

Esa es una de las razones por las que nunca confío en “delivery exactly once” como promesa de implementación. Lo que existe, en general, es una combinación de al menos una vez en el transporte, idempotencia en el consumidor y una capa de compensación para los casos en que la operación no puede seguir adelante.

Idempotencia en el consumidor con el patrón Inbox

El consumidor debe ser idempotente por naturaleza. Si recibe un duplicado, debe reconocerlo y devolver éxito sin repetir efectos colaterales. El estado del inbox es el registro de que el mensaje ya fue procesado, independientemente de los reintentos o replays del broker.

La forma más simple de implementarlo es persistir, en el mismo contexto transaccional del efecto de negocio, el identificador del mensaje y el nombre del consumidor. Cuando el mismo mensaje llega otra vez, hago una verificación y corto el flujo antes de cualquier acción adicional. En sistemas reales, esto suele hacerse con una tabla de Inbox con una constraint compuesta en (consumer, message_id), porque eso me da una garantía fuerte de que dos ejecuciones concurrentes no realizarán el mismo efecto dos veces.

Esto es importante porque el broker no sustituye la responsabilidad de la aplicación de ser segura. Service Bus puede tener duplicate detection en algunas configuraciones, pero eso no elimina la necesidad de un control local de deduplicación. El patrón Inbox es la capa que hace que el consumidor reconozca “ya traté esto” y no repita la acción.

Outbox transaccional en PostgreSQL y el problema del dual write

El dual write es el clásico problema de consistencia entre base de datos y broker. El Outbox resuelve este escenario al persistir la intención de publicar en la misma transacción del efecto local. Después, un publisher separado lee el outbox, envía el mensaje y marca el resultado con un update controlado. Esto crea una ventana de incertidumbre, pero no hace que la aplicación mienta sobre lo que fue confirmado.

La implementación práctica suele ser así: inicio una transacción en PostgreSQL, persisto el estado de negocio, inserto el mensaje en el Outbox y solo después hago commit. Si el commit tiene éxito, el mensaje queda garantizado como intención de publicación. A continuación, un segundo proceso — casi siempre un worker — lee los mensajes pendientes y los publica en el broker. El punto crucial es que no actualizo el estado a “publicado” hasta que la publicación haya ocurrido realmente. Este diseño me protege de tener un efecto local sin la notificación correspondiente.

Este patrón es mucho más fiable que intentar publicar primero y registrar el estado local después. Si hago eso, corro el riesgo de perder el mensaje o de crear un estado de negocio sin el evento correspondiente. El Outbox es uno de los pocos patrones que realmente reduce el problema de consistencia entre base de datos y mensajería sin exigir un protocolo distribuido complejo.

ℹ️ Información: detallo el dual write problem y la implementación completa del Transactional Outbox Pattern, incluido el publisher asíncrono y las obligaciones de idempotencia del consumidor, en la segunda parte de esta serie: Transactional Outbox Pattern: resolviendo el dual write.

Consistencia eventual sin ocultar el estado al usuario

Consistencia eventual no significa “dejar al usuario a oscuras”. Necesito exponer el estado actual del pedido, la etapa de la saga y los timestamps. Un pedido puede estar en procesamiento, pero la experiencia debe decir exactamente dónde está y qué está ocurriendo. El estado observable forma parte del diseño, no es un detalle opcional.

Cuándo realmente necesito esta arquitectura

No implemento Outbox, Inbox y Saga porque “parece moderno”. Los implemento porque existe un problema operativo real: una operación de negocio necesita atravesar múltiples pasos, algunos de ellos asíncronos, y necesito mantener la confianza incluso cuando una parte falla. Si estoy tratando con un flujo simple de creación y lectura, con una única transacción y sin compensación, probablemente no lo necesito.

La decisión suele quedar más clara cuando veo señales como estas:

  • un paso depende de otro sistema que puede tardar o fallar;
  • necesito evitar que toda la operación se revierta por un fallo parcial;
  • necesito mantener la trazabilidad del flujo entre dominios;
  • la duplicación de mensajes es una posibilidad real y no un caso raro;
  • el usuario necesita saber en qué fase de la operación se encuentra.
SituaciónRecomendación
CRUD simple, una transacción local y sin integración externamantener el flujo síncrono y simple
un pedido necesita reservar stock, cobrar la tarjeta y notificar al clienteconsiderar Outbox + Saga + Inbox
varios servicios reaccionan a eventos y el flujo debe ser compensableusar saga y estados explícitos
el problema es solo de rendimiento y no de consistencia distribuidano empezar por eventos

La regla práctica es: si necesito una operación distribuida que pueda fallar en un punto intermedio y aun así mantener una experiencia de negocio fiable, debo considerar esta arquitectura.

Cómo lo implementaría en la práctica

La implementación empieza con una decisión de diseño, no con una herramienta. Primero defino los pasos de negocio y sus estados. Después separo dos cosas: lo que debe ser consistente localmente y lo que puede procesarse de forma asíncrona.

  1. Empiezo con una transacción local en PostgreSQL para guardar el efecto de negocio y registrar una intención de publicación en el Outbox.
  2. Añado una tabla de Inbox para garantizar que el mismo evento no genere el mismo efecto dos veces.
  3. Creo un envelope versionado con message_id, correlation_id, causation_id, event_type, schema_version y payload tipado.
  4. Monto un worker responsable de leer los mensajes pendientes del Outbox y publicarlos en el tópico de Service Bus.
  5. Implementé consumidores con PeekLock, AutoCompleteMessages=false y confirmación solo después de que el efecto local esté guardado.
  6. Mantengo un estado explícito de la saga para decidir si avanzo, compenso o detengo el flujo.
  7. Registro logs y métricas con correlation ID para poder analizar todo el flujo cuando algo salga mal.

Esta hoja de ruta es simple de explicar, pero exige disciplina. La mayor parte de los problemas en arquitecturas orientadas a eventos viene de que el equipo trata el evento como un detalle técnico y no como un contrato de negocio.

Saga por coreografía u orquestación: cuál elegir

Una saga orquestada es más fácil de rastrear cuando tengo un flujo de negocio conocido y un orquestador explícito. La coreografía encaja mejor cuando cada pieza reacciona localmente a eventos y el flujo está ampliamente distribuido. Para este ejemplo, elegí la orquestación porque hace que el estado y la compensación sean más fáciles de explicar y probar.

En la práctica, elijo la orquestación cuando el flujo es esencialmente una máquina de estados: pedido creado, stock reservado, pago procesado, compensación en caso de fallo. En este escenario, necesito una entidad que acompañe el estado global del proceso de negocio y decida el siguiente paso. La coreografía tiene más sentido cuando tengo muchos servicios reaccionando a eventos y la complejidad está distribuida entre ellos. La ventaja de la coreografía es un menor acoplamiento; la desventaja es que entender la ejecución completa se vuelve más difícil y la trazabilidad tiende a empeorar.

La saga no es una solución para cualquier problema. Es la forma correcta de modelar una secuencia de pasos que debe compensarse cuando una pieza falla. Si simplemente tengo un proceso lineal y no necesitaré un rollback parcial, probablemente no necesito una Saga.

Orden por pedido con sesiones de Azure Service Bus

Las sesiones de Service Bus preservan el orden por clave de negocio, en este caso por pedido. Esto no equivale a un orden global entre todos los pedidos; lo que gano es un orden local por sesión, algo esencial en flujos que deben procesarse secuencialmente sin bloquear otros pedidos.

Retry, PeekLock y Dead Letter Queue

PeekLock me permite desacoplar el procesamiento de la confirmación. Si algo falla, abandono el mensaje para un reintento. Si el error es persistente o inválido, lo envío a la DLQ con un motivo útil. Esto es mucho más seguro que simplemente perder el mensaje o completarlo demasiado pronto.

Me gusta pensar en tres categorías de fallo cuando implemento esto. La primera es un fallo transitorio: base de datos no disponible, timeout de red, agotamiento de conexiones. En ese caso, abandono el mensaje y dejo que el broker lo entregue de nuevo. La segunda es un fallo de contrato o de validación: el payload está mal formado, llegó un campo inesperado, el schema cambió de forma incompatible. Aquí no quiero reprocesar indefinidamente. Prefiero registrar la causa y enviarlo a la DLQ con un motivo claro. La tercera es un fallo de negocio no recuperable, como un evento que llega cuando el pedido está en un estado inconsistente. En ese caso, la saga debe decidir si describe una violación de contrato o simplemente una inconsistencia tolerable que debe observarse.

Este modelo hace que mi sistema sea predecible. No escondo el fallo bajo reintentos infinitos y tampoco pierdo la información cuando un mensaje es definitivamente inválido.

Contratos de eventos y evolución de schema

Los eventos necesitan contratos claros. No puedo depender solo del payload sin versionado. El ejemplo usa envelopes versionados con IDs de correlación, causación y tipo de evento. Esto ayuda a evolucionar el schema sin convertir la saga en un caos de incompatibilidades.

Observabilidad con correlation y causation IDs

La observabilidad mejora mucho cuando cada mensaje lleva correlation y causation IDs. Puedo rastrear todo el camino del pedido, correlacionar logs, métricas y traces y localizar exactamente dónde la saga se desvió del flujo normal.

Cuándo no usar una arquitectura orientada a eventos

No uso eventos cuando el problema es simple, con consistencia inmediata fuerte y sin necesidad de desacoplamiento. Cuando una transacción simple ya lo resuelve, una arquitectura orientada a eventos puede introducir demasiado coste y complejidad. La regla práctica es: si no necesito flujo asíncrono, compensación y observabilidad distribuida, probablemente no debería empezar por eventos.

Ejemplo Práctico: pedido, stock y pago

El ejemplo completo está disponible en BlogSamples/Messaging/EventDriven/. Implementa un flujo simple en el que un pedido crea un evento de salida, el stock responde y, a continuación, se procesa el pago. En caso de rechazo, la saga emite la compensación y cancela el pedido.

Camino feliz y camino triste

En el camino feliz, el pedido empieza en Criado (creado), emite un evento para reservar stock, recibe la confirmación, pasa al pago y termina con el pedido aprobado. En el camino triste, alguna etapa falla: stock no disponible o pago rechazado. En ese caso, la saga no intenta seguir adelante; cambia el estado a una fase de compensación y publica un evento de cancelación o reversión.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
public sealed class PedidoSagaState
{
    public Guid PedidoId { get; set; }
    public SagaStatus Status { get; set; }
    public SagaEtapa Etapa { get; set; }
    public List<string> Processados { get; set; } = [];
    public List<SagaOutboxMessage> Outbox { get; set; } = [];
}

public static class PedidoSagaOrquestrador
{
    public static PedidoSagaState HandlePedidoCriado(PedidoSagaState saga)
    {
        saga.Status = SagaStatus.EmAndamento;
        saga.Etapa = SagaEtapa.AguardandoReserva;
        saga.Outbox.Add(new SagaOutboxMessage
        {
            TipoEvento = "ReservarEstoque",
            CorrelationId = saga.PedidoId.ToString()
        });

        return saga;
    }

    public static PedidoSagaState HandleReservaConfirmada(PedidoSagaState saga)
    {
        saga.Etapa = SagaEtapa.AguardandoPagamento;
        saga.Processados.Add("estoque-reservado");
        return saga;
    }

    public static PedidoSagaState HandlePagamentoRecusado(PedidoSagaState saga)
    {
        saga.Status = SagaStatus.Compensando;
        saga.Etapa = SagaEtapa.Cancelado;
        saga.Outbox.Add(new SagaOutboxMessage
        {
            TipoEvento = "CancelarPedido",
            CorrelationId = saga.PedidoId.ToString()
        });

        return saga;
    }
}

🧠 Observación: el estado de la saga es la fuente de verdad para decidir si avanzo, compenso o continúo con el flujo.

Consejos y Buenas Prácticas

  • Mantén el estado de la saga explícito y observable.
  • Trata la duplicación como regla, no como excepción.
  • La semántica de reintentos y DLQ debe estar documentada.
  • Versiona los contratos y evoluciónalos de forma controlada.
  • Usa sesiones solo cuando el orden por clave de negocio sea importante.
  • No uses eventos para todo. Si la operación es local y síncrona, la complejidad de la mensajería quizá no compense el coste.
  • Define claramente qué es compensable y qué no. No todo fallo tiene un rollback real.
  • Haz que el consumidor sea idempotente antes de pensar en un throughput alto.
  • Monitoriza los correlation IDs y causation IDs desde el inicio, porque eso es lo que hará viable la depuración cuando la cadena de eventos crezca.

Resumen Objetivo

  • Outbox — convierte la publicación en parte de la transacción local y reduce el problema del dual write.
  • Inbox — absorbe la duplicación y hace que el consumidor sea idempotente.
  • Saga — organiza la compensación y los estados de negocio en flujos distribuidos.
  • Azure Service Bus — ofrece tópicos, subscriptions, sesiones y DLQ para flujos asíncronos.
  • PostgreSQL — proporciona una base de datos transaccional para persistir el estado de la aplicación y el outbox.

Lee También

Referencias