Když backend a frontend sdílejí jedno zadání API, ušetříte dny

Z Mazovia

Automatizujte po malých krocích a každý krok si ověřte na vzorku. Nejdřív přejmenujte pět souborů ručně spuštěným skriptem, pak teprve celou složku. Až bude skript spolehlivý, můžete ho naplánovat — ve Windows přes Plánovač úloh, na Linuxu přes cron. Do plánované úlohy vždy pište absolutní cestu k interpretu i ke skriptu, protože prostředí naplánované úlohy nemá stejné proměnné jako vaše okno terminálu. Právě tady vzniká nejvíc případů, kdy „doma to fungovalo" a v plánovači ne.

Na závěr: dokumentaci berte jako součást definice hotového, ne jako úkol na potom. Když se frontend a backend shodnou na specifikaci dřív, než se napíše první řádek klientského kódu, zmizí většina nedorozumění a opakovaných schůzek. Udržujte ji krátkou, konkrétní a generovanou z jednoho zdroje — to je celý trik.

Kde se výkon ztrácí nejčastěji Typická chyba je obalení indexovaného sloupce funkcí, například LOWER(slovo) = 'x' nebo DATE(created_at) = '2024-01-01'. Tím databáze přijde o možnost index použít. Řešte to přepsáním podmínky na rozsah, tedy created_at >= '2024-01-01' AND created_at rekonstrukce koupelny krok za krokem</a>čněte tím, že každý endpoint popíšete strojově čitelně. OpenAPI (dříve Swagger) je dnes de facto standard a většina backendových frameworků umí specifikaci generovat přímo z anotací v kódu. Pokud to váš framework neumí, pište specifikaci ručně, ale uložte ji do repozitáře vedle kódu, ne do wiki, kterou nikdo neaktualizuje. Z jedné specifikace pak vygenerujete HTML dokumentaci i klientské typy, takže frontend dostane reálné názvy polí a ne odhady.

Dokumentujte i to, co není vidět na první pohled: autentizaci a jak zařídit malou kuchyni se token obnovuje, stránkování a jeho limity, řazení, filtrování, časové formáty (doporučuji ISO 8601 v UTC), číselníky a jejich platné hodnoty. U volitelných parametrů napište, co se stane, když chybí. Typická chyba je popsat jen šťastnou cestu a zamlčet, že výchozí limit stránkování je 20 a maximum 100. Frontend pak posílá 500 a diví se prázdné odpovědi.

Častá chyba je ukládání odvozených dat. Pokud máte v store seznam položek a k tomu celkovou cenu, dříve nebo později se rozejdou. Počítejte cenu selektorem nebo při renderu. Stejně tak neukládejte stav, který lze snadno odvodit z jiného stavu nebo z props. Každé duplicitní pole je místo, kde vznikne nekonzistence. Výjimkou je situace, kdy je výpočet opravdu drahý a potřebujete ho cachovat – pak ale cache spravujte explicitně a mějte jasná pravidla, kdy se invaliduje.

Testujte na skutečném zařízení, ne jen v emulátoru. Emulátor je pohodlný, ale skrývá pomalé načítání, nedostatek paměti i rozdíly ve velikostech a rozlišeních displeje. Projděte aplikaci na malém i velkém telefonu, v tmavém režimu a při zvětšeném písmu. Právě zvětšené písmo a otočení displeje odhalí nejvíc chyb v rozložení, protože se ukáže, co se při změně rozměrů rozbije. Do projektu si od začátku pište poznámky o tom, co nefunguje, místo abyste si to pamatovali.

Pro ladění používejte nástroje, které vám ukážou historii akcí a rozdíl ve stavu. Bez toho se v produkční chybě orientujete jen podle popisu. Do vývoje přidejte middleware, který loguje akce a změny, ale v produkci ho vypněte. Pokud aplikace začne být pomalá, podívejte se nejdřív na selektory a na to, kolik komponent je napojených na store. Často stačí rozdělit velký selektor nebo přesunout lokální stav z Reduxu pryč. Redux není náhrada za návrh komponent; je to nástroj pro sdílená data a měl by zůstat co nejmenší.

Příklad místo odstavce popisu U každého endpointu uveďte konkrétní ukázkový požadavek a odpověď, včetně hlaviček a stavových kódů. Nejkvalitnější popis je „tady je vstup, tady výstup, tady chybová varianta". U více stavů použijte příklady pro úspěch, validaci (400), neautorizovaný přístup (401), nenalezeno (404) a konflikt (409). Chybové odpovědi mějte jednotné schéma s polem pro kód, zprávu a seznam chyb u validace. Frontend pak nemusí hádat, proč mu přišla jiná struktura než minule.

Používejte verzování v URL nebo v hlavičce a změny popisujte v changelogu u dokumentace. Breaking change bez oznámení je nejčastější důvod, proč si týmy přestanou věřit. Zaveďte pravidlo, že pull request, který mění chování endpointu, musí obsahovat i úpravu specifikace, jinak neprojde review. Pomáhá i jednoduchý kontraktní test v CI, který ověří, že odpověď serveru odpovídá specifikaci.