Outbox transactionnelle : effets avec l'écriture métier

EN BREF : Écrire en base puis appeler une API e-mail, un webhook ou un ERP, c’est une double écriture : chaque étape peut réussir seule. Placez la ligne outbox dans la même transaction que le changement métier. Un relais distinct lit les lignes validées et livre au moins une fois ; les récepteurs doivent être idempotents.

Schéma de l'outbox transactionnelle : un gestionnaire de requête écrit la ligne métier et la ligne outbox dans une seule transaction de base ; après validation, un relais interroge ou suit le journal de l'outbox et livre e-mail, webhook ou envois ERP au moins une fois ; les récepteurs appliquent une porte d'idempotence. Une note en bas met en garde contre un commit de l'écriture métier puis un appel réseau sans outbox durable.
Figure 1. Écriture métier et ligne outbox dans une seule transaction ; le relais assure la livraison après validation.

1.0 Le problème de la double écriture

Un gestionnaire qui enregistre une commande puis envoie un e-mail de confirmation écrit dans deux systèmes : la base de données et le fournisseur de messagerie. La même forme apparaît quand on pousse un document vers un ERP ou qu’on émet un webhook vers un partenaire.

Si la base valide et que l’appel réseau échoue, l’état métier est vrai et personne n’a été notifié. Si l’on notifie d’abord et que la validation échoue, l’autre côté a agi sur quelque chose qui n’a jamais existé. Un commit en deux phases entre la base et l’API mail est rarement disponible et souvent indésirable. C’est le problème de double écriture que le motif d’outbox transactionnelle traite (voir le texte de Chris Richardson et la page AWS Prescriptive Guidance en références).

2.0 Ce qui entre dans une seule transaction

ÉcritureMême transaction que le changement métier ?
Ligne métier (commande, paiement, ticket, …)Oui
Ligne outbox (type, message id, payload, status)Oui
Appel HTTP e-mail / webhook / ERPNon — après validation, via le relais
Marquer la ligne outbox published / la supprimerAprès une tentative de relais réussie (ou nettoyage par suivi de journal)

La ligne outbox n’est pas un journal de ce qui s’est déjà passé sur le fil. C’est l’intention durable d’exécuter un effet de bord, enregistrée seulement si l’écriture métier est validée.

3.0 Relais : polling ou suivi du journal

Un processus distinct (ou un worker dans le même service) fait passer les lignes outbox validées vers le monde extérieur.

ApprocheComment elle trouve du travailCompromis typique
Éditeur par pollingSELECT des lignes en attente ordonnées par id ou created_atSimple ; marche sur du SQL ordinaire ; latence et charge croissent avec l’intervalle et la taille de table
Suivi du journal de transactionsLire les insertions dans le journal BD (WAL, binlog, streams)Moins de latence ; outillage propre à la BD ; toujours au moins une fois

microservices.io documente les deux comme compagnons de l’outbox. Restez au polling jusqu’à ce que le volume ou la latence force l’investissement dans le suivi de journal. Dans tous les cas, traitez le publish comme au moins une fois : un plantage entre « envoi réussi » et « ligne marquée terminée » renverra.

4.0 Forme de ligne que nous gardons stable

Gardez assez de colonnes pour que l’exploitation réponde à « qu’est-ce qui bloque ? » sans lire la mémoire de l’application :

  • id — monotone ou ULID ; pour l’ordre et les points de contrôle du relais.
  • message_id / clé d’idempotence — stable pour cet effet de bord logique ; les récepteurs dédoublonnent dessus.
  • type — quel gestionnaire de relais s’exécute (email.order_paid, erp.order_push, …).
  • aggregate_key — id de commande, de lead, d’appareil ; pour l’ordre et le support.
  • payload — JSON versionné dont le gestionnaire a besoin ; pas de secrets.
  • status — pending → publishing (bail optionnel) → published / failed_terminal.
  • attempts, next_attempt_at, last_error — pour le backoff et les alertes.
  • created_at — et optionnellement published_at.

