W praktyce
GraphQL wybieram wtedy, gdy ekrany aplikacji potrzebują różnych wycinków tych samych danych i nie chcę mnożyć endpointów. Stoi w stosie Kuma.de oraz, w zespole Code & Pepper, Little Birdie. Przy prostym API z kilkoma zasobami zostaję przy REST.
Czym jest GraphQL?
GraphQL to język zapytań do API i środowisko wykonawcze po stronie serwera, oparte na typach, które sam definiujesz. Usługę opisujesz schematem: typami i ich polami, a dla każdego pola piszesz funkcję, która dostarcza dane. GraphQL nie jest związany z żadną bazą ani magazynem danych, bo opiera się na Twoim kodzie.
Klient wysyła zapytanie o dokładnie te pola, których potrzebuje, i dostaje odpowiedź w tym samym kształcie, w jednym żądaniu. Serwer najpierw sprawdza zapytanie ze schematem, a dopiero potem je wykonuje. Pozwala też zapytać o sam schemat, czyli robi introspekcję, na której opierają się narzędzia deweloperskie. Działa zwykle pod jednym adresem, a nie pod osobnym dla każdego zasobu.
- Rodzaj
- Język zapytań i środowisko wykonawcze
- Schemat
- Typy i pola, funkcja dla każdego pola
- Odpowiedź
- Tylko pola z zapytania, w jednym żądaniu
- Punkt wejścia
- Zwykle jeden adres dla całego API
Jak pracuję z GraphQL
Zaczynam od ekranów, nie od schematu. Najpierw spisuję, jakich danych potrzebuje każdy ekran, bo schemat ma służyć klientowi, a nie odbijać strukturę bazy. Nie zaczynam od biblioteki ani generatora kodu: najpierw ustalam, kto pyta o dane i jak często zmieniają się jego potrzeby.
Schemat od strony ekranu
Typy i pola nazywam tak, jak mówi o nich aplikacja, a nie tak, jak nazywają się tabele. Schemat jest umową między frontendem a backendem, więc trzymam go w repozytorium i zmieniam przez review. Pola oznaczone jako przestarzałe zostają, dopóki coś z nich korzysta, więc starsza wersja aplikacji mobilnej nie przestaje działać.
Pola wybiera klient
Zapytanie wymienia pola, których ekran potrzebuje, więc nie wysyłam nadmiaru. W Kuma.de każdy ekran pobiera tylko potrzebne dane.
Uprawnienia i limity
Uprawnienia sprawdzam w logice wywoływanej z funkcji pól, na poziomie pól. Przed produkcją ustalam limity zapytań i decyduję o introspekcji, bo oba zagadnienia należą do bezpieczeństwa.
Kiedy tak, a kiedy nie
GraphQL ma sens, gdy wielu klientów pyta o różne wycinki tych samych danych.
Sprawdza się, gdy
- Aplikacja webowa i mobilna, które korzystają z jednego API, ale potrzebują innych pól.
- Ekrany z danymi z kilku źródeł, które klient woli pobrać jednym zapytaniem.
- Backend na Strapi, który udostępnia GraphQL przez wtyczkę.
- API, którego schemat ma być jawną umową zespołów frontendu i backendu.
Nie sprawdza się, gdy
- Proste API z kilkoma zasobami, które w pełni obsłuży REST.
- Zespół, który nie utrzyma schematu ani funkcji pól.
- Publiczne API, w którym liczy się cache po adresie URL, bo w GraphQL adres nie identyfikuje obiektu.
Gdy frontend i backend żyją w jednym projekcie TypeScript, patrzę na tRPC, który opisuję osobno. Dla prostych zasobów wystarczy REST.
Często zadawane pytania
Aplikacja webowa i mobilna na jednym API?
Napisz, jakich ekranów potrzebujesz i skąd mają pochodzić dane. Odpowiem, czy GraphQL się tu opłaci, czy wystarczy zwykłe REST.