GraphQL-Mutations: Syntax, Variablen und Input-Typen | We.Inc
Schreib GraphQL-Mutations, die Daten anlegen, ändern und löschen: Operationssyntax, $variables, Input-Objekttypen, was du zurückgibst und wie Fehler und Teilerfolge aussehen.
Eine GraphQL-Mutation ist die Operation, die du sendest, um Daten zu ändern. Sie beginnt mit dem Schlüsselwort mutation, ruft ein Feld des Mutation-Typs im Schema auf, übergibt Argumente, meist ein einzelnes Input-Objekt in einer $variable, und wählt aus, welche Felder des Ergebnisses zurückkommen sollen. Mutation-Felder auf oberster Ebene laufen nacheinander, nie parallel.
Mutation-Syntax in Einzelteilen
Teil
Beispiel
Was er tut
Schlüsselwort und Name
mutation AddTask
Kennzeichnet die Operation als Schreibvorgang und benennt sie für Logs
Variablendefinitionen
($input: TaskInput!)
Deklariert typisierte Werte, die separat als JSON gesendet werden
Root-Feld
addTask(input: $input)
Ein Feld, das im Mutation-Typ definiert ist
Selection Set
{ id title done }
Felder des Ergebnisses, die zurückgeschickt werden
Variablen-JSON
{"input": {...}}
Die eigentlichen Werte, außerhalb des Query-Strings
Mit dem Builder unten siehst du eine vollständige Mutation für eine kleine Aufgabenliste: die Operation, das Variablen-JSON, das dein Code mitsenden würde, und eine typische Antwort. Gib einen Aufgabentitel ein und beobachte, wie sich die Variablen aktualisieren. So kannst du eine Anfrage kopieren, die gegen ein passendes Schema sofort lauffähig ist.
Wähle Anlegen, Ändern oder Löschen.
Gib einen Titel für die Aufgabe ein; das Variablen-JSON aktualisiert sich beim Tippen.
Kopiere Mutation und Variablen und sende sie als Schlüssel query und variables in einem einzigen POST.
Vergleiche die Antwort deines Servers mit der Beispielantwort darunter.
Übergib Werte über Variablen, statt sie in den Query-String einzufügen. Das vermeidet Escaping-Fehler und erlaubt Servern, das geparste Dokument zu cachen.
Gib das geänderte Objekt samt id zurück, damit Client-Caches die Ansicht ohne zweite Anfrage aktualisieren können.
Benenne jede Operation. Benannte Mutations findest du in Server-Logs und Fehlerberichten viel leichter.
Behandle mehrere Root-Felder in einer Mutation als getrennte Schritte, nicht als Transaktion: Ein früheres Feld bleibt erledigt, wenn ein späteres fehlschlägt.
Häufige Fragen
Was ist der Unterschied zwischen einer Query und einer Mutation?
Beide nutzen dieselbe Syntax und beide können Daten zurückgeben. Per Konvention lesen Queries nur, und Mutations schreiben. Auch die Ausführungsregel unterscheidet sich: Query-Felder dürfen parallel aufgelöst werden, während Mutation-Felder auf oberster Ebene nacheinander laufen.
Warum einen Input-Typ statt einfacher Argumente verwenden?
Ein Input-Objekt bündelt zusammengehörige Werte in einem typisierten Argument. So bleibt die Signatur der Mutation kurz, und du kannst später optionale Felder ergänzen, ohne jeden Aufrufer zu ändern.
Kann ich eine Mutation per GET-Request senden?
Nein. Die Vorgaben zu GraphQL over HTTP erlauben Servern GET nur für Query-Operationen. Mutations gehen als POST, was Schreibvorgänge außerdem von Browser- und CDN-Caches fernhält.
Ist eine Mutation mit mehreren Feldern atomar?
Nein. graphql.org weist darauf hin, dass serielle Ausführung keine Datenbanktransaktion ist. Schlägt das zweite Feld fehl, bleibt die Änderung des ersten bestehen, und die Antwort enthält Daten für das eine und einen Fehler für das andere.
Was sollte eine Delete-Mutation zurückgeben?
Die Spezifikation überlässt das dir, aber das Feld braucht trotzdem einen Ausgabetyp. Üblich sind die id des gelöschten Objekts, das entfernte Objekt selbst oder ein Payload-Typ mit der id und einem Erfolgs-Flag.
Aufbau einer Mutation
Auf dem Server deklariert das Schema einen Mutation-Typ, dessen Felder die Schreibvorgänge sind, die Clients aufrufen dürfen, jeweils mit Argumenten und Rückgabetyp. Auf dem Client nennt die Operation eines oder mehrere dieser Felder, übergibt Argumente und wählt die Ergebnisfelder aus, die zurückkommen sollen.
Gibt das Feld einen Objekttyp zurück, ist ein Selection Set Pflicht, genau wie bei einer Query. Fragst du nach der neuen id und allen Feldern, die die Ansicht zeigt, kann der Client seine Anzeige direkt aus der Antwort aktualisieren.
Variablen und Input-Objekte
Variablen werden nach dem Operationsnamen mit einem Dollarzeichen und einem Typ deklariert, etwa $input: TaskInput!. Das Ausrufezeichen macht die Variable zur Pflicht. Die Werte reisen in einem separaten variables-Objekt im Request-Body.
Ein Input-Objekttyp wird mit dem Schlüsselwort input statt type deklariert. Seine Felder dürfen nur Skalare, Enums, Listen oder andere Input-Typen sein, wodurch sich die Form dessen, was Clients senden, einfach validieren lässt.
Fehler bei einem Schreibvorgang
Ist das Dokument ungültig, etwa durch ein falsch geschriebenes Feld oder eine fehlende Pflichtvariable, antwortet der Server mit errors und ohne data, und nichts wird geschrieben.
Schlägt der Schreibvorgang selbst während der Ausführung fehl, kommt das Feld als null zurück, und ein Eintrag in errors enthält eine Meldung und einen Pfad. Viele Schemas geben erwartbare Probleme, etwa einen zu langen Titel, zusätzlich als Felder eines Payload-Typs zurück, damit der Client sie neben dem Formular anzeigen kann.
Das Schema hinter den Beispielen
Mutation-Typ und Input-Typen
Input-Typen nutzen das Schlüsselwort input. TaskPatch hat keine Pflichtfelder, ein Update kann also nur das senden, was sich geändert hat.
Aus JavaScript senden
Die Mutation mit fetch per POST senden
Dokument und Variablen reisen als zwei Schlüssel eines einzigen JSON-Bodys. Prüfe errors auch dann, wenn der Status 200 ist.
Zwei Schreibvorgänge in einer Operation
Mit Aliasen lässt sich dasselbe Feld zweimal ausführen. Das zweite läuft erst, wenn das erste fertig ist, aber ein Fehler darin macht das erste nicht rückgängig.
Anlegen
Der Input-Typ bündelt die Felder der neuen Aufgabe. Das Selection Set fragt nach der id, die der Server vergeben hat.
Ändern
Die id gibt an, welche Aufgabe geändert wird, und der Input enthält nur die Felder, die sich ändern.
Löschen
Bei einer entfernten Aufgabe gibt es nichts mehr auszuwählen, daher gibt dieses Schema die gelöschte id als einfachen ID-Skalar zurück.
Mutation-Builder
Mutation auswählen
Aufgabentitel
Mutation
Variablen (JSON)
Beispielantwort
Mutation kopieren
Variablen kopieren
Löschen braucht nur die id, daher wird der Titel nicht gesendet.