Jaké jsou nejlepší praktiky pro verzi pro GraphQL schémata?

Verzování GraphQL schémat je fakt výzva, ale jsou určitý techniky, co nám fungujou. Primárně se snažíme udělat schéma co nejvíc zpětně kompatibilní, což znamená, že když něco měníme, tak přidáváme nový pole místo mazání nebo úprav starých. Například, když potřebujeme změnit typ pole, radši přidáme nový field a ten starej označíme jako deprecated. To dává lidem čas na přechod.

Co se týče deprekovaných polí, obvykle je necháváme nějakou dobu v systému – třeba 6 měsíců až rok – ale to dost záleží na konkrétní situaci a týmu. Je dobrý mít dokumentaci k těmhle změnám, aby si všichni mohli zjistit, co se mění a proč. Testy jsou samozřejmě zásadní pro ověření, že nic nezhavaruje, když měníme schéma.

A co se týče verzí? Někdy to prostě nevyhnutelně vyžaduje novou verzi API, ale snažíme se to minimalizovat a spíš pracovat s evolucí stávajícího schématu. Je to o komunikaci v týmu a plánování dopředu – když víme, že něco hodláme změnit, líp se to pak dělá.

Nástroje jako Apollo nebo GraphQL Tools nám pomáhají s generováním dokumentace a sledováním změn. Celkově je to spíš o tom mít jasnou strategii a nebát se udělat změny, když je to potřeba.

Verzování GraphQL schémat fakt může být oříšek. Místo aby se dělaly nové verze jako u REST, tak tady spíš používáme techniky jako "deprecate" pole a typy, což je fajn způsob, jak říct uživatelům, že něco je už zastaralé. Tyhle deprecated pole bychom měli nechat v schématu minimálně rok, aby měli vývojáři čas přejít na novou verzi.

Je dobrý mít ve schématu pořád dokumentaci k těm změnám, ale testy jsou rozhodně nezbytné. Vždycky po změnách radši probíhají testy, abychom si byli jisti, že nic nezhavaruje. Pro migraci dat používáme skripty nebo i nějaké nástroje na transformaci dat, to se hodí, když měníme strukturu dat.

Další věc je komunikace v týmu. Všichni by měli mít jasnou představu o tom, co se mění a proč. Tím se vyhneme zbytečným problémům. Takže shrnuto: používej deprecated pole, drž dokumentaci v aktuálním stavu a testuj pořád. To by mělo pomoct.

K verzování GraphQL schémat je dobrý přístup mít na paměti zpětnou kompatibilitu. Místo toho, abys vytvářel nové verze, doporučuji používat deprecated pole. Když něco měníš, označ to jako deprecated a ponechej to v API třeba na půl roku nebo rok. Tím dáš uživatelům čas přizpůsobit se a přejít na novou variantu. Je fajn mít jasnou dokumentaci ke změnám, aby bylo jasné, co se změnilo a co by se mělo vyhnout.

Testy jsou taky klíčový. Mít solidní testy ti pomůže udržet API stabilní při jakýchkoli změnách. Co se týče migrace dat, snaž se mít dobře promyšlený plán, jak s novými datovými strukturami pracovat a jak stará data převádět.

Celkově bych řekl, že méně je více – radši udělej změny postupně a srozumitelně, než všechno rozbít a dělat novou verzi, která pak bude komplikovanější na údržbu.