Architektura kódu

Tahle kapitola není o tom, co tvůj backend dělá, ale jak je poskládaný uvnitř — kam který kus kódu patří. Většina backendů totiž neumře na špatný algoritmus, ale na chaos: pravidla appky rozházená všude možně, jedna malá změna rozbije pět nesouvisejících věcí, a po půl roce se v tom nikdo nevyzná. Dobrá architektura tomu předchází. Vezmeme to od základních pojmů.

Pár pojmů na úvod

• Byznys logika = pravidla tvojí aplikace, ta „chytrá" část. Např. „uživatel nesmí mít víc než 3 aktivní objednávky" nebo „slevu lze uplatnit jen jednou". To je srdce appky.
• Controller (route handler) = kód, který přijme příchozí HTTP request a rozhodne, co s ním.
• Service = kód, kde žije byznys logika.
• Repository = kód, který se stará o ukládání a čtení z databáze.
• ORM = knihovna, přes kterou pracuješ s databází pomocí objektů místo psaní SQL.
• Závislost (dependency) = něco, co jeden kus kódu potřebuje k práci (např. service potřebuje repository, aby se dostal k datům).

Nelekej se, projdeme to teď na jednoduchém příměru.

Vrstvy — jako restaurace

Nejjednodušší způsob, jak backend uspořádat, je rozdělit ho do vrstev, kde každá má jednu práci. Představ si restauraci:

