GraphQL jelentése — eClick Tudástár

A GraphQL egy lekérdező nyelv API-khoz, amit a Facebook 2012-ben kezdett el használni és 2015-ben nyitott meg nyilvánosan. Lényege: a kliens pontosan megadhatja, milyen mezőket szeretne lekérni, egyetlen HTTP-kérésben, fix endpoint-on (általában /graphql) — és pontosan azt kapja vissza, sem többet, sem kevesebbet. A modern web egyik domináns API-paradigmája a REST mellett, és bizonyos use case-ekben jelentősen rugalmasabb. Ha valaha böngészted a GitHub API-t, vagy Shopify Storefront-tal dolgoztál, már használtál GraphQL-t.

Így is ismerheted

Magyar fordítása nincs általánosan elfogadott — szinte mindenki a GraphQL nevet használja (kiejtése: gráf-kjú-el vagy gráf-kyúel). A „Graph Query Language” rövidítése. Néha „Graph API”-nak is hívják (a Facebook Graph API GraphQL alapokon működik). Kapcsolódó fogalmak: schema (a típusrendszer), resolver (a kód, ami visszaadja az adatot), query (olvasás), mutation (írás), subscription (real-time változás).

GraphQL vs REST — mi a fő különbség?

REST-en több endpoint-ot kérdezel le egymás után: GET /users/123, GET /users/123/posts, GET /posts/456/comments. Minden endpoint fix struktúrájú, és sokszor kapsz több adatot mint amennyire szükséged van (over-fetching), vagy kevesebbet (under-fetching, plusz kérések kellenek).

GraphQL-ben egy lekérdezés mindezt egyben hozza:

query {
  user(id: 123) {
    name
    email
    posts {
      title
      comments { author, body }
    }
  }
}

Egy HTTP-kérés, pontosan a kért mezők, fészkelt kapcsolatok. A kliens dönti el, mit kér. Tipikus eredmény: mobil app-on, ahol a hálózat lassú, ez 3–5 kérést spórol egy oldalbetöltésnél — ami észrevehető javulás.

Cserébe a szerveroldal komplexebb. Egy REST endpoint sztenderd SQL JOIN-nal megoldható; egy GraphQL resolver minden mezőhöz egy függvény, és figyelni kell az N+1 probléma-ra: ha a query 100 user-t kér, és mindegyikhez 10 post-ot, a naív implementáció 100 × 10 = 1000 DB-kérést indít. Megoldás: DataLoader pattern, ami batch-eli a kéréseket.

Mikor érdemes GraphQL-t választani?

Nem minden projekten van értelme. Pár tipikus jó és rossz eset:

JÓ: mobil app, ahol a hálózat lassú és minimalizálni kell a kéréseket.
JÓ: komplex frontend (React, Vue, Svelte) ahol különböző komponensek különböző mező-szubsztat-okat kérnek.
JÓ: headless CMS (Strapi, Hygraph, Contentful) ahol a frontend tervezője és a backend nem ugyanaz.
NEM: egyszerű CRUD-API, ahol REST 5 endpoint elég.
NEM: nagy publikus API (ahol cache-elni akarsz HTTP-szinten — GraphQL POST-on jön, nehéz CDN-en cache-elni).
NEM: file-upload-heavy szolgáltatás (a GraphQL alapból nem support-álja, kell hozzá kiegészítés).

Tooling — mit használj fejlesztéshez?

A GraphQL ökoszisztéma érett, de fragmentált. Szerveroldal a tipikus választások:

Apollo Server — Node.js, a legelterjedtebb. Saját Apollo Studio dashboard, premium tier-rel monitorozás.
GraphQL Yoga — könnyebb alternatíva, jó beépített file-upload és subscription.
Hasura — PostgreSQL fölött automatikusan generál GraphQL API-t. Egy óra alatt kezeled, amit kézzel napokba kerülne. Tipikusan dashboard-ok és belső admin-tooling, ahol nem kell mély üzleti logika.
Strapi v4 — headless CMS, beépített GraphQL plugin-nal.
WPGraphQL (WordPress) — WP REST API GraphQL-tetejű alternatívája, headless WordPress projektekhez.

Kliensoldalon az Apollo Client és a urql a legelterjedtebb React-projekten, mindketten beépített cache-eléssel és optimistic update-ekkel. Egyszerűbb használat esetén a graphql-request könyvtár is elég — egy alap fetch wrapper. Vue-projekten az Apollo Composable a Vue 3-mal jól együtt él. Mobil oldalon a React Native és Flutter is kapott natív Apollo-ekvivalenseket.

Tipikus hibák és buktatók

Egy gyakori baki, ami komoly performance-problémát okozhat: a N+1 query problem. A naív resolver minden nested mező-lekérdezésnél új DB-kérést indít. Egyetlen olyan GraphQL query, ami users { posts { author { name } } }-t kér, könnyen több ezer DB-kérést okozhat 100 user-rel. Mindig használj DataLoader-t vagy SQL-szintű batch-elést — a Hasura ezt automatikusan megoldja.

Másik klasszikus hiba: GraphQL endpoint cache-elése HTTP-szinten. Mivel mindenki POST-ra /graphql-re megy, és a body változik, a CDN nem tudja cache-elni. Megoldás vagy az Automatic Persisted Queries (Apollo feature, ami a query-t GET-re alakítja hash-sel), vagy egy edge worker-ben saját cache-réteg.

Biztonság szempontjából figyelj a query-depth limitre és a query-complexity-re — egy rosszindulatú kliens olyan mély/komplex query-t küldhet, ami megfojtja a szervert (pl. user { posts { comments { author { posts { ... } } } } } 20 szinten). Apollo Server-ben ez plugin-nal állítható.

GraphQL és OAuth — auth integráció

GraphQL nem köt ki autentikációt — a megszokott OAuth-flow simán működik felette. Tipikus megoldás: a kliens egy access token-t küld a Authorization: Bearer header-ben, és a GraphQL middleware (pl. Apollo Server context function) validálja minden kérésnél. A field-level authorization (egyes mezők rejtése a user szerepe alapján) GraphQL Shield vagy GraphQL Armor library-vel oldható meg deklaratívan.

Ha GraphQL-API-t építenénk neked — akár nulláról React + Apollo stack-en, akár headless WordPress-en WPGraphQL-lel, akár Hasura PostgreSQL fölé —, lásd az egyedi weboldal-fejlesztés szolgáltatásunkat. Kapcsolódó cikkek: Webhook, OAuth, WebSocket. A hivatalos doksi az graphql.org-on érhető el.

GraphQL