Podstawy GraphQL dla programistów Reacta

REST udostępnia endpointy o stałej strukturze: GET /users/:id zwraca cały obiekt użytkownika niezależnie od tego, jakich danych potrzebuje klient. GraphQL pozwala klientom dokładnie określić, które pola chcą otrzymać, eliminując nadmiarowe pobieranie danych (over-fetching) i niedostateczne pobieranie danych (under-fetching), które wymaga wielu żądań.

Jedno zapytanie GraphQL może pobrać użytkownika, jego posty oraz autora każdego posta w ramach jednego żądania.

Każdy interfejs API GraphQL jest definiowany za pomocą schematu zapisanego w Schema Definition Language (SDL). Schemat deklaruje typy, ich pola oraz główne typy Query, Mutation i Subscription, na których klienci mogą wykonywać operacje.

Schemat jest kontraktem między klientem a serwerem. Zespoły frontendowe i backendowe mogą pracować równolegle po uzgodnieniu schematu.

Zapytanie GraphQL wybiera pola: { user(id: "1") { name email posts { title } } }. Zagnieżdżone pola pozwalają przechodzić przez relacje w ramach jednego żądania. Aliasy zmieniają nazwy pól: { me: user(id: "1") { name } }. Fragmenty pozwalają ponownie wykorzystywać wybór pól w wielu zapytaniach.

Zmienne sprawiają, że zapytania można ponownie wykorzystywać: query GetUser($id: ID!) { user(id: $id) { name } } z variables: { id: "1" }.

Każde pole w schemacie GraphQL ma po stronie serwera funkcję resolvera. Gdy klient pyta o user.name, resolver użytkownika pobiera obiekt użytkownika, a resolver pola name (lub resolver domyślny) zwraca pole name.

Rozwiązywanie na poziomie pól umożliwia GraphQL precyzyjne pobieranie wyłącznie żądanych danych.

Jeśli zapytanie pobiera listę 100 postów, a każdy post zawiera swojego autora, naiwna implementacja wykonuje 100 osobnych zapytań do bazy danych w celu pobrania autorów. Bez optymalizacji ten problem N+1 spowalnia interfejsy API GraphQL.

DataLoader rozwiązuje problem N+1, grupując wszystkie wyszukiwania autorów w jedno zapytanie do bazy danych za pomocą pamięci podręcznej dla pojedynczego żądania i funkcji grupującej.

Apollo Studio i GraphQL Playground to interfejsy użytkownika dostępne w przeglądarce, służące do interaktywnego eksplorowania interfejsu API GraphQL. Automatycznie uzupełniają pola na podstawie schematu, wyświetlają wyniki zapytań i pokazują dokumentację typów bezpośrednio w interfejsie.

Korzystanie z tego narzędzia to najszybszy sposób na zrozumienie nieznanego interfejsu API GraphQL przed napisaniem kodu klienta.

Interfejsy API GraphQL udostępniają własny schemat za pomocą zapytania introspekcyjnego: { __schema { types { name } } }. Klienci mogą odpytywać sam schemat, aby odkrywać dostępne typy, pola i argumenty.

Narzędzia do generowania kodu, takie jak graphql-codegen, używają introspekcji do automatycznego generowania typów TypeScript zgodnych ze schematem API.

Mutacje GraphQL modyfikują dane: mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. Subskrypcje ustanawiają trwałe połączenie (zwykle WebSocket) i przesyłają aktualizacje: subscription { postAdded { id title } }.

Wszystkie trzy typy główne (Query, Mutation, Subscription) używają tej samej składni wyboru pól.

GraphQL sprawdza się doskonale w aplikacjach złożonymi, zagnieżdżonymi wymaganiami dotyczącymi danych, z wieloma typami klientów (mobilnymi, internetowymi i telewizyjnymi) potrzebującymi różnych podzbiorów pól lub z szybko rozwijającymi się interfejsami API, w których preferowane jest wycofywanie pól zamiast wersjonowania endpointów.

REST jest prostszy w przypadku interfejsów API CRUD z przewidywalnymi, płaskimi strukturami zasobów oraz doskonale współpracuje z pamięcią podręczną HTTP dzięki ETagom i nagłówkom cache.

Apollo Client to najbardziej rozbudowany funkcjonalnie klient GraphQL: oferuje znormalizowany cache, zarządzanie stanem lokalnym, subskrypcje i linki obsługi błędów. URQL jest lżejszy, korzysta z cache dokumentów i ma prostsze API. React Query z graphql-request to najprostsze podejście do podstawowych zapytań i mutacji, bez zaawansowanych funkcji cachowania.

Wybór zależy od wymagań dotyczących cachowania: znormalizowany cache sprawdzi się w przypadku encji współdzielonych między zapytaniami (Apollo), a prostszy cache dokumentów w przypadku niezależnych zapytań (URQL lub React Query).

Prosty SDL: type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. Wykrzykniki oznaczają pola, które nie mogą mieć wartości null.

Ten schemat dokładnie informuje klienta, jakie pola istnieją w każdym typie i jakie zapytania są dostępne, umożliwiając generowanie kodu z bezpiecznym typowaniem.

Co oznacza "over-fetching" w kontekście REST i GraphQL?

GraphQL pozwala klientom żądać dokładnie tych pól, których potrzebują (bez nadmiernego ani niedostatecznego pobierania danych), za pomocą języka zapytań zdefiniowanego przez schemat. Resolverzy odpowiadają za poszczególne pola, a DataLoader rozwiązuje problem N+1. Introspekcja umożliwia generowanie typów TypeScript. Apollo Client, URQL i React Query to główni klienci GraphQL zgodni z React.

GraphQL należy wybrać w przypadku złożonych, zagnieżdżonych danych wymaganych przez wielu klientów, a REST w przypadku prostych operacji CRUD z przewidywalnymi strukturami.