Co je GraphQL

Co je GraphQL a proč vznikl

GraphQL je dotazovací jazyk pro API a runtime pro plnění těchto dotazů pomocí dat z vašich zdrojů. Vznikl jako odpověď na limity tradičního REST přístupu, zejména na problémy over-fetchingu (přenášíme více dat, než klient potřebuje) a under-fetchingu (musíme volat více endpointů, abychom seskládali požadovaný tvar dat). GraphQL dává klientovi možnost deklarativně specifikovat přesný tvar výsledku, a tím zjednodušuje vývoj front-endu, optimalizuje přenosy a urychluje iterace.

Jádro GraphQL: schéma, typy a resolvery

• Schéma definuje kontrakt mezi klientem a serverem. Popisuje typy, pole, vztahy a operace Query, Mutation a Subscription.
• Typy: skalární (Int, Float, String, Boolean, ID), Object, Interface, Union, Enum, Input a List. Vše je striktně typované a introspektivní.
• Resolver je funkce, která naplní dané pole daty. Resolver může číst z DB, volat REST/GRPC služby, cache či jiné zdroje. Skládáním resolverů vzniká datový graf.

Operace: Query, Mutation, Subscription

• Query: čistá čtení bez vedlejších efektů. Klient přesně určí strukturu, včetně vnořených vazeb a argumentů.
• Mutation: změnové operace (vytvoření, update, smazání). Vrací stav po změně (např. nově vytvořený objekt), což usnadňuje synchronizaci UI.
• Subscription: stream událostí v reálném čase (typicky přes WebSocket). Užitečné pro notifikace, dashboardy, collaborative scénáře.

Transport a protokol

GraphQL je agnostický na transport, ale nejběžnější je HTTP s POST (lze i GET pro cacheovatelné dotazy). Subscriptions typicky používají WebSocket. V praxi se uplatňují konvence jako GraphQL-over-HTTP (hlavičky, status kódy) a operationName pro více operací v jednom dokumentu.

Výhody oproti REST

• Přesné dotazy: klient dostane jen to, co chce (méně dat, méně requestů).
• Jedno endpointové API: místo mnoha REST endpointů je typicky /graphql. Snižuje to režii správy verzí a dokumentace.
• Silné typování + introspekce: nástroje mohou generovat typy a klientské SDK, zlepšuje se DX (developer experience).
• Evoluce bez verzí: rozšiřováním schématu o nová pole se vyhneme verzování URL; odstranění polí je řešeno deprecací.
• Kompozice dat: agregace dat z více zdrojů v jednom dotazu bez orchestrace na klientovi.

Kdy REST dává stále smysl

• Jednoduché CRUD služby s jasnými zdroji a silnou závislostí na HTTP cache a status kódech.
• Vysoká cacheovatelnost na CDN (GET na konkrétní URL s ETag/Last-Modified), statické API.
• Integrace s legacy systémy, auditem a bezpečnostními kontrolami vázanými na REST rozhraní.

Modelování schématu a doménový návrh

Dobré schéma je zrcadlo domény, ne databázového modelu. Doporučení:

• Doménové typy místo generických „DTO“ objektů.
• Input typy pro mutace (jasně určují, co lze měnit).
• Rozhraní (Interface) a Unie (Union) pro polymorfismus a variantní struktury.
• Deprecation pro řízené odstraňování starých polí a operací.

Pagination, filtrování a třídění

Dvě dominantní strategie:

• Offset/limit: snadné, ale trpí na změny v datech a výkon na velkých offsetech.
• Cursor-based (Relay): stabilnější, výkonnější. Využívá edges, node, cursor, pageInfo.

Filtrace a sortování se modelují jako argumenty polí; složitější dotazy mohou používat input objekty.

N+1 problém a DataLoader

Protože resolvery běží po polích, hrozí mnoho malých dotazů do DB (N+1). Řešení:

• Batching a caching na úrovni požadavku (např. DataLoader) pro sloučení několika findById do jednoho findByIds.
• Projekce a joiny na DB vrstvě, případně materializované pohledy.

Cache a výkon v GraphQL

• HTTP cache je obtížnější
• Dotazy nejsou vázané na URL – proto se používají Persisted Queries a Automatic Persisted Queries (APQ): klient posílá hash dotazu, který CDN/API Gateway může cacheovat.
• Response caching na poli či resolveru (krátká TTL, stale-while-revalidate), případně fragment-level caching na klientu.
• CDN na edge s pravidly podle operationName a proměnných.

Bezpečnost: limity, autorizace, ochrana schématu

