PHP Academy · Lekcja

GraphQL a REST

Dowiedz się, kiedy GraphQL sprawdza się lepiej niż REST i dlaczego

GraphQL a REST to bezpłatna lekcja PHP Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej PHP Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs PHP Academy zawiera 4 lekcji w sumie.

Dlaczego GraphQL?

Potrafią już Państwo tworzyć w PHP interfejsy REST gotowe do wdrożenia. GraphQL nie zastępuje HTTP i nie jest magicznym rozwiązaniem — to język zapytań i system typów, który pozwala klientowi dokładnie opisać potrzebne dane i otrzymać dokładnie to, czego potrzebuje, w jednym wywołaniu.

W tej lekcji uczciwie porównamy oba podejścia: sytuacje, w których GraphQL rzeczywiście wygrywa, te, w których REST nadal jest właściwym wyborem, oraz operacyjne koszty GraphQL.

Nadmiarowe i niedostateczne pobieranie danych

Klasyczne problemy REST:

Pobieranie nadmiarowych danych: GET /users/1 zwraca 40 pól, choć interfejs potrzebuje 3.
Pobieranie niewystarczających danych: aby wyrenderować wpisy użytkownika i liczbę komentarzy przy każdym wpisie, należy wywołać /users/1, następnie /users/1/posts, a potem N endpointów komentarzy.

GraphQL scala to w jedno deklaratywne żądanie.

query {
  user(id: 1) {
    name
    posts {
      title
      commentCount
    }
  }
}

Jeden endpoint, typowany schemat

REST udostępnia wiele adresów URL, natomiast GraphQL udostępnia jeden endpoint (zwykle POST /graphql) oparty na silnie typowanym schemacie. Schemat jest kontraktem — można go introspekować, więc narzędzia (automatyczne uzupełnianie, dokumentacja, generowanie kodu) są dostępne bez dodatkowej pracy.

Poniżej przedstawiono minimalny schemat w SDL. Struktura każdej możliwej odpowiedzi jest znana z góry.

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  commentCount: Int!
}

type Query {
  user(id: ID!): User
}

Odpowiedź odzwierciedla zapytanie

Kluczowa właściwość: struktura odpowiedzi JSON jest przewidywalna na podstawie zapytania. Klienci nie muszą zgadywać nazw pól. Eliminuje to całą klasę problemów związanych z wersjonowaniem — można dodawać pola bez łamania starszych klientów, a pola wycofywać za pomocą @deprecated, zamiast wprowadzać adresy /v2.

{
  "data": {
    "user": {
      "name": "Ada",
      "posts": [
        { "title": "On Engines", "commentCount": 12 }
      ]
    }
  }
}

Kiedy GraphQL ma przewagę nad REST

GraphQL jest lepszym wyborem, gdy:

Obsługują Państwo wielu różnorodnych klientów (web, iOS, Android) o różnych potrzebach dotyczących danych.
Dane tworzą graf o głębokich relacjach, który klienci przemierzają dynamicznie.
Chcą Państwo agregować wiele backendów za jedną typowaną bramą.
Liczy się szybka iteracja po stronie frontendu, a Państwo chcą uniknąć niekończących się zmian endpointów backendu.

Gdzie REST nadal ma przewagę

Nie należy sięgać po GraphQL odruchowo. REST jest prostszy i często lepszy, gdy:

Potrzebne jest buforowanie HTTP — pamięci podręczne CDN i edge opierają klucze na adresach URL i metodach HTTP; pojedyncze POST /graphql jest dla nich nieprzejrzyste.
API jest zorientowane na zasoby i stabilne (CRUD dla kilku encji).
Potrzebne jest przesyłanie i pobieranie plików lub strumieniowanie, w przypadku których multipart i zakresy bajtów są w REST obsługiwane natywnie.
Odbiorcami są zewnętrzni użytkownicy, którzy oczekują konwencjonalnej semantyki REST.

Krótkie porównanie w PHP

Oto te same dane złożone w sposób typowy dla REST w PHP — proszę zauważyć, że klient nadal potrzebowałby wielu wywołań albo trzeba byłoby ręcznie skonstruować parametr embed. GraphQL przenosi tę logikę wyboru na klienta.