Réclamez une ligne par une mise à jour atomique (pending → publishing avec propriétaire et échéance de bail) pour que deux workers de relais n’envoient pas le même mail. En cas de succès, marquez published (ou supprimez, si vous préférez une petite table et vous fiez aux sauvegardes pour l’audit). En échec rejouable, incrémenter attempts et fixer next_attempt_at. Après une limite configurée, passez en failed_terminal et alertez une personne.

5.0 Ordre et doublons

Pour un seul agrégat, publiez dans l’ordre d’attribution des id d’outbox (ou numéros de séquence), pour qu’un partenaire ne voie pas « expédié » avant « créé ». Entre agrégats, des workers parallèles conviennent.

Les doublons sont attendus. Lisez cette note avec Webhooks idempotents : clés, relances et effets de bord : l’outbox garantit que l’effet de bord est tenté après une écriture métier réussie ; le magasin de déduplication du récepteur garantit qu’il est appliqué une fois. Les envois ERP demandent la même discipline de l’autre côté — une clé métier stable sur le document, comme dans Intégrer les commandes à un ERP : validation manuelle, envois idempotents et journal de synchronisation.

6.0 Ce qu’il ne faut pas mettre sur le chemin de la requête

  • N’ouvrez pas une transaction BD, n’appelez pas une API HTTP tierce, puis ne validez pas. Timeouts et verrous rendent les modes d’échec difficiles à raisonner.
  • Ne faites pas de fire-and-forget d’une goroutine ou d’un publish vers une file sans outbox durable (ou équivalent) si perdre cet effet de bord en cas de panne est inacceptable.
  • Ne traitez pas « HTTP 200 de l’API mail » comme système d’enregistrement de « le client a été notifié » sans avoir aussi persisté ce résultat. Préférez : outbox published et message id du fournisseur stocké sur la ligne.

7.0 Observabilité

  • Métriques : âge des pending (p50/p95), taux de succès/échec de publish, échecs terminaux, latence du relais.
  • Alertes : plus ancien pending/publishing au-delà d’un seuil ; pic d’échecs terminaux après un déploiement.
  • Support : chercher par aggregate_key et afficher l’état de l’outbox à côté de l’enregistrement métier.

Si vous câblez des effets de bord pour les paiements, l’ERP ou les clouds d’équipements, voir Web, cloud et gestion des équipements, ou parlez-nous de votre projet.

Références

Questions fréquentes

Une outbox, c'est la même chose qu'une file de messages ?

L'outbox est une table (ou un champ de document) dans la même base que l'écriture métier, pour que les deux valident ou annulent ensemble. La file ou le broker se place après le relais. L'outbox existe pour qu'un publish ne puisse pas réussir sans l'écriture métier, et l'inverse.

Faut-il encore de l'idempotence côté récepteur ?

Il en faut toujours. Le relais peut publier plus d'une fois : il peut planter après un envoi réussi et avant de marquer la ligne terminée. Les consommateurs doivent traiter la livraison comme au moins une fois, par exemple avec la clé d'idempotence et la fenêtre de notre note sur les webhooks.

Peut-on appeler l'API e-mail dans la transaction de base de données ?

À éviter. Garder une transaction BD ouverte pendant un appel réseau allonge les verrous, et un timeout laisse dans le doute si le mail est parti. Écrivez la ligne outbox, validez, puis laissez le relais faire le travail réseau.

Interroger la table outbox en boucle paraît gaspilleur. Y a-t-il une autre option ?

Le polling marche sur toute base SQL et suffit en général à volume modéré. Quand la base le permet, le suivi du journal de transactions (lire le WAL ou le binlog pour les insertions outbox, par exemple) réduit latence et charge. Les deux livrent toujours au moins une fois.

Que mettre dans la charge utile (payload) de l'outbox ?

De quoi permettre au relais d'agir sans recalculer l'intention : type, un id d'idempotence ou de message stable, la clé métier, et les champs dont l'appel aval a besoin. Préférez un schéma versionné à un dump opaque de tout l'agrégat, pour que les anciennes lignes restent lisibles après un changement de code.