Outbox transaccional: efectos con la escritura de negocio
EN BREVE: Escribir en la base y luego llamar a correo, webhook o ERP es una escritura dual: cada paso puede tener éxito solo. Ponga la fila outbox en la misma transacción que el cambio de negocio. Un relé lee las filas confirmadas y entrega al menos una vez; los receptores deben ser idempotentes.
1.0 El problema de la escritura dual
Un manejador que guarda un pedido y luego envía un correo de confirmación escribe en dos sistemas: la base de datos y el proveedor de correo. La misma forma aparece al empujar un documento a un ERP o al emitir un webhook a un socio.
Si la base confirma y la llamada de red falla, el estado de negocio es cierto y nadie fue notificado. Si notifica primero y el commit falla, el otro lado actuó sobre algo que nunca existió. Un commit en dos fases entre la base y la API de correo rara vez está disponible y suele ser indeseable. Ese es el problema de escritura dual que aborda el patrón de outbox transaccional (véanse el texto de Chris Richardson y la página de AWS Prescriptive Guidance en las referencias).
2.0 Qué va en una sola transacción
| Escritura | ¿Misma transacción que el cambio de negocio? |
|---|---|
| Fila de negocio (pedido, pago, ticket, …) | Sí |
| Fila outbox (type, message id, payload, status) | Sí |
| Llamada HTTP de correo / webhook / ERP | No — tras el commit, vía el relay |
Marcar la fila outbox como published / borrarla | Tras un intento de relay exitoso (o limpieza por seguimiento de log) |
La fila outbox no es un registro de lo que ya ocurrió en el cable. Es la intención durable de realizar un efecto secundario, anotada solo si la escritura de negocio confirma.
3.0 Relay: polling o seguimiento del log
Un proceso aparte (o un worker en el mismo servicio) lleva las filas outbox confirmadas al mundo exterior.
| Enfoque | Cómo encuentra trabajo | Compromiso típico |
|---|---|---|
| Publicador por polling | SELECT de filas pendientes ordenadas por id o created_at | Simple; funciona en SQL ordinario; el retraso y la carga crecen con el intervalo y el tamaño de la tabla |
| Seguimiento del log de transacciones | Leer inserciones del log de la BD (WAL, binlog, streams) | Menos retraso; necesita herramientas específicas de la BD; sigue siendo at-least-once |
microservices.io documenta ambos como compañeros de la outbox. Quédese con el polling hasta que el volumen o la latencia obliguen a invertir en seguimiento de log. En cualquier caso, trate el publish como at-least-once: un fallo entre «envío correcto» y «fila marcada hecha» enviará otra vez.
4.0 Forma de fila que mantenemos estable
Conserve columnas suficientes para que operaciones responda «¿qué está atascado?» sin leer memoria de la aplicación:
- id — monótono o ULID; para orden y puntos de control del relay.
- message_id / clave de idempotencia — estable para este efecto secundario lógico; los receptores deduplican con ella.
- type — qué manejador de relay corre (
email.order_paid,erp.order_push, …). - aggregate_key — id de pedido, de lead, de dispositivo; para orden y consultas de soporte.
- payload — JSON versionado que necesita el manejador; no meta secretos.
- status —
pending→publishing(lease opcional) →published/failed_terminal. - attempts, next_attempt_at, last_error — para backoff y alertas.
- created_at — y opcionalmente
published_at.
Reclame una fila con una actualización atómica (pending → publishing con dueño y caducidad del lease) para que dos workers de relay no envíen el mismo correo. En éxito, marque published (o borre, si prefiere una tabla pequeña y confía en las copias de seguridad para auditoría). En fallo reintentable, incremente attempts y fije next_attempt_at. Tras un límite configurado, pase a failed_terminal y alerte a una persona.
5.0 Orden y duplicados
Para un solo agregado, publique en el orden en que se asignaron los id de outbox (o números de secuencia), para que un socio no vea «enviado» antes que «creado». Entre agregados, workers en paralelo están bien.
Los duplicados se esperan. Lea esta nota junto con Idempotencia en webhooks: claves, reintentos y efectos: la outbox garantiza que el efecto secundario se intenta tras una escritura de negocio exitosa; el almacén de deduplicación del receptor garantiza que se aplica una vez. Los envíos a ERP necesitan la misma disciplina en el otro lado — una clave de negocio estable en el documento, como en Integrar pedidos con un ERP: revisión manual, envíos idempotentes y log de sincronización.
6.0 Qué no poner en la ruta de la petición
- No abra una transacción de BD, llame a una API HTTP de terceros y luego confirme. Los timeouts y los bloqueos hacen difíciles de razonar los modos de fallo.
- No haga fire-and-forget de una goroutine o un publish a cola sin una outbox durable (o equivalente) si perder ese efecto secundario en un fallo es inaceptable.
- No trate «HTTP 200 de la API de correo» como sistema de registro de «el cliente fue notificado» a menos que también haya persistido ese resultado. Prefiera: outbox publicada y message id del proveedor guardado en la fila.
7.0 Observabilidad
- Métricas: edad de pending (p50/p95), tasas de éxito/fallo de publish, fallos terminales, retraso del relay.
- Alertas: el
pending/publishingmás antiguo por encima del umbral; pico de fallos terminales tras un despliegue. - Soporte: buscar por
aggregate_keyy mostrar el estado de la outbox junto al registro de negocio.
Si está cableando efectos secundarios para pagos, ERP o nubes de dispositivos, consulte Web, nube y gestión de dispositivos o hable de un proyecto con nosotros.
Referencias
- Chris Richardson, Pattern: Transactional outbox: https://microservices.io/patterns/data/transactional-outbox.html
- Chris Richardson, Pattern: Polling publisher: https://microservices.io/patterns/data/polling-publisher.html
- Chris Richardson, Pattern: Transaction log tailing: https://microservices.io/patterns/data/transaction-log-tailing.html
- AWS Prescriptive Guidance, Transactional outbox pattern: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
Preguntas frecuentes
¿Una outbox es lo mismo que una cola de mensajes?
La outbox es una tabla (o campo de documento) en la misma base de datos que la escritura de negocio, de modo que ambas confirman o revierten juntas. La cola o el broker van después del relay. La outbox existe para que el publish no pueda tener éxito sin la escritura de negocio, y al revés.
¿Hace falta idempotencia también en el receptor?
Sigue haciendo falta. El relay puede publicar más de una vez: puede caer tras un envío correcto y antes de marcar la fila como hecha. Los consumidores deben tratar la entrega como at-least-once, por ejemplo con la clave de idempotencia y la ventana de nuestra nota sobre webhooks.
¿Podemos llamar a la API de correo dentro de la transacción de base de datos?
Conviene evitarlo. Mantener abierta una transacción de BD mientras se espera una llamada de red alarga los bloqueos, y un timeout deja duda de si el correo salió. Escriba la fila outbox, confirme y deje al relay el trabajo de red.
Hacer polling de la tabla outbox parece un desperdicio. ¿Hay otra opción?
El polling funciona en cualquier base SQL y suele bastar con volumen moderado. Donde la base lo permita, el seguimiento del log de transacciones (por ejemplo leer WAL o binlog de inserciones outbox) reduce latencia y carga. Ambos siguen entregando al menos una vez.
¿Qué va en el payload de la outbox?
Lo suficiente para que el relay actúe sin volver a derivar la intención: tipo, un id de idempotencia o mensaje estable, la clave de negocio y los campos que necesita la llamada de destino. Prefiera un esquema versionado a un volcado opaco de todo el agregado, para que las filas antiguas sigan siendo legibles tras cambios de código.