Mutation GraphQL: sintassi, variabili e input type | We.Inc
Scrivi mutation GraphQL che creano, aggiornano ed eliminano dati: sintassi dell'operazione, $variables, input object type, cosa restituire e come appaiono errori e successo parziale.
Una mutation GraphQL è l'operazione che invii per modificare i dati. Inizia con la parola chiave mutation, chiama un campo del tipo Mutation dello schema, passa degli argomenti, di solito un unico oggetto input contenuto in una $variable, e seleziona quali campi del risultato restituire. I campi mutation di primo livello vengono eseguiti uno dopo l'altro, mai in parallelo.
La sintassi di una mutation, pezzo per pezzo
Parte
Esempio
Cosa fa
Parola chiave e nome
mutation AddTask
Indica l'operazione come scrittura e le dà un nome per i log
Definizioni delle variabili
($input: TaskInput!)
Dichiara valori tipizzati inviati a parte come JSON
Campo radice
addTask(input: $input)
Un campo definito sul tipo Mutation
Selection set
{ id title done }
Campi del risultato da rimandare indietro
JSON delle variabili
{"input": {...}}
I valori effettivi, tenuti fuori dalla stringa della query
Usa il builder qui sotto per vedere una mutation completa per una piccola lista di attività: l'operazione, il JSON delle variabili che il tuo codice invierebbe insieme e una risposta tipica. Scrivi il titolo di un'attività e guarda le variabili aggiornarsi, così puoi copiare una richiesta pronta da eseguire su uno schema corrispondente.
Scegli creazione, aggiornamento o eliminazione.
Scrivi un titolo per l'attività; il JSON delle variabili si aggiorna mentre scrivi.
Copia la mutation e le variabili, e inviale come chiavi query e variables di un unico POST.
Confronta la risposta del tuo server con la risposta di esempio mostrata sotto.
Invia i valori tramite variabili invece di incollarli nella stringa della query. Eviti bug di escaping e permetti ai server di mettere in cache il documento già analizzato.
Restituisci l'oggetto modificato, compreso il suo id, così le cache dei client possono aggiornare lo schermo senza una seconda richiesta.
Dai un nome a ogni operazione. Le mutation con nome sono molto più facili da trovare nei log del server e nei report di errore.
Tratta più campi radice in una mutation come passaggi separati, non come una transazione: un campo precedente resta eseguito anche quando uno successivo fallisce.
Domande frequenti
Qual è la differenza tra una query e una mutation?
Entrambe usano la stessa sintassi ed entrambe possono restituire dati. Per convenzione le query leggono soltanto e le mutation scrivono. Cambia anche la regola di esecuzione: i campi di una query possono essere risolti in parallelo, mentre i campi mutation di primo livello vengono eseguiti in serie.
Perché usare un input type invece di semplici argomenti?
Un oggetto input raggruppa valori correlati in un unico argomento tipizzato, così la firma della mutation resta corta e puoi aggiungere campi opzionali in seguito senza cambiare ogni chiamante.
Posso inviare una mutation con una richiesta GET?
No. Le linee guida di GraphQL over HTTP consentono ai server di accettare GET solo per le operazioni query. Le mutation vanno inviate come POST, che tiene anche le scritture lontane dalle cache del browser e delle CDN.
Una mutation con più campi è atomica?
No. graphql.org fa notare che l'esecuzione in serie non è una transazione di database. Se il secondo campo fallisce, la modifica del primo resta, e la risposta contiene i dati di uno e un errore per l'altro.
Cosa dovrebbe restituire una mutation di eliminazione?
La specifica lo lascia decidere a te, ma il campo ha comunque bisogno di un tipo di output. Le scelte comuni sono l'id dell'oggetto eliminato, l'oggetto rimosso stesso, oppure un tipo payload con l'id e un flag di successo.
Anatomia di una mutation
Sul server, lo schema dichiara un tipo Mutation i cui campi sono le scritture che i client possono chiamare, ciascuna con argomenti e un tipo di ritorno. Sul client, l'operazione nomina uno o più di quei campi, passa gli argomenti e sceglie i campi del risultato che vuole ricevere.
Se il campo restituisce un tipo oggetto, serve un selection set, proprio come in una query. Chiedere il nuovo id e i campi mostrati a schermo permette al client di aggiornare la vista direttamente dalla risposta.
Variabili e oggetti input
Le variabili si dichiarano dopo il nome dell'operazione con il simbolo del dollaro e un tipo, come $input: TaskInput!. Il punto esclamativo rende la variabile obbligatoria. I valori viaggiano in un oggetto variables separato nel corpo della richiesta.
Un input object type si dichiara con la parola chiave input invece di type. I suoi campi possono essere solo scalari, enum, liste o altri input type, e questo rende semplice validare la forma di ciò che inviano i client.
Errori da una scrittura
Se il documento non è valido, per esempio un campo scritto male o una variabile obbligatoria mancante, il server risponde con errori e nessun dato, e non viene scritto nulla.
Se è la scrittura stessa a fallire durante l'esecuzione, il campo torna null e una voce in errors riporta un messaggio e un percorso. Molti schemi restituiscono anche i problemi previsti, come un titolo troppo lungo, come campi di un tipo payload così il client può mostrarli accanto al form.
Lo schema dietro gli esempi
Tipo Mutation e input type
Gli input type usano la parola chiave input. TaskPatch non ha campi obbligatori, quindi un aggiornamento può inviare solo ciò che è cambiato.
Inviarla da JavaScript
Invia la mutation in POST con fetch
Il documento e le variabili viaggiano come due chiavi di un unico body JSON. Controlla errors anche quando lo status è 200.
Due scritture in una sola operazione
Gli alias permettono di eseguire lo stesso campo due volte. Il secondo parte solo quando il primo è finito, ma un suo errore non annulla il primo.
Creazione
L'input type raggruppa i campi della nuova attività. Il selection set chiede l'id assegnato dal server.
Aggiornamento
L'id indica quale attività modificare e l'input contiene solo i campi che cambiano.
Eliminazione
Non resta nulla da selezionare su un'attività rimossa, quindi questo schema restituisce l'id eliminato come semplice scalare ID.
Builder di mutation
Scegli una mutation
Titolo dell'attività
Mutation
Variabili (JSON)
Risposta di esempio
Copia mutation
Copia variabili
L'eliminazione richiede solo l'id, quindi il titolo non viene inviato.