Quelltext der Seite První unit test bez zbytečného strachu: praktický postup

Dokumentace REST API často bývá tím posledním, na co vývojáři myslí. Přitom právě ona rozhoduje o tom, jak rychle frontend pochopí možnosti backendu a jak bez chyb je využije. Dobře vedená dokumentace není luxus, ale nástroj, který šetří hodiny práce oběma stranám. Než začnete psát, ujasněte si, kdo bude dokumentaci číst – frontend vývojář, který nezná interní strukturu vašeho systému. Pište tedy srozumitelně, strukturovaně a hlavně konkrétně.<br><br>Dobrá dokumentace by měla obsahovat i ukázkové scénáře použití. Místo izolovaných příkladů ukažte, jak jednotlivé endpointy spolupracují při řešení typické úlohy – třeba jak načíst seznam položek, přidat novou, upravit ji a smazat. To pomáhá frontendu pochopit kontext a návaznosti. Nezapomeňte také na popis stránkování, filtrování a řazení, pokud je API podporuje – frontend pak nemusí vymýšlet vlastní řešení. V neposlední řadě myslete na to, že dokumentace by měla být snadno prohledávatelná. Používejte konzistentní názvy, členění do sekcí a klíčová slova. Vyhněte se zdlouhavým úvodům a marketingovým frázím – jde o technický manuál, ne o prodejní text.<br><br>Časté chyby a jak je odstranit Jednou z typických chyb je dynamické sestavování dotazů pomocí řetězců, zejména když potřebujete řadit podle sloupce zvoleného uživatelem. Pokud uživatel může ovlivnit název sloupce nebo směr řazení, parametrizace nepomůže. V takovém případě vždy použijte seznam povolených hodnot, který ověří, že zadaný řetězec odpovídá skutečnému názvu sloupce. Druhou častou chybou je zapomínání na vstupy vstupující do LIKE, IN nebo ORDER BY klauzulí. I zde platí, že místo přímého vkládání vstupu použijte placeholder a pro dynamické části aplikujte whitelist.<br><br>Nezapomínejte na časté a malé commity. Každá logicky ucelená změna by měla být samostatným commit s výstižným popiskem. To usnadňuje revizi, ale i případný reverz. Vyhněte se commitům typu „oprava překlepu" – ty patří do předchozího commitu. Ideální je, když každý commit představuje jednu funkcionalitu nebo opravu, kterou lze samostatně nasadit. Tím se snižuje riziko, že při slučování větví vezmete i nechtěné změny.<br><br>Verzování a změny: jak dokumentaci udržet živou REST API se vyvíjí, a proto je nutné dokumentaci verzovat. Kořte se vždy k verzi API, kterou používáte, a při změnách jasně označte, co je nové, co je změněné a co je odstraněné. Zavedte pravidlo, že každá změna v kódu backendu, která ovlivní rozhraní, musí mít odpovídající změnu v dokumentaci – jinak dokumentace rychle zastará a stane se nepoužitelnou. Užitečné je uvádět i datum poslední aktualizace a možnost porovnat verze. Typickým problémem je, že dokumentace popisuje staré endpointy, které už nefungují, nebo naopak neobsahuje nově přidané funkce. Proto dokumentaci pravidelně kontrolujte a testujte – ideálně přímo z dokumentace.<br><br>Základním stavebním kamenem je popis každého endpointu. Uveďte jeho HTTP metodu, cestu a účel – co dělá, jaká data přijímá a co vrací. Nezapomeňte na příklady požadavků a odpovědí, a to včetně hlaviček a stavových kódů. Často se stává, že dokumentace obsahuje jen příklady úspěšné odpovědi, ale chybí popis chybových stavů. Přidejte proto tabulku možných chyb – proč k nim dochází, jak vypadá tělo odpovědi a jak by na ně měl frontend reagovat. Typickou chybou je také opomenutí autentizace – popište, jak se token předává, kdy expiruje a co se stane při neplatném přístupu.<br><br>Prakticky to vypadá tak, že pro funkci, která sčítá dvě čísla, napíšete test, který ověří součet kladných čísel, ale také součet se záporným číslem a součet s nulou. Každý scénář by měl být samostatný test. Tím získáte přehled o tom, který konkrétní případ selhává. Mnoho začátečníků dělá chybu, že testy píší až po dokončení funkce a snaží se pokrýt všechno najednou. Lepší je psát testy průběžně, klidně dřív než samotnou implementaci – pak vám testy ukazují, co má funkce dělat.<br><br>Dalším důležitým prvkem je jasná definice datových modelů. Místo dlouhých popisů v textu použijte schémata – třeba ve formátu JSON – a vysvětlete, co který atribut znamená, jaký má typ a zda je povinný. Rozlišujte mezi tím, co backend přijímá od klienta a co vrací. Často se stává, že pole mají v požadavku a odpovědi různé názvy nebo že některé atributy jsou vypočítávané a frontend je nemůže měnit. Tuto asymetrii vždy zdůrazněte. Praktickým tipem je uvádět i validace – jaké hodnoty jsou povolené, jaké délky řetězců, jaké rozsahy čísel. Frontend tak nemusí hádat, proč server vrací chybu.