GraphQL-mutations: syntax, variabelen en input-types | We.Inc
Schrijf GraphQL-mutations die data aanmaken, wijzigen en verwijderen: operatiesyntax, $variables, input-objecttypes, wat u teruggeeft en hoe fouten en gedeeltelijk succes eruitzien.
Een GraphQL-mutation is de operatie die u stuurt om data te wijzigen. Hij begint met het sleutelwoord mutation, roept een veld aan op het Mutation-type van het schema, geeft argumenten mee, meestal één input-object in een $variable, en kiest welke velden van het resultaat terugkomen. Mutation-velden op het hoogste niveau draaien na elkaar, nooit parallel.
Mutation-syntax in onderdelen
Onderdeel
Voorbeeld
Wat het doet
Sleutelwoord en naam
mutation AddTask
Markeert de operatie als schrijfactie en geeft haar een naam voor de logs
Variabeledefinities
($input: TaskInput!)
Declareert getypeerde waarden die apart als JSON worden verstuurd
Rootveld
addTask(input: $input)
Een veld dat op het Mutation-type is gedefinieerd
Selection set
{ id title done }
Velden van het resultaat die worden teruggestuurd
Variabelen-JSON
{"input": {...}}
De echte waarden, buiten de querystring gehouden
Gebruik de bouwer hieronder om een volledige mutation te zien voor een kleine takenlijst: de operatie, de variabelen-JSON die uw code ermee zou meesturen en een typische response. Typ een taaktitel en zie de variabelen bijwerken, zodat u een verzoek kunt kopiëren dat klaar is om tegen een passend schema te draaien.
Kies aanmaken, wijzigen of verwijderen.
Typ een titel voor de taak; de variabelen-JSON werkt bij terwijl u typt.
Kopieer de mutation en de variabelen en verstuur ze als de sleutels query en variables van één POST.
Vergelijk het antwoord van uw server met de voorbeeldresponse eronder.
Verstuur waarden via variabelen in plaats van ze in de querystring te plakken. Dat voorkomt escapefouten en laat servers het geparste document cachen.
Geef het gewijzigde object terug, inclusief zijn id, zodat client-caches het scherm kunnen bijwerken zonder tweede verzoek.
Geef elke operatie een naam. Benoemde mutations zijn veel makkelijker terug te vinden in serverlogs en foutrapporten.
Behandel meerdere rootvelden in één mutation als losse stappen, niet als transactie: een eerder veld blijft uitgevoerd als een later veld faalt.
Veelgestelde vragen
Wat is het verschil tussen een query en een mutation?
Beide gebruiken dezelfde syntax en beide kunnen data teruggeven. Volgens afspraak lezen queries alleen en schrijven mutations. Ook de uitvoeringsregel verschilt: queryvelden mogen parallel worden opgelost, terwijl mutation-velden op het hoogste niveau na elkaar draaien.
Waarom een input-type gebruiken in plaats van losse argumenten?
Een input-object bundelt samenhangende waarden in één getypeerd argument, zodat de signatuur van de mutation kort blijft en u later optionele velden kunt toevoegen zonder elke aanroeper te wijzigen.
Kan ik een mutation met een GET-verzoek versturen?
Nee. De richtlijnen voor GraphQL over HTTP laten servers GET alleen accepteren voor query-operaties. Mutations gaan als POST, wat schrijfacties ook buiten browser- en CDN-caches houdt.
Is een mutation met meerdere velden atomair?
Nee. graphql.org merkt op dat seriële uitvoering geen databasetransactie is. Als het tweede veld faalt, blijft de wijziging van het eerste staan, en de response bevat data voor het ene en een fout voor het andere.
Wat moet een delete-mutation teruggeven?
De specificatie laat dat aan u over, maar het veld heeft nog steeds een output-type nodig. Gangbare keuzes zijn de id van het verwijderde object, het verwijderde object zelf, of een payload-type met de id en een succesflag.
Anatomie van een mutation
Op de server declareert het schema een Mutation-type waarvan de velden de schrijfacties zijn die clients mogen aanroepen, elk met argumenten en een returntype. Op de client noemt de operatie een of meer van die velden, geeft argumenten mee en kiest de resultaatvelden die terug moeten komen.
Als het veld een objecttype teruggeeft, is een selection set verplicht, net als in een query. Door de nieuwe id en de velden die het scherm toont op te vragen, kan de client zijn weergave direct vanuit de response bijwerken.
Variabelen en input-objecten
Variabelen worden na de operatienaam gedeclareerd met een dollarteken en een type, zoals $input: TaskInput!. Het uitroepteken maakt de variabele verplicht. De waarden reizen mee in een apart variables-object in de body van het verzoek.
Een input-objecttype wordt gedeclareerd met het sleutelwoord input in plaats van type. De velden ervan kunnen alleen scalars, enums, lijsten of andere input-types zijn, wat de vorm van wat clients versturen eenvoudig te valideren houdt.
Fouten bij een schrijfactie
Als het document ongeldig is, bijvoorbeeld door een verkeerd gespeld veld of een ontbrekende verplichte variabele, antwoordt de server met errors en zonder data, en wordt er niets geschreven.
Als de schrijfactie zelf tijdens de uitvoering faalt, komt het veld terug als null en bevat een errors-item een bericht en een path. Veel schema's geven verwachte problemen, zoals een te lange titel, ook terug als velden van een payload-type, zodat de client ze naast het formulier kan tonen.
Het schema achter de voorbeelden
Mutation-type en input-types
Input-types gebruiken het sleutelwoord input. TaskPatch heeft geen verplichte velden, dus een update kan alleen versturen wat er veranderd is.
Versturen vanuit JavaScript
De mutation POSTen met fetch
Het document en de variabelen reizen als twee sleutels van één JSON-body. Controleer errors, ook als de status 200 is.
Twee schrijfacties in één operatie
Met aliassen kan hetzelfde veld twee keer draaien. Het tweede draait pas als het eerste klaar is, maar een fout erin maakt het eerste niet ongedaan.
Aanmaken
Het input-type bundelt de velden van de nieuwe taak. De selection set vraagt om de id die de server heeft toegekend.
Wijzigen
De id zegt welke taak moet veranderen en de input bevat alleen de velden die veranderen.
Verwijderen
Bij een verwijderde taak valt niets meer te selecteren, dus dit schema geeft de verwijderde id terug als gewone ID-scalar.
Mutation-bouwer
Kies een mutation
Taaktitel
Mutation
Variabelen (JSON)
Voorbeeldresponse
Mutation kopiëren
Variabelen kopiëren
Verwijderen heeft alleen de id nodig, dus de titel wordt niet verstuurd.