Mutacje GraphQL z działającymi przykładami

Mutacje GraphQL

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.

Zbuduj stronę za darmo · Za darmo, bez karty

Powiązane: Poradniki

Produkt

Dla kogo

Funkcje

Zasoby

Firma

Mapa strony