Transaktionale Mutations in GraphQL: Konsistenz über mehrere Schritte

1. Warum eine Mutation selten wirklich atomar ist

Aus Sicht des Clients ist eine GraphQL-Mutation ein einzelner Aufruf mit einer einzigen Antwort, entweder Erfolg oder Fehler. Innerhalb des Servers verbirgt sich hinter placeOrder aber oft eine Kette von Einzelschritten: Bestellung anlegen, Zahlung autorisieren, Lagerbestand reservieren, Versandauftrag erstellen, Bestätigungs-Event auslösen. Transaktionale Mutations in GraphQL müssen sicherstellen, dass diese Kette entweder vollständig oder gar nicht wirkt, sonst entstehen Bestellungen ohne Zahlung oder Zahlungen ohne Bestellung.

Das Problem verschärft sich, sobald die einzelnen Schritte über mehrere Datenbanken oder sogar mehrere Services verteilt sind, wie es in einer Microservices-Architektur der Normalfall ist. Eine klassische Datenbanktransaktion mit BEGIN und COMMIT funktioniert nur, solange alle Schritte dieselbe Datenbank betreffen. Sobald ein Zahlungsdienstleister oder ein separater Versand-Service beteiligt ist, braucht es andere Mechanismen, um transaktionale Mutations in GraphQL konsistent zu halten.

2. Unit of Work: Konsistenz innerhalb eines Resolvers

Solange alle beteiligten Schreiboperationen dieselbe Datenbank betreffen, ist das Unit-of-Work-Pattern der direkteste Weg zu konsistenten transaktionalen Mutations in GraphQL. Der Resolver öffnet zu Beginn eine Datenbanktransaktion, sammelt alle Änderungen, und committet sie erst am Ende gemeinsam. Schlägt irgendein Schritt fehl, wird die gesamte Transaktion zurückgerollt, keine Teiländerung bleibt sichtbar.

Wichtig ist, diese Transaktionsgrenze bewusst zu ziehen: Sie sollte exakt den Resolver umschließen, der die fachliche Operation repräsentiert, nicht mehr und nicht weniger. Ein zu weit gefasster Transaktionsrahmen, der versehentlich auch unabhängige Lesevorgänge oder externe HTTP-Aufrufe einschließt, hält Datenbankverbindungen unnötig lange offen und erhöht das Risiko von Lock-Contention unter Last.

<?php

declare(strict_types=1);

namespace App\GraphQL\Mutation;

use App\Domain\Order\OrderRepository;
use App\Domain\Inventory\InventoryRepository;
use App\Infrastructure\Database\ConnectionInterface;
use Throwable;

/**
 * Places an order and reserves stock within a single unit of work.
 * Both writes commit together or roll back together.
 */
final class PlaceOrderMutation
{
    public function __construct(
        private readonly ConnectionInterface $connection,
        private readonly OrderRepository $orders,
        private readonly InventoryRepository $inventory,
    ) {
    }

    /**
     * Executes the order placement as a single atomic unit of work.
     *
     * @param array{sku: string, quantity: int, customerId: string} $input
     * @return array{orderId: string, status: string}
     * @throws Throwable Re-thrown after rollback, formatted upstream
     */
    public function execute(array $input): array
    {
        $this->connection->beginTransaction();

        try {
            $this->inventory->reserve($input['sku'], $input['quantity']);
            $order = $this->orders->create($input['customerId'], $input['sku'], $input['quantity']);

            $this->connection->commit();

            return ['orderId' => $order->id, 'status' => 'PLACED'];
        } catch (Throwable $exception) {
            $this->connection->rollBack();
            throw $exception;
        }
    }
}

3. Idempotency Keys gegen doppelte Ausführung

Netzwerkfehler, Timeouts und Client-Retries sind der zweite große Feind konsistenter transaktionaler Mutations in GraphQL. Schlägt eine Antwort auf eine erfolgreich verarbeitete Mutation aufgrund eines Netzwerkfehlers fehl, weiß der Client nicht, ob die Operation durchgeführt wurde. Ein automatischer Retry kann dieselbe Bestellung ein zweites Mal auslösen, mit doppelter Zahlung und doppeltem Lagerabzug als Folge.

Die Standardlösung ist ein vom Client generierter Idempotency Key, üblicherweise eine UUID, die als Input-Argument der Mutation mitgegeben wird. Der Server speichert für jeden verarbeiteten Key das Ergebnis der Operation. Trifft derselbe Key erneut ein, wird die Operation nicht erneut ausgeführt, sondern das gespeicherte Ergebnis der ersten Ausführung direkt zurückgegeben. Dieses Muster macht Mutations sicher wiederholbar, ohne dass Clients komplizierte Deduplizierungslogik selbst implementieren müssen.