• Rate limiting a throttling na gateway vrstvě; depth/complexity limiting (max hloubka dotazu, skórování polí).
• Autorizace: field-level kontrola (directivy, middleware), record-level pravidla a attribute-based access.
• Disable/guard introspection na produkci (nebo jen pro privilegované klienty), ochrana proti introspection leaks.
• Input validation a allow-list dotazů (persisted queries) pro veřejná API.

Chyby a návratové kódy

GraphQL vždy vrací HTTP 200 pro syntakticky validní GraphQL odpověď; chyby jsou v poli errors s path a extensions. Doporučuje se standardizovat error codes v extensions.code a mapovat doménové chyby (např. FORBIDDEN, NOT_FOUND, CONFLICT).

Verzování vs. evoluce schématu

• „No versioning“: přidáváme nová pole, stará označíme @deprecated a po období podpory odstraníme.
• Breaking changes se plánují s dostatečným předstihem a komunikací; automatické kontroly kompatibility (schema diff v CI).

Federace a modulární monorepo schémat

Ve větších organizacích je praktické rozdělit schéma mezi doménové týmy. Federace umožní publikovat dílčí subgraphy a skládat supergraph na gateway (entity klíče, resolves přes hranice). Alternativou je schema stitching nebo BFF (Backend for Frontend) per aplikace.

Nástroje a ekosystém

• Server: Apollo Server, GraphQL Yoga, Mercurius (Fastify), Helix; pro jiné jazyky graphql-java, Sangria (Scala), graphql-go, Strawberry/Graphene (Python).
• Klient: Apollo Client, Relay, urql; generování typů (GraphQL Code Generator), fragmenty, cache normalizace.
• Vývoj: GraphiQL/GraphQL Playground, Explorer, lint a schema validation, mocking resolverů.

Testování a kvalita

• Jednotkové testy resolverů a datových přístupů.
• Integrační testy s lokálním serverem a seedovanými daty.
• Contract testing proti schématu (operation registry, kontrola breaking changes v CI/CD).

Observabilita a monitoring

• Tracing per resolver (OpenTelemetry) – latence polí, N+1 detekce, tepelné mapy nejdražších dotazů.
• Usage analytics: kdo volá jaké operace a fragmenty (pomůže s deprecací a cleanupem).
• Operation registry a allow-list pro bezpečnost i výkon na CDN.

Integrace s REST a existujícími systémy

GraphQL často funguje jako orchestrace nad REST/GRPC – nevyměňuje všechny systémy, ale sjednocuje přístup k datům. Výhodou je evoluční migrace: nejdřív zabalíme existující endpointy resolverem, později refaktorujeme zdorje.

Best practices pro produkci

• Schema governance: vlastnictví domén, review proces, automatické kontroly kompatibility.
• Bezpečnost a limity: depth/complexity limit, query cost model, rate limiting, RLS na úrovni DB.
• Výkon: DataLoader, cache, APQ, jemnozrnná autorizace (ne v DB smyčkách), vhodné indexy.
• Dokumentace: descriptions ve schématu, generované reference, živé playgroundy s ukázkami.

Příklady typických use-case

• Komplexní front-endy (mobil/SPA), kde jeden dotaz složí dashboard z více domén.
• Produktové katalogy s bohatými vazbami (produkty, varianty, recenze, sklad, cena).
• Multi-tenant SaaS se silnou personalizací a řízením přístupů na úrovni polí.

Antivzory a časté chyby

• „Jedna mega-mutace“: obtížná autorizace a audit; dávejte menší, konzistentní mutace.
• Expozice DB modelu: schema ≠ tabulky; skrývejte technické detaily.
• Ignorování N+1: vždy plánujte DataLoader/batching.
• Bez limitů na dotaz: otevřená brána k DoS – zaveďte complexity/depth guardy.

GraphQL vs. REST: shrnutí

GraphQL brilantně řeší flexibilitu klienta, agregaci dat a rychlou evoluci kontraktu. REST exceluje v jednoduchosti, HTTP cache a jasném mapování zdrojů. V praxi se přístupy často kombinují: veřejné read-heavy API zůstává REST/HTTP cache friendly, interní BFF/federované API je GraphQL.

Závěr

GraphQL není jen „rychlejší REST“, ale jiný model interakce – klient si říká o přesná data a server se stará o jejich složení. Díky silnému typování, introspekci, federaci a bohatému ekosystému výrazně zlepšuje produktivitu týmů a uživatelskou zkušenost. Úspěch však stojí na promyšleném schématu, hlídání výkonu, bezpečnostních limitech a disciplinované správě změn.