<?php
// REST: server decides the payload shape
function userResource(int $id): array {
    return [
        'id' => $id,
        'name' => 'Ada',
        'email' => 'ada@example.com',   // over-fetched by mobile
        'createdAt' => '1815-12-10',
        'posts' => [                       // pre-embedded, all-or-nothing
            ['title' => 'On Engines', 'commentCount' => 12],
        ],
    ];
}

header('Content-Type: application/json');
echo json_encode(userResource(1), JSON_PRETTY_PRINT);

Koszty, które wprowadza GraphQL

GraphQL przenosi złożoność na serwer. Pojawiają się nowe kwestie, za które trzeba odpowiadać:

Zapytania N+1 — zagnieżdżone resolvery wykonują jedno zapytanie do bazy na każdy węzeł, chyba że zostaną zbatchowane (DataLoader).
Ograniczanie kosztu i głębokości zapytań — złośliwe, głęboko zagnieżdżone zapytanie może doprowadzić do DoS.
Buforowanie jest trudniejsze; zwykle stosuje się je na poziomie resolvera lub danych, a nie HTTP.
Obsługa błędów wygląda inaczej — odpowiedź 200 OK może nadal zawierać tablicę errors.

Błędy: 200 z tablicą errors

W przeciwieństwie do kodów statusu REST, GraphQL standardowo zwraca HTTP 200 i zgłasza częściowe niepowodzenia w treści odpowiedzi. data może być częściowo wypełnione, podczas gdy errors zawiera informacje o tym, co się nie powiodło. Klienci muszą sprawdzać oba pola.

{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "path": ["user"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

Praktyczna reguła wyboru

Praktyczna reguła:

Publiczne API, intensywne wykorzystanie cache, CRUD zorientowane na zasoby → REST.
Wewnętrzne API lub API produktu zasilające różnorodne, rozbudowane klienty na podstawie połączonych danych → GraphQL.
Wiele backendów do ujednolicenia za pomocą jednego typowanego kontraktu → bramka GraphQL.

Często i sensownie jest używać obu: REST do webhooków i przesyłania plików, a GraphQL do grafu odczytu aplikacji.

Udostępnianie GraphQL przez HTTP w PHP

Od strony operacyjnej endpoint GraphQL w PHP to jedna trasa, która odczytuje treść JSON, pobiera z niej query i variables, wykonuje je względem schematu i zwraca { data, errors }. W porównaniu z wieloma trasami REST transport jest jednolity — cała różnorodność znajduje się w ciągu zapytania wysyłanym przez klienta.

<?php
// Minimal GraphQL-over-HTTP entry point
$input = json_decode(file_get_contents('php://input'), true) ?? [];
$query = $input['query'] ?? '';
$variables = $input['variables'] ?? null;

// $result = GraphQL::executeQuery($schema, $query, null, $ctx, $variables);
// header('Content-Type: application/json');
// echo json_encode($result->toArray());
var_dump(['query' => $query, 'variables' => $variables]);

Szybkie sprawdzenie

Kiedy REST zachowuje wyraźną przewagę nad GraphQL?

Podsumowanie

Porównano GraphQL i REST pod kątem istotnych różnic:

GraphQL rozwiązuje problem pobierania zbyt małej lub zbyt dużej ilości danych za pomocą jednego typowanego endpointu i wyboru sterowanego przez klienta.
Sprawdza się szczególnie przy wielu klientach, danych o strukturze grafu i agregowaniu danych z backendu.
REST nadal jest dobrym rozwiązaniem dla publicznych API obsługujących cache, prostego CRUD, przesyłania plików i konwencjonalnych odbiorców.
GraphQL przenosi koszty na serwer: N+1, ograniczenia kosztu zapytań, buforowanie oraz semantykę odpowiedzi 200 z błędami.

Następnie: zbudowanie schematu za pomocą webonyx/graphql-php.

Często zadawane pytania

Czy lekcja „GraphQL a REST” jest bezpłatna?

Tak — pełny tekst „GraphQL a REST” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu PHP Academy, przejdź na CoddyKit PRO. Kurs PHP Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „GraphQL a REST”?

Dowiedz się, kiedy GraphQL sprawdza się lepiej niż REST i dlaczego Ćwiczysz PHP Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć PHP Academy?

Nie wymagamy żadnego doświadczenia. PHP Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „GraphQL a REST”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji PHP Academy?

Tak. Każda lekcja PHP Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do PHP Academy