Mutacje GraphQL: składnia, zmienne i typy input | We.Inc
Pisz mutacje GraphQL, które tworzą, aktualizują i usuwają dane: składnia operacji, $variables, typy obiektów input, co zwracać oraz jak wyglądają błędy i częściowy sukces.
Mutacja GraphQL to operacja, którą wysyłasz, aby zmienić dane. Zaczyna się od słowa kluczowego mutation, wywołuje pole typu Mutation w schemacie, przekazuje argumenty, zwykle jeden obiekt input trzymany w $variable, i wybiera, które pola wyniku mają wrócić. Pola mutacji najwyższego poziomu wykonują się jedno po drugim, nigdy równolegle.
Składnia mutacji w częściach
Część
Przykład
Co robi
Słowo kluczowe i nazwa
mutation AddTask
Oznacza operację jako zapis i nazywa ją na potrzeby logów
Definicje zmiennych
($input: TaskInput!)
Deklaruje otypowane wartości wysyłane osobno jako JSON
Pole główne
addTask(input: $input)
Pole zdefiniowane w typie Mutation
Selection set
{ id title done }
Pola wyniku, które mają zostać odesłane
JSON zmiennych
{"input": {...}}
Faktyczne wartości, trzymane poza tekstem zapytania
Użyj generatora poniżej, aby zobaczyć pełną mutację dla małej listy zadań: operację, JSON zmiennych, który Twój kod by z nią wysłał, oraz typową odpowiedź. Wpisz tytuł zadania i obserwuj, jak aktualizują się zmienne, aby skopiować żądanie gotowe do uruchomienia na pasującym schemacie.
Wybierz tworzenie, aktualizację lub usuwanie.
Wpisz tytuł zadania; JSON zmiennych aktualizuje się podczas pisania.
Skopiuj mutację i zmienne, a następnie wyślij je jako klucze query i variables w jednym żądaniu POST.
Porównaj odpowiedź swojego serwera z przykładową odpowiedzią pokazaną pod nimi.
Przekazuj wartości przez zmienne, zamiast wklejać je do tekstu zapytania. Unikasz w ten sposób błędów escapowania, a serwery mogą cache'ować sparsowany dokument.
Zwracaj zmieniony obiekt razem z jego id, aby cache po stronie klienta mógł zaktualizować ekran bez drugiego żądania.
Nazywaj każdą operację. Nazwane mutacje znacznie łatwiej znaleźć w logach serwera i raportach błędów.
Traktuj kilka pól głównych w jednej mutacji jako osobne kroki, a nie transakcję: wcześniejsze pole pozostaje wykonane, gdy późniejsze zawiedzie.
Najczęściej zadawane pytania
Jaka jest różnica między query a mutacją?
Obie używają tej samej składni i obie mogą zwracać dane. Zgodnie z konwencją zapytania tylko czytają, a mutacje zapisują. Różni się też zasada wykonania: pola zapytania mogą być rozwiązywane równolegle, a pola mutacji najwyższego poziomu wykonują się po kolei.
Po co typ input zamiast zwykłych argumentów?
Obiekt input grupuje powiązane wartości w jeden otypowany argument, więc sygnatura mutacji pozostaje krótka, a później możesz dodawać opcjonalne pola bez zmieniania każdego wywołania.
Czy mogę wysłać mutację żądaniem GET?
Nie. Wytyczne GraphQL over HTTP pozwalają serwerom przyjmować GET tylko dla operacji query. Mutacje wysyła się jako POST, co dodatkowo trzyma zapisy z dala od cache przeglądarki i CDN.
Czy mutacja z kilkoma polami jest atomowa?
Nie. graphql.org zaznacza, że wykonanie sekwencyjne to nie transakcja bazodanowa. Jeśli drugie pole zawiedzie, zmiana z pierwszego zostaje, a odpowiedź zawiera dane dla jednego i błąd dla drugiego.
Co powinna zwracać mutacja usuwająca?
Specyfikacja zostawia to Tobie, ale pole nadal potrzebuje typu wyjściowego. Typowe wybory to id usuniętego obiektu, sam usunięty obiekt albo typ payload z id i flagą sukcesu.
Budowa mutacji
Na serwerze schemat deklaruje typ Mutation, którego pola to zapisy, jakie mogą wywoływać klienci, każde z argumentami i typem zwracanym. Po stronie klienta operacja wymienia jedno lub więcej z tych pól, przekazuje argumenty i wybiera pola wyniku, które chce otrzymać.
Jeśli pole zwraca typ obiektowy, selection set jest wymagany, tak samo jak w zapytaniu. Poproszenie o nowe id i pola wyświetlane na ekranie pozwala klientowi zaktualizować widok prosto z odpowiedzi.
Zmienne i obiekty input
Zmienne deklaruje się po nazwie operacji ze znakiem dolara i typem, na przykład $input: TaskInput!. Wykrzyknik sprawia, że zmienna jest wymagana. Wartości trafiają do osobnego obiektu variables w treści żądania.
Typ obiektu input deklaruje się słowem kluczowym input zamiast type. Jego pola mogą być tylko skalarami, enumami, listami lub innymi typami input, dzięki czemu kształt danych wysyłanych przez klientów łatwo zwalidować.
Błędy przy zapisie
Jeśli dokument jest niepoprawny, na przykład zawiera literówkę w nazwie pola albo brakuje wymaganej zmiennej, serwer odpowiada błędami bez danych i nic nie zostaje zapisane.
Jeśli sam zapis zawiedzie podczas wykonania, pole wraca jako null, a wpis w errors zawiera komunikat i ścieżkę. Wiele schematów zwraca też spodziewane problemy, na przykład zbyt długi tytuł, jako pola typu payload, aby klient mógł pokazać je obok formularza.
Schemat stojący za przykładami
Typ Mutation i typy input
Typy input używają słowa kluczowego input. TaskPatch nie ma wymaganych pól, więc aktualizacja może wysłać tylko to, co się zmieniło.
Wysyłanie z JavaScriptu
Wyślij mutację przez POST z fetch
Dokument i zmienne podróżują jako dwa klucze jednej treści JSON. Sprawdzaj errors nawet przy statusie 200.
Dwa zapisy w jednej operacji
Aliasy pozwalają uruchomić to samo pole dwa razy. Drugie wykonuje się dopiero po zakończeniu pierwszego, ale jego błąd nie cofa pierwszego.
Tworzenie
Typ input grupuje pola nowego zadania. Selection set prosi o id nadane przez serwer.
Aktualizacja
id wskazuje, które zadanie zmienić, a input zawiera tylko zmieniane pola.
Usuwanie
Z usuniętego zadania nie ma już czego wybrać, więc ten schemat zwraca usunięte id jako zwykły skalar ID.
Generator mutacji
Wybierz mutację
Tytuł zadania
Mutacja
Zmienne (JSON)
Przykładowa odpowiedź
Kopiuj mutację
Kopiuj zmienne
Usuwanie potrzebuje tylko id, więc tytuł nie jest wysyłany.