GraphQL: zkušenosti z výroby

Píše se rok 2020. Vaše tým se stále více přiklání k vytváření jednostránkových aplikací nebo alespoň k začlenění bohatých komponent do běžných vícestránkových aplikací. Jazyk [GraphQL](https://graphql.org/) je nyní [více než dva roky](https://en.wikipedia.org/wiki/GraphQL) starý, což podle JavaScript normy ekosystému lze považovat za vyspělé. Cítili jsme se trochu odvážně, a tak jsme se vykašlali na obvyklé JSON API a vrhli se rovnou do toho - tady je, co jsme se dozvěděli.

Potřebujete server GraphQL

Ve většině rámců používaných pro vývoj webových stránek, nástroje pro vytvoření rozhraní JSON API již existují. Můžete vytvořit strukturu trasy a snadno přijímat nějaké GETy a POSTy a pak vypisovat odpověď JSON. Ruby na adrese Rails má dokonce speciální projekt přepínač nastavení, který se obejde bez obvyklých vychytávek pro vykreslování HTML a místo nich vytvoří pevný základ pro rozhraní API. Z toho vyplývá, že zkušený vývojář používající moderní nástroje může vytvořit backend doslova během několika minut.

Ne tak v případě jazyka GraphQL. I když existují serverové knihovny pro mnoho jazyků, přesto vám hned na začátku hrozí snížení rychlosti - jednoduše proto, že musíte zjistit, co je pro váš ekosystém vhodné. Z osobního hlediska se mi také nelíbí, že se pro označení knihovny, kterou lze zavést do projektu, používá termín "server".

Existuje pouze jeden koncový bod

V průběhu let jsme si zvykli na určitý způsob uvažování o struktuře API. Na nejzákladnější úrovni jsme jednoduše dodržovali postupy REST. To znamenalo vytvořit několik koncových bodů pro každý logický model naší aplikace. Je to struktura, která je snadno uchopitelná jak pro autory API, tak pro konzumenty. Vytváří také dobře skórované metody v backendu, což umožňuje uvažovat o kód stejně snadno jako o samotném rozhraní API. Tuto strukturu lze také snadno použít jako jmenný prostor, např. pro účely Verzování API.

GraphQL používá pouze jeden koncový bod, běžně /graphql. Každý požadavek na vaše rozhraní API přijde jako požadavek POST na tento koncový bod a odtud je na serveru GraphQL, aby zjistil, co klient chce, a odpovídajícím způsobem odpověděl.

Na první pohled se to zdá být těžkopádné: představte si, že se snažíte udělat všechno v rozhraní JSON API pomocí jediného koncového bodu! Brzy však začne dávat smysl, jakmile rozhraní API dozraje a některé věci budou nahrazeny jinými. V klasických API se depreciace obvykle provádí na úrovni jmenných prostorů, kdy se přechází z úrovně v1 na v2. GraphQL umožňuje mnohem větší kontrolu až po vyřazení jediného pole. Představte si, že můžete spotřebiteli rozhraní REST API říct, že nechcete, aby používal pole název pole a použít fancy_name místo toho! Ukázalo se, že to, co se zpočátku zdálo těžkopádné, je ve skutečnosti jedna z nejlepších funkcí.

Vše je napsáno na stroji

JSON nemá příliš mnoho možností psaní. Jsou zde řetězce, čísla, pole a objekty. Kromě toho máte smůlu. Naproti tomu v jazyce GraphQL všechno začíná a končí u typů, protože i kořenový dotaz a mutace jsou právě jen typy. GraphQL DSL vynucuje kontrolu typů na serveru i na klientovi, což zabraňuje nejrůznějším nepříjemným překvapením.

To je velmi důležité, zejména proto, že SPA jsou stále častěji typizovány, ať už pomocí TypeScript nebo alternativy jako Flow. GraphQL usnadňuje zavádění složitých a složených typů nad výchozími hodnotami a vývojáři na backendu i frontendu se rychle stanou druhou přirozeností.

Přečtěte si více: Testování JavaScript...s Ruby?!

Dokumenty jsou vestavěné

V klasickém rozhraní JSON API může být dokumentace dodatečně vytvořena. A i když tomu tak není, existuje spousta metod, ze kterých si můžete vybrat. Zda použijeme nějaké schéma, jako např. OpenAPI? Převedeme je pak do lidsky čitelné podoby pomocí nástrojů, jako je Swagger? Nebo prostě někam vysypeme celou řadu souborů Markdown? I když byl tento problém již několikrát vyřešen, stále vyžaduje vědomé přemýšlení a úsilí týmu - nejprve vytvořit dokumenty, pak je aktualizovat a šířit. Je to ještě složitější problém, když má API několik sekcí, které jsou přístupné např. jen určitým uživatelským rolím.

V GraphQL je dokumentace prvotřídní, protože většina serverů umožňuje dokumentovat typy a požadavky přímo na místě. Od začátku roku 2018 se součástí oficiální specifikace stal jazyk GraphQL Schema Definition Language, takže existuje přesně jeden způsob dokumentace rozhraní GraphQL API. Navíc vzhledem k tomu, že GraphQL umožňuje definovat viditelnost určitých částí grafu, uživatelé, kteří by neměli, automaticky nevidí dokumentaci toho, k čemu nemají přístup. Mít toto rozhodnutí ošetřené a jasné pokyny bylo pro tým velkým přínosem.

Existují pouze dva typy akcí

Na rozdíl od protokolů HTTP GET, POST, PUT, PATCH a DELETE existují v jazyce GraphQL pouze dva typy akcí: Dotazy a mutace. Hlavní rozdíl spočívá v tom, že Mutace mohou měnit a mění stav systému a Dotazy pouze pasivně načítají data.

Přiznám se, že jsem stále na vážkách. Líbí se mi množství sloves HTTP pro interakci se zdroji a možnost použít přesně ten správný nástroj pro danou práci. GraphQL usnadňuje péči o ty zapeklité případy, kdy se některé ze sloves HTTP přesně nehodilo, ale nese s sebou daň v podobě nutnosti přemýšlet o tom, co konkrétní mutace vlastně ovlivní. Lze také poukázat na to, že vzhledem k tomu, že ve skutečnosti neexistuje vestavěná standardní konvence pro pojmenování, budete muset vypracovat interní stylové příručky nebo riskovat, že vytvoříte nekonzistentní nepořádek.

V podstatě potřebujete klienta

Interakce s rozhraním REST API přes protokol HTTP je ve vanilkovém systému JavaScript velmi snadná, a ještě snadnější je s použitím moderního rozhraní načíst API. Naproti tomu pro GraphQL je třeba použít klientskou knihovnu, pokud chcete mít opravdu slušný výkon. Není nemožné komunikovat s rozhraním GraphQL API pouze pomocí vanilla JavaScript - jde přece jen o požadavky POST. Nicméně použití pouze dlouhodobě používaných webových technologií, jako je cachování požadavků pro běžná volání API, nebude fungovat, protože požadavky POST se obecně necachují.

Každý rozumný klient GraphQL implementuje mechanismus ukládání výsledků do mezipaměti na straně klienta a mnoho dalších funkcí. Díky všem těmto možnostem je ruční vytvoření konfigurace klienta GraphQL na základní úrovni naprosto otupující úkol. Při začátcích s jazykem GraphQL doporučuji zejména podívat se na Apollo-Boost protože je dodáván s velmi rozumnými výchozími hodnotami.

Klient vybírá data

Všichni jsme to zažili: vytáhli jsme seznam dat z rozhraní API a chybí v něm nějaké klíčové pole o souvisejícím modelu. Pak implementujeme hack, který zahrnuje N+1 požadavků, a přitom reptáme na vývojáře backendu, kteří to rychle doplňují. U dobře implementovaného rozhraní GraphQL se to obvykle nestává, protože se můžeme do dat ponořit tak hluboko, jak se nám zlíbí. Potřebujete se podívat na adresu zákazníka v objednávce v této dávce? Žádný problém - alespoň teoreticky, což hezky vede nás na...

Složitost je těžší předvídat

Při návrhu jazyka GraphQL ze strany back-endu může být obtížné přemýšlet o tom, jak hluboko může klient do grafu proniknout. Existuje mnoho způsobů, jak instrumentovat a sledovat využití grafu, a poté, co necháte své kolegy z front-endu, aby si s ním chvíli hráli, můžete začít pozorovat dlouhé dotazy, které provádějí poměrně nápadité čtení vašeho datového úložiště. V rozhraní REST API je to snadněji kontrolovatelné, protože můžete snadno určit rozsah dat, ke kterým se bude přistupovat v rámci jednoho požadavku. Často se však může stát, že tato opomenutá složitost se vám po uvolnění do produkčního provozu pořádně vymstí. Mnohokrát také není zřejmé, jak z této díry, kterou jste si vykopali, uniknout.

Číslované stránky jsou opravdu těžké

Tohle je výtka, která je ve skutečnosti jen naoko. Při pohledu na způsob, jakým funguje zamýšlený mechanismus stránkování, je rozhodně cítit, že jazyk GraphQL byl navržen pro Facebook. Takzvané Connections jsou v podstatě nekonečné proudy hran grafu, po kterých se naviguje pomocí kurzorů namísto klasičtějších stránek. Zatímco u nekonečného kanálu příspěvků ve stylu Facebooku je snadné pochopit, jak se to hodí, pokud chcete přehledně stránkovaný seznam s možností přejít například na stránku 42, budete to mít mnohem těžší. Existují samozřejmě způsoby, jak to obejít, ale to jsou právě ty způsoby, jak to obejít.

Udělali bychom to znovu?

Po všech výše uvedených výtkách a rozdílech si pravděpodobně myslíte, že GraphQL považujeme za experiment, který se zvrtl, a vrátili jsme se rovnou k rozhraním REST API. To není pravda. Pokud něco, tak se snažíme o širší využití jazyka GraphQL v projektech v celé organizaci. Je to skvělá technologie, která nám usnadnila a zlepšila práci. Zpočátku jsme však do GraphQL investovali, aniž bychom si zcela uvědomili, jakými bolestmi růstu budeme procházet.

Pokud si myslíte, že by pro vás jazyk GraphQL mohl být vhodný, doporučuji vám, abyste se do něj pustili. Dejte si dostatek času a prostoru pro bezpečné selhání a zanedlouho budete sklízet ovoce!

Přečtěte si také:

– Jak efektivně řídit vzdálené vývojáře? Průvodce pro CTO

– Python vs. Ruby? Kterou technologii byste měli použít pro vývoj produktů?

– Stručný průvodce budováním a rozvojem vlastního tržiště. Co stojí za to vědět?