GraphQL — co to je, dotazovací jazyk a použití v mobilních projektech

Co je GraphQL?

GraphQL — je specifikace a runtime prostředí pro API, které dává klientovi plnou kontrolu nad přijímanými daty. Vyvinutá inženýry Facebooku pro řešení problémů mobilní aplikace News Feed, specifikace byla zveřejněna jako otevřený standard v roce 2015. Od roku 2018 je GraphQL pod správou GraphQL Foundation s podporou Linux Foundation a společností jako Apollo, AWS, GitHub, SAP a dalších.

Na rozdíl od REST, kde každý endpoint vrací pevnou strukturu dat, GraphQL používá jediný endpoint, který přijímá řetězec dotazu. Klient v dotazu popíše, která pole potřebuje, a server vrátí právě ta. Například dotaz { user(id: „1”) { name email } } vrátí pouze name a email uživatele, bez nadbytečných polí jako address, phone nebo createdAt, která by bylo nutné získávat v REST.

GraphQL není vázán na žádnou konkrétní databázi nebo jazyk. Specifikace definuje pouze formát dotazů a odpovědí. Existují serverové implementace v Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) a dalších jazycích. Klientské knihovny jsou k dispozici pro všechny hlavní platformy, včetně Apollo Client pro iOS, Android a web.

Jak GraphQL funguje

Architektura GraphQL se skládá ze tří klíčových komponent: schéma (Schema), resolvery (Resolvers) a spouštěcí engine (GraphQL Engine). Schéma určuje, jaké typy dat jsou k dispozici, jaké dotazy lze provádět a jaké argumenty přijímají. Resolvery jsou funkce na serveru, které vracejí data pro každé pole schématu. Spouštěcí engine přijme příchozí dotaz, ověří jej proti schématu, zavolá příslušné resolvery a sestaví odpověď.

Proces zpracování dotazu vypadá takto:

• Klient odešle požadavek POST na /graphql s JSON tělem { „query”: „...” }
• Server parsuje dotaz, vytvoří AST (Abstract Syntax Tree) a ověří jej proti schématu
• Engine prochází AST, volá resolvery pro každé pole a shromažďuje data
• Odpověď je vrácena ve formátu JSON, přesně odpovídající struktuře dotazu

Klíčovou výhodou architektury GraphQL je rozlišování na úrovni polí. V REST vývojář buď získá všechna pole zdroje (možná s nadbytkem), nebo se uchýlí k rozšířením jako ?fields=name,email. V GraphQL je takové filtrování zabudováno do jazyka: každý dotaz explicitně specifikuje, která pole jsou potřeba, a server vrátí právě ta. To je obzvláště důležité pro mobilní aplikace, kde objem přenášených dat přímo ovlivňuje rychlost načítání a spotřebu dat.

Query, Mutation a Subscription

GraphQL definuje tři typy operací, z nichž každá odpovídá určitému scénáři interakce. Query — pro čtení dat, analogické GET v REST. Mutation — pro změnu dat (vytváření, aktualizace, mazání), analogické POST/PUT/DELETE. Subscription — pro aktualizace v reálném čase přes WebSocket, což nemá přímou analogii v klasickém REST (vyžaduje další řešení jako WebSocket nebo Server-Sent Events).

Základní syntaxe dotazů je intuitivní:

// Jednoduchý dotaz s argumentem
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation s vrácením změněných dat
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — naslouchá aktualizacím v reálném čase
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query se provádí paralelně — všechna pole na stejné úrovni se načítají současně. To umožňuje načíst související data (uživatele a jeho příspěvky) jedním dotazem bez mnoha round-tripů. Mutation se provádí sekvenčně — mutace v jednom dotazu se provádějí jedna po druhé v pořadí deklarace. Subscription naváže trvalé spojení přes WebSocket, přes které server odesílá data při výskytu události.

Operace mohou přijímat proměnné pro oddělení dat od dotazu, direktivy (@include, @skip) pro podmíněné zahrnutí polí a fragmenty pro opětovné použití sad polí. Tyto možnosti činí GraphQL dotazy flexibilními a znovupoužitelnými, což je důležité zejména ve velkých projektech s mnoha obrazovkami a komponentami.

Schéma a systém typů GraphQL

Základem GraphQL je systém typů, který popisuje všechna možná data a operace API. Schéma (Schema) je popis typů, které může server vrátit, a dotazů, které přijímá. Schéma se píše v jazyce Schema Definition Language (SDL) a slouží jako smlouva mezi klientem a serverem. Klient může získat schéma pomocí introspekce — speciálního dotazu __schema, který vrací úplný popis API.

Příklad schématu pro blog:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Vykřičník (!) znamená non-null pole — bude zaručeně přítomno v odpovědi. Hranaté závorky [ ] označují seznam. GraphQL podporuje skalární typy (Int, Float, String, Boolean, ID), objektové typy, enum, union, interface a input-typy (pro argumenty mutací). Přísná typizace samo-dokumentuje API a umožňuje klientským nástrojům generovat kód: TypeScript typy, Kotlin datové třídy, Swift struktury.