• Controller = číšník. Převezme od hosta požadavek, zkontroluje, že dává smysl, předá ho do kuchyně a pak donese výsledek. Sám nevaří — žádná byznys logika, žádné SQL.
• Service = kuchař. Tady se odehrává ta „chytrá" práce podle pravidel (ověř, že má uživatel místo na další objednávku, spočítej cenu se slevou). Neřeší, jak přišel požadavek (HTTP?), ani kde jsou data uložená.
• Repository = spíž. Umí jen donést a uložit data („dej mi uživatele s ID 5"). Service neřeší, jestli je za tím Postgres, nebo něco jiného.

Pravidlo, které si zapamatuj: tencí číšníci, vytížení kuchaři, hloupá spíž (thin controllers, fat services, dumb repositories). Když začneš vařit u stolu (byznys logika v kontroleru), nejde to pak znovupoužít odjinud (třeba ze zpracování fronty) ani pořádně otestovat.

Separation of Concerns — každý dělá jen svoje

Hlavní myšlenka výše má jméno: separation of concerns (oddělení starostí). Každý kus kódu má řešit jednu věc. Když jedna funkce zároveň parsuje HTTP, počítá cenu, posílá e-mail a píše do databáze, nejde ji bezpečně změnit — sáhneš na jedno a rozbiješ druhé.

Dva pojmy, které k tomu patří:

• Cohesion (soudržnost) — věci, co spolu souvisí, jsou pohromadě. Chceš ji vysokou.
• Coupling (provázanost) — jak moc jeden modul závisí na druhém. Chceš ho nízký.

Cíl: vysoká soudržnost, nízká provázanost. Každý modul dělá jednu věc pořádně a o ostatních ví co nejmíň.

Hexagonal architecture — když to chceš zatáhnout dál

Jakmile appka roste, používá se pokročilejší uspořádání (uvidíš pojmy hexagonal architecture, ports & adapters, clean architecture — je to v zásadě totéž). Myšlenka: byznys logika (doména) je uprostřed a neví vůbec nic o vnějším světě. Všechno vnější — HTTP, databáze, fronta, e-mail — jsou adaptéry, které se připojují přes porty (rozhraní = domluvený „zásuvkový" tvar).

Klíčové pravidlo (dependency rule): závislosti směřují dovnitř, k doméně. Doména nezávisí na databázi; je to naopak — databáze se přizpůsobí doméně. Výhoda: vyměníš databázi za jinou, nebo HTTP za zpracování fronty, a jádro appky se nezmění. A jádro se dá otestovat úplně bez databáze.

Ale pozor na opačný extrém. Pro malou appku jsou plné vrstvy a porty zbytečná ceremonie. Začni jednoduše (klidně controller → service → ORM) a přidávej strukturu, až když složitost reálně roste. Architektura ti má sloužit, ne být náboženství.

Kam patří byznys logika

Nejčastější chyba začátečníka: napsat pravidla appky do kontroleru nebo přímo do databázových modelů. Patří do service / doménového modelu. Dva přístupy, jak to uspořádat:

• Anemic model — entity jsou jen „pytlíky na data" bez chování a všechna logika je v service. Jednoduché a běžné, ale logika se může rozlézt do moc míst.
• Rich domain model — entita si sama hlídá svoje pravidla (objednavka.zrus() ověří, že se zrušit dá). Logika je u dat, hůř se rozteče. Je to srdce DDD (viz níže).

Ať zvolíš cokoli: byznys logika NIKDY nepatří do kontroleru ani do databázové vrstvy.

DDD-lite — pár užitečných pojmů

DDD (Domain-Driven Design) je celá filozofie návrhu kolem domény. Nemusíš ji dělat celou, ale tyhle pojmy se ti budou hodit:

• Entity — věc s identitou, která přetrvává změny (uživatel #42 je pořád ten samý, i když změní jméno).
• Value object — věc definovaná svou hodnotou, neměnná (peníze, adresa). Money(100, 'CZK'); dvě stejné částky jsou zaměnitelné, nemají vlastní identitu.
• Aggregate — skupina entit, které se mění jako celek přes jeden „hlavní" objekt (objednávku a její položky měníš jen přes Order). Drží data konzistentní.
• Ubiquitous language — kód mluví jazykem byznysu: metoda se jmenuje rezervujMisto(), ne updateRow(); třída je Faktura, ne DataRow2. Ať kód čte i člověk z byznysu.

A proč jen „lite"? Výše jsou taktické vzory DDD — stavební kameny kódu, co se hodí skoro vždy. Celé DDD má ještě strategickou vrstvu pro návrh ve velkém, když je doména složitá nebo na ní dělá víc týmů:

• Bounded context (ohraničený kontext) — hranice, uvnitř které má každý pojem jeden přesný význam. „Zákazník" ve fakturaci a „Zákazník" v podpoře jsou dva různé modely — nemíchej je do jednoho univerzálního User.
• Subdomény — co je tvoje jádro (konkurenční výhoda, tam investuj čas), co jen podpůrné a co generické (kup/použij hotové — viz Tech Choices).
• Context mapping / anti-corruption layer — jak spolu kontexty mluví a jak se jeden brání tomu, aby mu cizí model prosákl do jeho jazyka (překladová vrstva na hranici).
• Domain events — kontexty se o změnách dozvídají přes události („objednávka zaplacena"), ne sáháním si navzájem do dat (viz Messaging a outbox v Patternech).

Celé DDD je investice, která se vyplatí u složité domény a víc týmů; na obyčejnou CRUD appku je to kanón na vrabce. Proto tady bereš jen ty taktické kousky — a strategické sáhneš, až doména začne bolet.

DTO a mapování mezi vrstvami

Data nemají mít všude stejný tvar. Jinak vypadá entita v databázi (viz výše) a jinak to, co pošleš klientovi přes API. DTO (Data Transfer Object) je prostý objekt bez logiky, jehož jediný úkol je přenést data přes hranici (typicky mezi API a klientem) ve správném tvaru.

Proč nikdy neposílat klientovi přímo databázovou entitu:

1. Únik citlivých polí — entita User má i passwordHash, isAdmin. Když ji pošleš celou, vyzradíš je (bezpečnostní díra, viz Security).
2. Provázanost — API navázané na databázi se rozbije klientům při každé změně schématu (přejmenuješ sloupec → spadne mobilní appka).
3. Jiný tvar — klient často chce data jinak, než leží v databázi.

Proto se na hranici vytvoří DTO: request DTO (co přijímáš — hned ho zvaliduješ a vezmeš jen povolená pole, aby klient nepodstrčil isAdmin: true) a response DTO (co posíláš — jen pole, co má vidět). Při průchodu aplikací tak data mění tvar a mapper je mezi tvary převádí:

Pozor i tady na opačný extrém: u triviální appky můžou být tři skoro stejné tvary zbytečná byrokracie. Začni jednoduše a odděluj DTO, až ti chybějící hranice začne dělat problémy (únik polí, rozbíjení API).

Dependency Injection — předávej závislosti zvenčí

Když si nějaká třída sama vyrobí to, co potřebuje (new PostgresRepo()), je s tím napevno svázaná. Dependency Injection (DI) znamená, že jí to potřebné předáš zvenčí (typicky v konstruktoru):

// ❌ napevno svázané – v testu to nejde obejít, potřebuješ reálnou databázi
class UserService { repo = new PostgresRepo() }

// ✅ injektované – v testu předáš falešné (fake) repo, žádná databáze
class UserService { constructor(private repo: UserRepository) {} }

Výhody: snáz se testuje (podstrčíš falešnou závislost), snadno vyměníš implementaci a je jasně vidět, na čem třída závisí. Právě DI dělá hexagonální architekturu prakticky použitelnou.

Struktura složek: podle vrstev, nebo podle feature?

Malý projekt: „podle vrstev" stačí. Jak roste, „podle feature" se obvykle udržuje líp — a je to první krok k modulárnímu monolitu (níže).

Modulární monolit — hranice bez distribuovaného pekla

Mezi „jeden velký monolit, kde si všechno sahá na všechno" a „microservices přes síť" je zlatá střední cesta: modulární monolit. Je to pořád jeden nasaditelný program (jeden deploy, lokální transakce, žádná síťová režie), ale uvnitř rozdělený na moduly s tvrdými hranicemi — a každý modul (users, orders, billing) je vlastně ten bounded context z DDD výše.

Co dělá modul modulem (a ne jen složkou):

• Vlastní doména a vlastní data. Modul billing nesahá přímo do tabulek modulu orders. Když něco potřebuje, poprosí přes veřejné rozhraní druhého modulu, ne přes jeho databázi.
• Komunikace jen přes public API modulu — pár funkcí/rozhraní ven, zbytek je skrytý (private). Uvnitř si modul dělá, co chce; navenek slibuje jen to rozhraní (může ho přepsat, aniž rozbije ostatní).
• Žádné importy cizích vnitřností — orders nesmí importovat interní třídu z billing. Přesně tuhle hranici u obyčejného monolitu nikdo nehlídá, a proto se časem rozteče do „velké koule bláta".

Proč to chtít: dostaneš jasné hranice skoro jako u microservices, ale bez distribuovaného pekla — pořád máš lokální transakce, jeden deploy a snadný debug. A když jednou nějaký modul fakt potřebuješ odříznout do samostatné služby, hranici už máš hotovou: vyřízneš ho, protože nikdy nesahal cizím do dat. Proto je doporučená cesta monolit → modulární monolit → (teprve až to bolí) microservices, ne skok rovnou k microservices (viz Tech Choices).

🚩 Nejčastější podvod: „modulární monolit", kde moduly navzájem importují vnitřnosti a sdílejí tabulky. To je jen obyčejný monolit s hezčími názvy složek — hranice, kterou nikdo nevynucuje, žádná hranice není. Vynucuj ji (lint pravidla, oddělená schémata, code review), ne jen doufej.

Anti-patterny (čeho se vyvarovat)

• 🚩 Byznys logika v kontroleru / v databázovém modelu — nejde testovat ani znovupoužít.
• 🚩 God object — jedna obří třída „UserManager" o 2000 řádcích, co dělá úplně všechno.
• 🚩 Circular dependencies — A potřebuje B, B potřebuje A. Známka špatně vedených hranic.
• 🚩 Premature architecture — pět vrstev a tucet rozhraní na appku se třemi endpointy.

Failure modes — jak to dopadne, když architekturu zanedbáš

• Spaghetti kód → každá změna má nečekané vedlejší efekty, protože všechno souvisí se vším.
• Big ball of mud → žádné jasné hranice; po roce nikdo neví, kde co je.
• Over-engineering → tolik abstrakcí, že přidat jeden endpoint trvá celý den.
• Netestovatelnost → logika přilepená na HTTP a databázi → testy potřebují celý systém.

🛠️ Cvičení

1. Rozvrstvi chaos. Vezmi (klidně smyšlený) endpoint, který v jednom kuse kódu validuje vstup, počítá cenu, ukládá do databáze a posílá e-mail. Rozděl ho na controller → service → repository.
2. Injektuj závislost. Přepiš class OrderService { repo = new PostgresRepo() } tak, aby repo dostával v konstruktoru. Pak naskicuj test, kde mu předáš falešné repo bez databáze.
3. Navrhni DTO. Entita User má id, email, passwordHash, isAdmin, createdAt. Navrhni response DTO pro veřejný profil — co v něm bude a co ne a proč. A co zvaliduješ u request DTO?
4. Kam patří pravidlo? Pro „uživatel nesmí mít víc než 3 aktivní objednávky" urči, do které vrstvy logika patří a proč ne do kontroleru.
5. Anemic vs rich. Naskicuj objekt Order dvakrát: jednou anemicky (data + service zvlášť), jednou richly (order.zrus() si hlídá pravidla sám). Pojmenuj výhody a nevýhody.
6. Podle vrstev vs podle feature. Načrtni stejnou appku (users, orders, billing) v obou strukturách složek a řekni, kdy která začne být nepříjemná.

🧠 Otázky & odpovědi