Jak vytvořit GraphQL federaci v NX? Přehledný návod, jak na to

V tomto článku si ukážeme, jakým způsobem můžete vytvořit Federation gateway za pomocí monorepa v NX. Zaměříme se na jednotlivé kroky, možnosti řešení i nejčastější chyby, které vás při tvorbě mohou potkat.

Co je monorepo a Apollo Federation Gateway?

Monorepo je speciální případ repozitáře, při kterém se vyvíjí více nezávislých projektů a jejich kód se uchovává v rámci jednoho repozitáře.

Apollo Federation Gateway je architektura, která kombinuje několik rozhraní GraphQL API. S federací můžeme zodpovědně sdílet vlastnictví supergrafů napříč libovolným libovolným počtem týmů.

Jak to celé funguje?

Ve federované architektuře se jednotlivá rozhraní GraphQL API nazývají subgrafy. Z nichž se vytváří tzv. supergrafy, které používá právě gateway. Pomocí dotazů na vytvořený supergraf se mohou klienti ptát na všechny subgrafy najednou. Brána tedy slouží jako přístupový bod pro náš supergraf. Klient se může dotazovat na jakýkoliv GraphQL server, aniž by musel něco konfigurovat.

Příklad z praxe

Nyní si ukážeme příklad, jak to celé v reálu může vypadat. Představme si, že máme dvě GraphQL aplikace, které nám běží na různých portech. První bude spravovat uživatele, pojmenujeme si jí userapp, a druhá články, tu si pojmenujeme articleapp. Tyto aplikace spolu mohou navzájem komunikovat. Dále bychom měli FE aplikaci (na obrázku client), která nám představuje knihovnu. Knihovna si spravuje uživatele a články. Musí být tedy napojena na naše dvě GraphQL aplikace. To nám zajistí právě federation gateway.

Tvorba gateway

Vytvoření gateway se dá řešit dvěma způsoby. Prvním způsobem je vytvořit gateway, která má v sobě vložený objekt s položkou serviseList. Uvnitř se jen nadefinuje název aplikace a url, nad kterou aplikace poslouchá.

Toto řešení má však jednu velkou nevýhodu. Pokud nám gateway poběží a nějaká z aplikací spadne, přestane fungovat jen postižená část aplikace. Když se aplikaci podaří opravit, okamžitě po nasazení nám začne v bráně fungovat. Problém ale nastává tehdy, pokud by došlo k výpadku samotné gateway. Gateway se začne restartovat a pokusí se z aplikací stáhnout schémata (ukázka v kódu).

Problém také nastane, když nějaká z aplikací neběží. Může se stát, že se některou aplikaci nepodaří nastartovat, a je třeba ji ručně nahodit. Federation gateway se pokusí stáhnout schémata, to se jí nepodaří, protože všechny aplikace neběží, a aplikace spadne. V tu chvíli nám federation gateway vůbec neběží, a to je velký problém. My však potřebujeme, aby aplikace běžela i bez toho, aniž by byly všechny aplikace v běhu. Z tohoto důvodu je dobré použít pro implementaci druhý zmiňovaný způsob.

Použití supergrafu Druhým způsobem je použití supergrafu, který obsahuje veškerá schémata aplikací, nad kterými brána běží a na jaké url poslouchají. Apollo Federation Gateway předá objekt, který obsahuje položku supergraphSdl, a ta pak přidá obsah supergrafu ve stringové podobě.

Aplikace si při spuštění stáhne ze souboru obsah supergrafu, čímž gateway získá veškerá schémata aplikací a url adresy, které ke spuštění potřebuje, a už se dále nestará, zda aplikace skutečně běží či ne.

Postup při tvorbě Apollo Federation gateway

Nejprve jsem si vytvořil za pomocí NX workspace pro monorepo, následně jsem vytvořil dvě GraphQL aplikace a nad nimi Federation gateway, která je schopna načítat supergraph a následně si kontrolovat, zda je aktuální. Pokud zjistí, že je obsah rozdílný, než je obsah nasazeného supergrafu, server se zastaví, gateway si načte aktuální obsah a server se restartuje. K přenasazování supergrafu bylo třeba vytvořit i nějaký mechanismus, který by vytvářel nové supergrafy. K tomu jsem vytvořil separátní aplikaci, která nám supergrafy vytváří a kontroluje, zda není dostupný nový oproti aktuálnímu ve zvoleném úložišti.

Co se úložišť týče, existuje mnoho možností, kam supergrafy ukládat. Já si pro ukládání zvolil dvě místa. Jedním je lokální místo na disku a druhým je databáze. Více si k tomu však řekneme níže, kde si celý proces popíšeme.

Odkaz na celý workspace je možné stáhnout zde: https://github.com/qest-cz/gql-federtion-sample