# Idempotency key is a required input, not an optional extra -
# forces clients to think about retry safety from the start
input PlaceOrderInput {
  idempotencyKey: ID!
  sku: String!
  quantity: Int!
  customerId: ID!
}

type PlaceOrderPayload {
  orderId: ID!
  status: OrderStatus!
  wasReplayed: Boolean!
}

type Mutation {
  placeOrder(input: PlaceOrderInput!): PlaceOrderPayload!
}

<?php

declare(strict_types=1);

namespace App\GraphQL\Mutation;

/**
 * Wraps a mutation handler with idempotency key deduplication,
 * so a retried request never re-executes the underlying operation.
 */
final class IdempotentMutationWrapper
{
    public function __construct(
        private readonly IdempotencyKeyStore $store,
    ) {
    }

    /**
     * Executes the callback only if the key was not seen before,
     * otherwise returns the stored result of the first execution.
     *
     * @param string $key Client-supplied idempotency key
     * @param callable $operation The mutation logic to guard
     * @return array Result of either the fresh or the replayed execution
     */
    public function execute(string $key, callable $operation): array
    {
        $stored = $this->store->find($key);

        if ($stored !== null) {
            return [...$stored, 'wasReplayed' => true];
        }

        $result = $operation();
        $this->store->save($key, $result);

        return [...$result, 'wasReplayed' => false];
    }
}

4. Das Saga-Pattern für verteilte Transaktionen

Sobald eine Mutation Services überspannt, die jeweils ihre eigene Datenbank besitzen, greift keine klassische Transaktion mehr. Das Saga-Pattern löst dieses Problem, indem es die Operation in eine Kette lokaler Transaktionen zerlegt, jede in genau einem Service, verbunden durch Events oder direkte Aufrufe. Jeder Schritt der Saga hat einen definierten Kompensationsschritt, der ausgeführt wird, falls ein späterer Schritt fehlschlägt.

Bei transaktionalen Mutations in GraphQL mit Saga-Pattern gibt der Resolver die Saga nur an, wartet aber nicht zwingend auf deren vollständigen Abschluss. Stattdessen liefert die Mutation einen Zwischenstatus zurück, etwa PROCESSING, und der Client erfährt den endgültigen Status über ein Subscription-Feld oder einen nachfolgenden Query. Diese asynchrone Natur unterscheidet sich fundamental vom Unit-of-Work-Ansatz, bei dem die Antwort erst nach vollständigem Abschluss zurückkommt.

# Saga-based mutation: returns immediately with a processing status,
# final outcome arrives asynchronously via subscription
type Mutation {
  placeOrder(input: PlaceOrderInput!): PlaceOrderPayload!
}

type Subscription {
  orderSagaStatus(orderId: ID!): OrderSagaStatus!
}

type OrderSagaStatus {
  orderId: ID!
  step: SagaStep!
  status: SagaStepStatus!
}

enum SagaStep {
  ORDER_CREATED
  PAYMENT_AUTHORIZED
  STOCK_RESERVED
  SHIPMENT_SCHEDULED
}

5. Kompensationsschritte statt klassischem Rollback

Der entscheidende konzeptionelle Unterschied zwischen einer klassischen Transaktion und einer Saga: Es gibt kein technisches Rollback, das den vorherigen Zustand exakt wiederherstellt. Stattdessen definiert jeder Schritt eine eigene, fachliche Kompensationsaktion. Wurde ein Lagerbestand reserviert, ist die Kompensation eine Freigabe der Reservierung, keine technische Undo-Operation. Wurde eine Zahlung autorisiert, ist die Kompensation eine Stornierung der Autorisierung.

Diese Kompensationsschritte müssen selbst wieder idempotent sein, denn Saga-Orchestratoren können nach einem Ausfall Kompensationen doppelt auslösen. Ein zweites Freigeben einer bereits freigegebenen Reservierung darf keinen Fehler produzieren, sondern muss als No-Op behandelt werden. Wer transaktionale Mutations in GraphQL mit Sagas umsetzt, entwirft deshalb jeden Kompensationsschritt von Anfang an als sicher wiederholbare Operation, genau wie die ursprüngliche Aktion selbst.

6. Orchestrierung vs. Choreografie in GraphQL-Mutations

Sagas lassen sich auf zwei Arten koordinieren: orchestriert, mit einem zentralen Prozess, der jeden Schritt explizit anstößt und den Fortschritt trackt, oder choreografiert, bei der jeder Service auf Events reagiert und selbstständig den nächsten Schritt auslöst, ohne zentrale Steuerung. Für transaktionale Mutations in GraphQL, die von einem einzelnen Mutation-Resolver angestoßen werden, ist Orchestrierung meist die verständlichere Wahl, weil der GraphQL-Layer ohnehin schon der natürliche Einstiegspunkt für die gesamte Operation ist.

