Co se stane, když při odhadu přehlédnete skryté činnosti

Jak nastavit přístup a tajemstv

Pozor na to, jak nástroj pracuje s rozsahem závislostí. Pokud máte v monorepu balíčky, které na sobě závisí pomocí přesných verzí, každé vydání jednoho balíčku znamená, že musíte vydat i všechny závislé. To je správné, ale snadno to vede k lavinovému efektu. Řešením je používat rozpětí, například pomocí symbolu ^, ale jen tam, kde to dává smysl. U interních balíčků se často vyplatí závislost specifikovat pomocí pracovního prostoru, tedy odkazem na lokální balíček, a teprve při publikaci se nahradí konkrétní verzí. Tím se vyhnete ručnímu přepisování čísel.

Používej reálné příklady, ne vymyšlené. Vygeneruj je z běžícího serveru a vlož tak, jak skutečně vypadají, včetně zanořených objektů a prázdných hodnot. Vyhni se popisům typu „vrací seznam" bez upřesnění, co je v položce a co znamená každé pole. U výčtových hodnot vypiš všechny možné varianty a napiš, co znamenají. Frontend pak nemusí hádat a backend nemusí vysvětlovat, proč se zobrazuje nula místo názvu stavu.

Nástroje, které řeší změny a závislosti Pro monorepa se nejčastěji používají nástroje postavené na konvenčních commitech, jako je Changesets, Lerna nebo Nx. Fungují tak, že vývojář při změně přidá krátký soubor s popisem, co se změnilo a jaký typ změny to je – oprava, nová funkce, nebo breaking change. Nástroj pak při vydání sám spočítá nové verze, aktualizuje vzájemné závislosti a vygeneruje changelog. Klíčové je, že se verzování neřeší ručně, ale na základě těchto záznamů. Bez nich se dříve nebo později stane, že někdo zapomene zvýšit verzi u balíčku, který byl nepřímo ovlivněn.

Napiš pravidla, která platí pro všechny endpointy Největší čas se ztrácí na věcech, které nejsou v žádném konkrétním endpointu. Jak se předává autentizace, kdy vyprší token a co dělat při jeho expiraci, jak vypadá stránkování a řazení, jak se posílá datum a čas, jestli se čísla posílají jako řetězce, jak se zapisují peněžní částky. Tato pravidla patří do jednoho úvodu, na který se odkazuje zbytek dokumentace. Když je každý endpoint popisuje po svém, vznikají chyby, které se hledají celé hodiny, protože kód na první pohled vypadá správně.

Dokumentace REST API není popis toho, co všechno umí server. Je to pracovní nástroj pro člověka, který za týden nebo za měsíc usedne k frontendu a potřebuje vědět, co poslat a co dostane zpět. Pokud dokumentace vzniká až na konci vývoje, bývá neúplná a plná domněnek. Začni tím, že sepíšeš jeden jediný scénář: přihlášení uživatele, načtení seznamu položek, jejich úprava. Teprve z něj odvoď strukturu celé dokumentace. Většina týmů zjistí, že víc než polovinu endpointů lze popsat podle tří nebo čtyř opakujících se vzorů.

Udržuj dokumentaci vedle kódu a aktualizuj ji ve stejném kroku, ve kterém měníš endpoint. Ideálně tak, aby se generovala z definice, kterou používá i server, a tím se nemohla rozejít s realitou. Ověřuj ji tím, že podle ní napíšeš testovací volání, a to spusť. Když příklad v dokumentaci nefunguje, je to chyba jako každá jiná. Zpětná vazba od frontendu je nejcennější zdroj: když se na něco ptá dvakrát, patří to do dokumentace, ne do chatu.

Monorepo s více balíčky znamená, že v jednom repozitáři spravujete několik samostatně publikovatelných knihoven nebo služeb. Verzování takového celku je jiné než u jednoho projektu. Nejde jen o to, jaké číslo verze napsat do souboru package.json, ale hlavně o to, jak zajistit, aby se verze jednotlivých balíčků neposouvaly chaoticky a aby na sebe závislosti správně navazovaly. Pokud tohle podceníte, dřív nebo později narazíte na nekonzistentní vydání, kdy jeden balíček vyžaduje verzi druhého, která ještě neexistuje.

Nejčastější důvod, proč se spolupráce frontendu a backendu zadrhne, není technický dluh ani špatná architektura. Je to dokumentace, která buď chybí, nebo popisuje něco jiného, než API skutečně dělá. Výsledkem jsou dohady v chatu, zbytečné přepisování kódu a zpoždění, které nikdo neplánoval. Dokumentace přitom není administrativa navíc – je to nástroj, který určuje, kdo co může dělat a kdy.

Základem je rozhodnout, zda chcete verzovat všechny balíčky společně, nebo každý zvlášť. Společné verzování znamená, že při jakékoli změně se číslo verze zvedne všem balíčkům bez ohledu na to, zda se jich změna týkala. Je to jednodušší na pochopení a méně náchylné k chybám, ale vzniká spousta zbytečných vydání. Samostatné verzování je přesnější, ovšem vyžaduje nástroj, který umí sledovat, který balíček se změnil a jaký dopad to má na jeho závislosti. Bez takového nástroje se v tom dříve či později ztratíte.