Transactional Outbox: Seiteneffekte beim Fachschreiben
KURZ GESAGT: Datenbank schreiben und danach E-Mail-API, Webhook oder ERP aufrufen ist ein Doppel-Schreiben: Jeder Schritt kann allein gelingen. Legen Sie die Outbox-Zeile in dieselbe Transaktion wie die Fachänderung. Ein separates Relay liest committete Zeilen und liefert at-least-once; Empfänger müssen idempotent sein.
1.0 Das Doppel-Schreib-Problem
Ein Handler, der eine Bestellung speichert und danach eine Bestätigungsmail schickt, schreibt in zwei Systeme: die Datenbank und den Mail-Anbieter. Dieselbe Form zeigt sich beim Push eines Belegs ins ERP oder beim Webhook an einen Partner.
Wenn die Datenbank committed und der Netzwerkaufruf scheitert, ist der Fachzustand wahr und niemand wurde benachrichtigt. Wenn Sie zuerst benachrichtigen und der Commit scheitert, hat die Gegenseite auf etwas reagiert, das nie existierte. Ein Two-Phase-Commit über Datenbank und Mail-API ist selten verfügbar und meist unerwünscht. Das ist das Doppel-Schreib-Problem, das das Pattern der transactional Outbox angeht (siehe Chris Richardsons Pattern-Text und die Seite der AWS Prescriptive Guidance in den Quellen).
2.0 Was in eine Transaktion gehört
| Schreibvorgang | Dieselbe Transaktion wie die Fachänderung? |
|---|---|
| Fachzeile (Auftrag, Zahlung, Ticket, …) | Ja |
| Outbox-Zeile (type, message id, payload, status) | Ja |
| E-Mail- / Webhook- / ERP-HTTP-Aufruf | Nein — nach dem Commit, über das Relay |
Outbox-Zeile als published markieren / löschen | Nach erfolgreichem Relay-Versuch (oder per Log-Tailing-Cleanup) |
Die Outbox-Zeile ist kein Protokoll dessen, was schon auf der Leitung passiert ist. Sie ist die dauerhafte Absicht, einen Seiteneffekt auszuführen, und wird nur geschrieben, wenn der Fachschreibvorgang committed.
3.0 Relay: pollen oder das Log tailen
Ein eigener Prozess (oder Worker im selben Dienst) bringt committete Outbox-Zeilen in die Außenwelt.
| Ansatz | Wie er Arbeit findet | Typischer Trade-off |
|---|---|---|
| Polling-Publisher | SELECT offener Zeilen nach id oder created_at | Einfach; läuft auf gewöhnlichem SQL; Lag und Last wachsen mit Poll-Intervall und Tabellengröße |
| Transaction-Log-Tailing | Inserts aus dem DB-Log lesen (WAL, Binlog, Streams) | Weniger Lag; braucht DB-spezifische Werkzeuge; weiterhin at-least-once |
microservices.io beschreibt beide als Begleiter der Outbox. Bleiben Sie beim Polling, bis Volumen oder Latenz Log-Tailing rechtfertigen. In jedem Fall ist Publish at-least-once: Ein Absturz zwischen „Senden gelungen“ und „Zeile als erledigt markiert“ sendet erneut.
4.0 Zeilenform, die wir stabil halten
Halten Sie genug Spalten, damit der Betrieb „was hängt?“ beantworten kann, ohne Anwendungsspeicher zu lesen:
- id — monoton oder ULID; für Ordnung und Relay-Checkpoints.
- message_id / Idempotency-Key — stabil für diesen logischen Seiteneffekt; Empfänger deduplizieren danach.
- type — welcher Relay-Handler läuft (
email.order_paid,erp.order_push, …). - aggregate_key — Auftrags-ID, Lead-ID, Geräte-ID; für Ordnung und Support-Abfragen.
- payload — versioniertes JSON, das der Handler braucht; keine Secrets hinein.
- status —
pending→publishing(optionaler Lease) →published/failed_terminal. - attempts, next_attempt_at, last_error — für Backoff und Alarme.
- created_at — optional dazu
published_at.
Beanspruchen Sie eine Zeile mit einem atomaren Update (pending → publishing mit Owner und Lease-Ablauf), damit zwei Relay-Worker nicht dieselbe Mail schicken. Bei Erfolg published setzen (oder löschen, wenn die Tabelle klein bleiben soll und Backups fürs Audit reichen). Bei wiederholbarem Fehler attempts erhöhen und next_attempt_at setzen. Nach einem konfigurierten Limit nach failed_terminal und einen Menschen alarmieren.
5.0 Reihenfolge und Duplikate
Für ein einzelnes Aggregat in der Reihenfolge der vergebenen Outbox-IDs (oder Sequenznummern) publishen, damit ein Partner nicht „versandt“ vor „angelegt“ sieht. Über Aggregate hinweg sind parallele Worker in Ordnung.
Duplikate sind erwartet. Lesen Sie diese Notiz zusammen mit Webhook-Idempotenz und Retries: Keys, Fristen, Seiteneffekte: Die Outbox garantiert, dass der Seiteneffekt nach erfolgreichem Fachschreibvorgang versucht wird; der Dedup-Speicher des Empfängers garantiert, dass er einmal angewendet wird. ERP-Pushes brauchen dieselbe Disziplin auf der Gegenseite — einen stabilen Fachschlüssel auf dem Beleg, wie in Aufträge an ein ERP anbinden: manuelle Prüfung, idempotente Übertragung und Sync-Log.
6.0 Was nicht auf den Request-Pfad gehört
- Keine DB-Transaktion öffnen, eine fremde HTTP-API aufrufen und dann committen. Timeouts und Sperren machen Fehlermodi schwer nachvollziehbar.
- Kein Fire-and-Forget einer Goroutine oder eines Queue-Publishes ohne dauerhafte Outbox (oder Entsprechung), wenn der Verlust dieses Seiteneffekts bei einem Absturz unannehmbar ist.
- „HTTP 200 von der Mail-API“ nicht als System of Record für „Kunde wurde benachrichtigt“ behandeln, solange dieses Ergebnis nicht auch persistiert ist. Besser: Outbox published und Provider-Message-ID auf der Zeile gespeichert.
7.0 Beobachtbarkeit
- Metriken: Alter von pending (p50/p95), Publish-Erfolgs-/Fehlerraten, terminale Fehler, Relay-Lag.
- Alarme: älteste
pending/publishingüber Schwelle; Spike terminaler Fehler nach einem Deploy. - Support: nach
aggregate_keysuchen und Outbox-Status neben dem Fachdatensatz zeigen.
Wenn Sie Seiteneffekte für Zahlungen, ERP oder Geräte-Clouds verdrahten, siehe Web, Cloud und Geräteverwaltung, oder Projekt besprechen.
Quellen
- 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
Häufige Fragen
Ist eine Outbox dasselbe wie eine Message-Queue?
Die Outbox ist eine Tabelle (oder ein Dokumentfeld) in derselben Datenbank wie der Fachschreibvorgang, damit beide gemeinsam committen oder zurückrollen. Queue oder Broker sitzen hinter dem Relay. Die Outbox stellt sicher, dass das Publish nicht ohne den Fachschreibvorgang gelingt — und umgekehrt.
Brauchen wir auf der Empfängerseite trotzdem Idempotenz?
Unbedingt. Das Relay kann mehrfach publishen: Es kann nach erfolgreichem Senden und vor dem Markieren der Zeile abstürzen. Konsumenten müssen Zustellung als at-least-once behandeln, etwa mit dem Idempotency-Key und Fenster aus unserer Webhook-Notiz.
Dürfen wir die E-Mail-API innerhalb der Datenbanktransaktion aufrufen?
Besser nicht. Eine offene DB-Transaktion während eines Netzwerkaufrufs hält Sperren länger, und ein Timeout lässt offen, ob die Mail rausging. Outbox-Zeile schreiben, committen, dann das Relay die Netzwerkarbeit machen lassen.
Polling der Outbox-Tabelle wirkt verschwenderisch. Gibt es eine Alternative?
Polling läuft auf jeder SQL-Datenbank und reicht meist bei moderatem Volumen. Wo die Datenbank es hergibt, senkt Transaction-Log-Tailing (etwa WAL oder Binlog auf Outbox-Inserts) Latenz und Last. Beide liefern weiterhin at-least-once.
Was gehört in die Outbox-Payload?
Genug, damit das Relay ohne Neuableitung der Absicht handeln kann: Typ, stabile Idempotenz- oder Message-ID, Fachschlüssel und die Felder für den Downstream-Aufruf. Lieber ein versioniertes Schema als ein undurchsichtiger Dump des ganzen Aggregats, damit alte Zeilen nach Codeänderungen lesbar bleiben.