Choreografie skaliert besser bei sehr vielen beteiligten Services, weil kein zentraler Orchestrator zum Single Point of Failure wird, erschwert aber das Debugging erheblich: Der Ablauf einer Saga ergibt sich implizit aus verteilten Event-Handlern statt aus einem einzigen, lesbaren Ablaufplan. Für die meisten produktiven E-Commerce-Systeme mit drei bis sechs beteiligten Services ist ein expliziter Orchestrator die pragmatischere und wartbarere Wahl.

7. Fehlerzustände sichtbar machen: partieller Erfolg im Response

Eine Mutation, die intern mehrere Schritte umfasst, darf niemals ein binäres Erfolg-oder-Fehler-Signal liefern, wenn in Wahrheit ein Zwischenzustand vorliegt. Wurde die Bestellung angelegt, aber die Zahlungsautorisierung ist noch ausstehend, muss der Response genau das ausdrücken, etwa über ein status-Feld mit dem Wert PAYMENT_PENDING, statt einen generischen Fehler zurückzugeben, der den erfolgreichen ersten Schritt verschweigt.

Dieses Prinzip bei transaktionalen Mutations in GraphQL verlangt, dass der Payload-Typ jeder Mutation von Anfang an mit mehreren möglichen Zwischenzuständen entworfen wird, nicht nachträglich als Erweiterung. Ein Union-Type aus OrderPlaced, PaymentPending und OrderFailed zwingt Clients, jeden dieser Zustände explizit zu behandeln, statt sich fälschlich auf einen einzelnen Erfolgsfall zu verlassen.

8. Transaktionale Mutations testen: Fehlerpfade provozieren

Der übliche Testfokus auf den Erfolgsfall reicht bei mehrstufigen Mutations nicht aus. Entscheidend ist, gezielt jeden einzelnen Schritt der Kette künstlich fehlschlagen zu lassen und zu prüfen, ob die vorherigen Schritte korrekt zurückgerollt oder kompensiert werden. Bei Unit of Work bedeutet das, Integrationstests zu schreiben, die den zweiten oder dritten Schritt einer Transaktion gezielt eine Exception werfen lassen und danach den Datenbankzustand prüfen.

Bei Sagas ist der Testaufwand höher, weil Fehler an jedem Schritt und in jeder Kompensation isoliert simuliert werden müssen, inklusive doppelt ausgelöster Kompensationen zur Prüfung der Idempotenz. Ein dediziertes Chaos-Testing, das zufällige Service-Ausfälle während einer laufenden Saga simuliert, deckt Lücken in der Kompensationslogik auf, die reine Unit-Tests praktisch nie finden. Wer transaktionale Mutations in GraphQL produktiv betreibt, sollte solche Tests fest im CI-Prozess verankern.

9. Konsistenzstrategien im direkten Vergleich

Welche Strategie passt, hängt maßgeblich davon ab, ob alle Schritte dieselbe Datenbank betreffen oder über Services verteilt sind.

In der Praxis kombiniert man diese Strategien oft: Unit of Work innerhalb eines Services für lokale Konsistenz, Idempotency Keys an jeder öffentlichen Mutation, und eine orchestrierte Saga für alles, was über Servicegrenzen hinausgeht. Diese Kombination deckt die meisten produktiven E-Commerce-Szenarien ab, ohne die Komplexität einer vollständig choreografierten Architektur einzugehen.

10. Zusammenfassung

Transaktionale Mutations in GraphQL brauchen unterschiedliche Absicherungsmechanismen, je nachdem, ob alle Schritte dieselbe Datenbank betreffen oder über Services verteilt sind. Unit of Work löst das Problem lokal mit klassischen Datenbanktransaktionen. Idempotency Keys schützen jede Mutation gegen doppelte Ausführung durch Retries, unabhängig von der gewählten Konsistenzstrategie. Das Saga-Pattern koordiniert verteilte Schritte über Kompensationsaktionen statt technischem Rollback.

Entscheidend ist, dass jeder Kompensationsschritt selbst idempotent ist und dass der GraphQL-Response-Typ mehrere mögliche Zwischenzustände explizit modelliert, statt binär Erfolg oder Fehler zu signalisieren. Wer diese drei Elemente kombiniert, kann komplexe, mehrstufige Geschäftsvorgänge über GraphQL abbilden, ohne stille Dateninkonsistenzen bei Teilausfällen zu riskieren.

11. FAQ: Transaktionale Mutations in GraphQL