System Design
Explica cómo diseñar eventos e integraciones con contratos, ownership, entrega, orden, duplicados, idempotencia, evolución de schemas y recuperación.
La integración asíncrona cambia el problema: ya no basta con enviar un mensaje. Debes diseñar entrega, duplicados, orden, idempotencia, retención, recuperación y observabilidad.
Los eventos y mensajes permiten coordinar sistemas sin mantener una llamada bloqueante. Un productor comunica una intención o un hecho; uno o más consumidores procesan el mensaje según un contrato.
Las llamadas síncronas acoplan disponibilidad y latencia. Si crear un pedido espera inventario, pagos, facturación, notificaciones y analítica, una sola dependencia lenta puede bloquear todo.
La asincronía desacopla tiempos, pero introduce estados intermedios e incertidumbre. No elimina complejidad: la transforma.
Pide que algo ocurra y suele tener un destinatario lógico.
ReserveStock
SendReceiptPuede ser rechazado.
Describe un hecho que ya ocurrió.
OrderConfirmed
PaymentRejectedLos consumidores no deben reinterpretarlo como una orden imperativa escondida.
Es el contenedor transportado. Puede llevar un comando, evento o respuesta.
Distribuye trabajo. Normalmente un mensaje es procesado por un consumidor dentro de un grupo. Es útil para tareas diferidas, emails, generación de archivos y absorción de picos.
Conserva una secuencia durante un periodo. Varios consumidores mantienen su propia posición y pueden releer. Es útil para eventos, telemetría, CDC y proyecciones.
La tecnología concreta puede combinar capacidades, pero el modelo mental debe permanecer claro.
{
"eventId": "evt_123",
"eventType": "OrderConfirmed",
"eventVersion": 2,
"occurredAt": "2026-07-24T15:30:00Z",
"aggregateId": "ord_789",
"aggregateVersion": 7,
"tenantId": "ten_1",
"correlationId": "cor_456",
"causationId": "cmd_321",
"data": {
"branchId": "br_1",
"total": { "amount": "42.00", "currency": "COP" }
}
}eventId permite deduplicar.eventType identifica el hecho.eventVersion permite evolucionar el esquema.aggregateVersion ayuda a detectar orden por entidad.correlationId une un flujo completo.causationId señala qué mensaje produjo este evento.tenantId ayuda al aislamiento, pero no sustituye controles de acceso.El problema clásico es guardar en la base y publicar en el broker como dos operaciones separadas.
guardar pedido ✅
publicar evento ❌El sistema queda inconsistente.
flowchart LR
API[Order API] -->|transaction| DB[(Orders + Outbox)]
Worker[Outbox Worker] -->|poll/CDC| DB
Worker --> Broker[Message Broker]
Broker --> Consumer[Consumers]El outbox reduce la pérdida entre persistencia y publicación, pero el consumidor todavía debe soportar duplicados.
Muchos sistemas garantizan entrega al menos una vez. El mismo mensaje puede llegar varias veces debido a retries, pérdida de acknowledgements o recuperación.
El consumidor debe ser idempotente:
si eventId ya fue procesado
→ no repetir el efecto
→ devolver éxito o registrar duplicado“Exactly once” suele tener un alcance limitado dentro de una plataforma. No elimina efectos externos duplicados como emails o cobros si estos no participan de la garantía.
El orden global limita escalabilidad. Con frecuencia solo se garantiza dentro de una partición.
partition key = orderIdEsto preserva orden para un pedido, pero no entre todos los pedidos.
Aun con partición, pueden aparecer retries o productores múltiples. Usa versión y reglas de transición para rechazar eventos antiguos.
Consumidores de un mismo grupo comparten trabajo. Grupos distintos reciben la secuencia independientemente.
OrderConfirmed
├─ grupo notifications
├─ grupo analytics
└─ grupo fulfillmentCada grupo tiene su propio lag y estrategia de error.
El ack indica que el mensaje puede considerarse procesado. Debe enviarse después de completar el efecto durable necesario.
Retries requieren:
Reintentar inmediatamente un error permanente solo genera carga.
Una DLQ conserva mensajes que no pueden procesarse después de varios intentos. No es un cementerio automático.
Debe existir:
Cuando la producción supera el consumo, crece el lag.
Opciones:
La métrica importante no es solo mensajes por segundo, sino cuánto tarda un mensaje relevante en completarse.
Un evento puede actualizar una proyección después de unos segundos. La interfaz debe decidir si:
No prometas consistencia inmediata sobre una proyección eventual.
Una operación distribuida puede coordinar pasos y compensaciones:
crear pedido
→ reservar stock
→ cobrar
→ confirmarSi cobrar falla, se libera la reserva. Si confirmar falla después del cobro, puede requerirse reembolso o reconciliación.
Un coordinador conoce el flujo y envía comandos.
Cada servicio reacciona a eventos. Reduce coordinador central, pero puede ocultar el flujo y crear dependencias difíciles de rastrear.
La elección depende de complejidad, visibilidad y ownership.
Los eventos publicados se convierten en contratos. Cambios aditivos suelen ser más seguros. Para cambios incompatibles:
Un evento de dominio puede contener detalles internos y existir dentro de una transacción local. Un evento de integración es un contrato estable para otros sistemas y puede necesitar transformación, minimización y versionado independiente.
No publiques automáticamente todos los eventos internos.
tenantId sin autorización.El mensaje reaparece; la idempotencia evita repetir el efecto.
El sistema puede recibir una aprobación después de marcar timeout. Se necesita correlación y reconciliación.
Compara versión y estado actual antes de aplicar.
Usa payload compacto y referencia a almacenamiento cuando sea apropiado, considerando expiración y autorización.
Un dato inválido bloquea continuamente. Clasifica, envía a DLQ y alerta.
Los consumidores deben distinguir reconstrucción de efectos externos; no deben reenviar emails o cobros durante un replay de proyección.
Una llamada local o síncrona puede ser mejor cuando el resultado debe conocerse inmediatamente, el flujo es simple, los componentes comparten disponibilidad y la asincronía solo añadiría estados y operación sin beneficio.
Diagramas de componentes hace visibles módulos internos, interfaces y dependencias que implementan estas capacidades.