Jan Mikoláš
Slovník pojmů
GraphQL
GraphQL dává klientovi přesný výběr dat. Není to databázový jazyk ani automatické řešení výkonu, oprávnění nebo návrhu API.
Stručná definice
Kontrakt API popsaný typy, poli a operacemi.
Server nejprve zveřejní GraphQL schéma: typy, dostupná pole, vstupy a operace. Klient pak pošle query pro čtení nebo mutation pro změnu a zvolí jen potřebná pole. Server dotaz syntakticky i typově ověří, spustí resolvery a zpravidla vrátí JSON s daty, případně i se seznamem chyb.
GraphQL nestojí přímo nad tabulkami. Resolver může číst relační databázi, volat několik interních služeb, použít cache nebo složit data z externího API. Veřejné GraphQL schéma je kontrakt pro klienta, ne zrcadlo interní databázové struktury.
K čemu se používá
Když různí klienti potřebují různé pohledy na stejná data
Výběr polí je užitečný zejména pro více frontendů nebo obrazovek, které nad stejným doménovým modelem zobrazují odlišný detail.
- webová a mobilní aplikace čtou objednávky s jiným rozsahem detailu
- administrace skládá přehled z objednávek, zákazníků a stavů synchronizace
- frontend si jedním dotazem načte data potřebná pro konkrétní obrazovku
- mutace vytváří nebo mění business objekty přes typovaný vstupní kontrakt
- interní API postupně vyvíjí schéma bez nutnosti vystavovat tabulky přímo klientům
Praktický příklad
Detail objednávky bez zbytečných polí
Frontend administrace potřebuje zobrazit číslo objednávky, stav, jméno zákazníka, položky a celkovou cenu. Dotaz výslovně vybírá tato pole; server před jejich vrácením ověří, že aktuální uživatel smí objednávku v dané organizaci číst.
Ukázka neznamená, že pole customer nebo items jsou veřejná pro každého. Resolver nebo společná autorizační vrstva musí vynutit stejná pravidla jako u REST endpointu. Citlivé údaje se do schématu nezařazují jen proto, že je interně obsahuje databáze.
GraphQL a JSON
query OrderDetail($id: ID!) {
order(id: $id) {
number
status
customer { displayName }
items { quantity productName totalPrice }
totalPrice
}
}
{"id":"ord_42"}Jak funguje
Textový diagram: klientský dotaz → schéma → resolvery → autorizovaná data → JSON odpověď
Schéma vymezuje veřejný kontrakt; jednotlivé resolvery pak rozhodují, odkud data vezmou a zda je smí vrátit.
- Schéma popisuje kontrakt Typy určují dostupná pole, jejich vstupy a nullabilitu. Introspection může klientům pomoci kontrakt poznat, pokud ji provozovatel vědomě zpřístupní.
- Klient sestaví operaci Query vybírá data, mutation žádá změnu a proměnné nesou hodnoty odděleně od textu dotazu. Fragment dovolí znovu použít výběr polí.
- Server operaci validuje Kontroluje syntaxi, existenci polí, typy vstupů a limity. Validní GraphQL ještě neznamená, že je požadavek oprávněný nebo levný.
- Resolvery načtou a zkontrolují data Resolver může pracovat s databází či službou, ale musí řešit autorizaci, chyby a efektivní načtení souvisejících objektů.
- Odpověď nese data i chyby Část dat může být úspěšná, zatímco jiné pole skončí chybou. Klient proto nevyhodnocuje jen HTTP status, ale i strukturu odpovědi.
Důležité pojmy
Typy a resolvery dávají výběru polí pravidla
Dobrý kontrakt je srozumitelný klientovi a současně neschovává provozní pravidla jen do implementace.
Query, mutation a subscription
Query čte data, mutation vyjadřuje změnu. Subscription může oznamovat průběžné změny, ale pro přenos často používá WebSocket nebo jiný mechanismus a potřebuje stejnou autorizaci.
Typ, pole a nullabilita
Typ určuje tvar kontraktu, pole poskytuje konkrétní hodnotu a nullabilita říká, zda může hodnota chybět. Není to totéž co databázový sloupec či tabulka.
Resolver
Resolver je kód, který vypočítá nebo načte hodnotu pole. Jeden resolver může spojit více zdrojů, proto musí mít rozumné limity a sledovat počet dalších volání.
Proměnná a fragment
Proměnné nesou vstupní hodnoty odděleně od struktury dotazu. Fragment pomáhá sdílet opakovaný výběr polí; ani jeden mechanismus nenahrazuje validaci business pravidel.
Introspection a vývoj schématu
Schéma lze strojově zkoumat a postupně rozšiřovat. Zastaralé pole je vhodné označit jako deprecated a odstranit až po řízené migraci klientů.
Vztah k podobným pojmům
GraphQL neříká, jak ukládat data ani jak implementovat backend
Stejná aplikace může používat GraphQL pro některé klienty a REST, webhooky nebo fronty pro jiné integrační potřeby.
- GraphQL a REST API
- REST typicky rozděluje operace do endpointů a pracuje s HTTP zdroji. GraphQL nabízí typované schéma a výběr polí v operaci. Ani přístup není univerzálně lepší.
- GraphQL a SQL
- GraphQL dotazuje veřejné API, SQL relační databázi. Resolver může SQL používat, ale klientský GraphQL dotaz nesmí dostat neomezenou moc nad interní databází.
- Schéma GraphQL a schéma databáze
- GraphQL schéma popisuje, co API slibuje klientovi. Databázové schéma popisuje uložené objekty a vztahy; obě se mohou a často mají lišit.
- Subscription a WebSocket
- Subscription popisuje semantiku odběru změn. WebSocket je jeden možný obousměrný transport; implementace může používat i jinou technologii.
Výhody a omezení
Přesný výběr dat výměnou za náročnější řízení nákladů a oprávnění
Přínosy
- jedna operace může dodat data pro konkrétní obrazovku bez nadbytečných polí
- typované schéma usnadňuje dokumentaci, validaci a práci editorů
- lze vyvíjet kontrakt postupně přidáváním polí a deprecací starších
- sjednocuje přístup k více zdrojům dat za jeden veřejný kontrakt
Časté chyby
- zaměnit GraphQL za přímý přístup k databázi
- spoléhat na to, že výběr polí automaticky řeší N+1 a výkon
- autorizovat pouze celou operaci, ale ne jednotlivé objekty nebo citlivá pole
- povolit neomezenou hloubku, šířku či cenu dotazů
- považovat HTTP 200 za úspěch, i když odpověď obsahuje GraphQL chyby
Kdy jej použít
Když se vyplatí dlouhodobě spravovat bohatý kontrakt pro více klientů.
GraphQL může sedět administraci a více frontendům, které používají stejné doménové objekty, ale na každé obrazovce potřebují jiný výřez. Přínos roste s kvalitou schématu, rozumným modelováním mutací a schopností provozovat dotazové limity, monitoring a autorizaci.
Pro malou integrační operaci s jasným HTTP zdrojem může být REST endpoint jednodušší na pochopení, cache i provoz. GraphQL není náhrada za databázový model, dokumentaci chybových stavů ani rozhraní pro asynchronní události.
Na co myslet
Veřejné schéma je produktové i bezpečnostní rozhraní.
Důležité jsou limity, dohledatelnost a autorizační pravidla blízko dat, nikoli pouze pohodlný výběr polí na klientovi.
- modelovat typy a mutace podle doménového významu, ne jako přímé tabulky
- ověřovat oprávnění na úrovni operace, objektu a citlivého pole
- měřit dobu resolverů, počet načtení a nákladnost dotazu; řešit N+1 batchingem nebo vhodným načítáním
- omezit hloubku, složitost, velikost vstupů a případně používat uložené či povolené operace
- verzovat kontrakt evolučně: přidávat, označovat deprecated a teprve potom bezpečně odstraňovat
Časté otázky
GraphQL bez zkratkovitých slibů
Je GraphQL náhradou za REST?
Ne nutně. Je to jiný způsob návrhu API kontraktu. V jednom systému mohou vedle sebe dávat smysl GraphQL pro frontend, REST pro partnerskou integraci a webhook pro oznámení události.
Je GraphQL databázový jazyk?
Není. Dotazuje veřejné API schéma. Resolver může sahat do databáze, ale server určuje, která data jsou dostupná a jak se načítají.
Odstraňuje GraphQL N+1 problém?
Ne automaticky. Naivní resolver může při každém řádku spustit další dotaz. Je potřeba měřit a použít vhodné dávkování, eager loading nebo jiné strategie.
Znamená HTTP 200 vždy úspěch GraphQL operace?
Ne. Odpověď může obsahovat částečná data a pole errors. Klient musí umět pracovat s kontraktem odpovědi, nejen s transportním statusem.
Jak navrhuji API v praxi
API kontrakt vážu na doménový význam, oprávnění a provozní limity.
Při návrhu integrací řeším data, kompatibilitu, chyby, výkon dotazů i serverové ověření konkrétního přístupu — bez ohledu na to, zda transport používá REST nebo GraphQL.