Introspekce — jedinečná schopnost GraphQL, která v REST chybí. Klient může odeslat dotaz na schéma a získat úplný popis všech typů, polí, argumentů a direktiv. To je základem nástrojů jako GraphiQL a Apollo Studio, které automaticky generují dokumentaci a automatické doplňování pro vývojáře. Introspekce také umožňuje psát automatické testy kontrolující shodu schématu s očekávanou strukturou.

Srovnání GraphQL s REST

Výběr mezi GraphQL a REST je jednou z klíčových architektonických otázek při navrhování API. Oba přístupy mají své silné a slabé stránky a výběr závisí na konkrétních požadavcích projektu. REST vítězí v jednoduchosti a univerzálnosti, GraphQL — ve flexibilitě a efektivitě dotazů. Podívejme se na srovnávací tabulku.

Hlavní nevýhodou GraphQL je obtížnost cachování. V REST funguje HTTP caching na úrovni URL: jeden požadavek na /api/users/42 vždy vrátí stejnou strukturu a odpověď lze cachovat podle URL. V GraphQL jdou všechny požadavky na jeden endpoint, struktura odpovědi závisí na těle požadavku. K řešení tohoto problému používá Apollo Client normalizovanou cache na straně klienta, která rozděluje odpovědi na samostatné entity podle id a automaticky je aktualizuje při přijetí nových dat.

Dalším důležitým aspektem je problém N+1. Při dotazování na vnořená data (například příspěvky uživatele a komentáře ke každému příspěvku) může GraphQL provést samostatný SQL dotaz pro každý prvek seznamu. Řeší se pomocí DataLoader — nástroje pro dávkování a cachování databázových dotazů, který seskupuje jednotlivé dotazy do jednoho dávkového. V REST je tento problém méně výrazný, protože vývojář kontroluje strukturu odpovědi na serveru.

Příklady GraphQL dotazů

Podívejme se na praktické příklady použití GraphQL v mobilní aplikaci v Kotlin s Apollo Client. Příklady demonstrují typické scénáře: načtení dat pro obrazovku profilu (query), vytvoření nového příspěvku (mutation) a přihlášení k odběru nových komentářů (subscription). Každý příklad zahrnuje jak GraphQL dotaz, tak kód na straně klienta.

Query: načtení profilu s příspěvky

Jeden GraphQL dotaz načte uživatele, jeho poslední příspěvky a celkový počet sledujících. V REST by bylo potřeba alespoň 2-3 požadavky: /users/42, /users/42/posts, /users/42/stats. GraphQL je spojí do jednoho round-tripu, čímž zkracuje dobu načítání obrazovky na pomalých připojeních.

// GraphQL dotaz (v souboru .graphql)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Volání na klientovi (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: vytvoření nového příspěvku

Mutace nejen vytvoří zdroj, ale také vrátí jeho aktuální data pro aktualizaci UI. Pole __typename používá Apollo Client k normalizaci cache — klient automaticky aktualizuje záznam Post v cache při úspěšné odpovědi mutace.

// GraphQL mutace
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Volání mutace s input typem
val input = CreatePostInput(
    title = "Nový příspěvek o GraphQL",
    content = "GraphQL zjednodušuje práci s API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Důležitou výhodou GraphQL oproti REST v kontextu mobilního vývoje je automatické generování kódu. Apollo Client pro Kotlin (Apollo GraphQL) generuje typově bezpečné třídy ze souborů .graphql ve fázi sestavení. Pokud server změní schéma, projekt se nesestaví, dokud nejsou dotazy aktualizovány. Tím se předchází runtime chybám typickým pro REST, kde změna struktury odpovědi může během vývoje zůstat nepovšimnuta.

Ekosystém: Apollo, Relay a nástroje

Ekosystém GraphQL zahrnuje několik klíčových knihoven a nástrojů, které zjednodušují vývoj a provoz. Apollo Client — nejpopulárnější klientská knihovna podporující React, iOS, Android a Kotlin Multiplatform. Relay od Facebooku — alternativa pro React aplikace s jedinečným přístupem ke správě dat a cachování. Volba mezi Apollo a Relay závisí na platformě a požadavcích na výkon.

Na serverové straně vedou Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) a graphql-ruby. Pro vývoj schématu a testování dotazů se používá GraphiQL — interaktivní IDE integrované v prohlížeči. Apollo Studio poskytuje metriky výkonu, sledování dotazů a správu schématu pro produkční prostředí. Samostatně stojí za zmínku GraphQL Code Generator — nástroj generující TypeScript, Kotlin, Swift a Dart typy ze schémat SDL.

Pro mobilní vývoj je zvláště zajímavý Apollo Kotlin (Apollo GraphQL) — knihovna napsaná kompletně v Kotlin s podporou corutin, Flow a Multiplatform. Umožňuje používat stejné GraphQL dotazy pro Android a iOS v projektech Kotlin Multiplatform. Apollo Kotlin normalizuje cache, podporuje chyby na úrovni polí (partial errors) a automaticky generuje datové modely ze souborů .graphql. To činí GraphQL preferovanou volbou pro velké mobilní projekty, kde je důležitá rychlost vývoje a typová bezpečnost.