Dijagram sustava često nastaje u trenutku jasnoće: nekoliko okvira, nekoliko strelica i zajednički osjećaj da svi napokon razumiju kako se aplikacija uklapa u cjelinu. Zatim se sustav promijeni. Doda se predmemorija, pojavi se pozadinski radnik, API dobije drugog potrošača, a jedna tablica baze podataka postane tri. Dijagram ostaje netaknut jer se njegovo ažuriranje čini manje hitnim od isporuke sljedeće funkcionalnosti.

Tako dokumentacija arhitekture postaje dekorativna. Tehnički je prisutna, povremeno korisna i sve više nepovezana sa sustavom koji razvojni programeri zapravo održavaju.

Živa dokumentacija arhitekture zauzima drukčiji pristup. Ona arhitekturno znanje tretira kao nešto što se razvija zajedno s kodom, implementacijom, operativnom praksom i odlukama tima. Cilj nije dokumentirati svaki detalj implementacije. Cilj je sačuvati odluke i granice koje ljudima pomažu sigurno mijenjati sustav.

Statični dijagrami ne uspijevaju iz predvidljivih razloga

Jedan dijagram na visokoj razini ne može odgovoriti na svako arhitekturno pitanje. Može pokazati da PHP aplikacija komunicira s PostgreSQL-om i Redisom, ali ne i jesu li zapisi sinkroni, koja usluga posjeduje dio podataka ili što se događa kada potrošač reda nije dostupan.

Problem je rijetko u tome što timovi ne cijene dokumentaciju. Češće je dokumentaciju preskupo održavati ili je preopširna da bi bila korisna. Dijagram koji se održava u alatu za dizajn može zahtijevati zaseban tijek rada, poseban pristup i nekoga tko pamti svaku nedavnu promjenu. Pod pritiskom isporuke, gubi.

Dokumentacija također zastarijeva kada pokušava obuhvatiti pogrešnu razinu detalja. Dijagram koji sadrži svaki kontroler, tablicu i spremnik teško je čitljiv i gotovo sigurno će se udaljiti od stvarnog stanja. Arhitektura bi trebala objasniti važnu strukturu, a ne grafički reproducirati repozitorij.

Dokumentirajte odluke, granice i putove promjena

Najtrajnija arhitekturna dokumentacija odgovara na praktična pitanja. Gdje zahtjev ulazi? Koja komponenta posjeduje poslovno pravilo? Koja je baza podataka izvor istine? Što može neovisno zakazati? Kako se promjena implementira i poništava?

Za tipičan PHP pozadinski sustav to može značiti dokumentiranje granice između HTTP koda za isporuku i aplikacijske logike. Kontroler bi trebao prevesti zahtjev u aplikacijsku naredbu, dok klasa slučaja upotrebe koordinira provjeru valjanosti, trajnu pohranu i događaje. Točni nazivi direktorija manje su važni od smjera ovisnosti.

final class CreateInvoiceController
{
    public function __invoke(Request $request, CreateInvoice $createInvoice): Response
    {
        $invoice = $createInvoice(
            new CreateInvoiceCommand(
                customerId: $request->get('customer_id'),
                amount: $request->get('amount')
            )
        );

        return new JsonResponse(['id' => $invoice->id()], 201);
    }
}

Taj mali primjer prenosi arhitekturni izbor: HTTP aspekti ne pripadaju unutar tijeka rada s računima. Kada potrošač reda, CLI naredba ili interni API kasnije trebaju izraditi račun, mogu koristiti istu aplikacijsku granicu bez simuliranja HTTP zahtjeva.

Živi dokument trebao bi jasno navesti taj izbor, uključujući iznimke. Ako naslijeđeni kontroleri još uvijek sadrže poslovnu logiku, navedite to. Iskrena dokumentacija vrjednija je od idealizirane slike sustava koji ne postoji.

Držite arhitekturu blizu koda

Promjene arhitekture trebale bi biti pregledive u istom zahtjevu za spajanje kao i kod koji ih uvodi. To ne znači da svaka promjena koda zahtijeva ažuriranje dijagrama. Znači da bi značajne promjene trebale ostaviti lagan trag u repozitoriju: sažet zapis odluke, dijagram komponenti izražen tekstom ili ciljano ažuriranje operativnog priručnika.

Dijagrami temeljeni na tekstu dobro funkcioniraju jer mogu živjeti uz kod, pregledavati se u razlikama i ažurirati bez zasebnog alata. Njihova vrijednost nije u tome što je tekst nadmoćan vizualima; nego u tome što je put održavanja kratak.

Browser -> PHP API
PHP API -> PostgreSQL
PHP API -> Redis
PHP API -> Queue
Worker -> Queue
Worker -> Email provider

Čak i ovaj jednostavan prikaz postaje korisniji uz nekoliko napomena: PostgreSQL posjeduje stanje računa, Redis sadrži potrošne podatke predmemorije, red prenosi posao obavijesti koji se može ponoviti, a pružatelj e-pošte vanjska je ovisnost s obradom pogrešaka.

Koristite zapise odluka za “zašto”

Kod pokazuje što sustav sada radi. Zapis odluke objašnjava zašto je donesena važna odluka i koji je kompromis prihvaćen. Neka ti zapisi budu kratki. Koristan zapis obično uključuje kontekst, odluku, posljedice i datum prihvaćanja.

Primjerice, tim može zabilježiti da izrada računa ostaje sinkrona jer pozivatelj prije nastavka mora primiti konačni identifikator, dok je dostava e-pošte asinkrona jer privremeni kvarovi pružatelja ne bi smjeli blokirati transakciju. Ta razlika sprječava da buduće “poboljšanje performansi” premjesti pogrešan posao u red.

Zapisi odluka ne bi trebali postati ceremonija za imenovanje varijabli ili reorganizaciju mapa. Sačuvajte ih za izbore koji utječu na pouzdanost, vlasništvo, sigurnost, implementaciju, konzistentnost podataka ili buduće mogućnosti.

Učinite ponašanje tijekom izvođenja vidljivim

Arhitektura nije samo skup komponenti. Ona je i ponašanje u normalnim i neuobičajenim uvjetima. Tijek zahtjeva može izgledati jednostavno dok se ne pojave istek vremena baze podataka, duplicirana poruka, neuspješna implementacija ili promašaj predmemorije.

Dokumentirajte važne putove neuspjeha. Ako radnik ponovno pokušava izvršiti poslove, definirajte gdje se nalaze ograničenja ponovnih pokušaja i odgoda. Ako povratni poziv plaćanja može stići dvaput, navedite ključ idempotentnosti i ograničenje baze podataka koje ga štiti. Ako Redis nije dostupan, navedite smanjuje li API funkcionalnost elegantno, zaobilazi li čitanja iz predmemorije ili odbija zahtjev.

Ovi su detalji posebno važni kada je uključen Docker. Lokalno okruženje docker compose može programerima pokazati koje su usluge potrebne i kako se povezuju, ali ne bi trebalo podrazumijevati produkcijska jamstva koja ne postoje. Zasebno dokumentirajte provjere stanja, varijable okruženja, trajne volumene i ovisnosti pri pokretanju od pretpostavki o produkcijskom orkestratoru.

• Opišite vlasnika i izvor istine za svaki važan skup podataka.
• Navedite koje su operacije sinkrone, a koje se stavljaju u red.
• Zabilježite ponašanje ponovnih pokušaja, vremenskih ograničenja i idempotentnosti za vanjske interakcije.
• Povežite korake implementacije i vraćanja prethodne verzije s komponentama na koje utječu.

Pregledavajte arhitekturu kroz promjenu, a ne ceremoniju

Najbolje vrijeme za ažuriranje dokumentacije arhitekture jest kada tim već ima relevantan kontekst: tijekom implementacije i pregleda koda. Praktično pitanje za pregled jednostavno je: je li ova promjena stvorila novu ovisnost, izmijenila granicu povjerenja, premjestila vlasništvo nad podacima, uvela način neuspjeha ili promijenila ponašanje implementacije?

Ako je odgovor da, ažurirajte najmanji koristan artefakt. Dodavanje replike za čitanje može zahtijevati napomenu o komponenti i zapis odluke. Promjena indeksa upita može zahtijevati samo migraciju i dokumentaciju usmjerenu na performanse blizu upita. Ne zaslužuje svaka promjena dijagram.

Pregledi arhitekture također imaju koristi od brisanja. Uklonite dijagrame koji dupliciraju bolju dokumentaciju, zamijenite nejasne stranice preciznijima i označite poznate netočnosti dok se ne mogu ispraviti. Manji skup pouzdanih dokumenata bolji je od velikog arhiva neizvjesnosti.

Dokument je zajednički model

Živi dokument arhitekture nije uglađen artefakt izrađen nakon što je stvarni posao završen. On je dio inženjerskog sustava: zajednički model koji programerima pomaže razmišljati o posljedicama prije nego što naprave promjenu.

Kada se dokumentacija razvija sa softverom, uvođenje novih članova postaje brže, incidente je lakše istražiti, a tehničke rasprave postaju konkretnije. Sustav će se i dalje mijenjati na iznenađujuće načine. Razlika je u tome što tim ima pouzdano mjesto za bilježenje onoga što se promijenilo, zašto se promijenilo i što sljedeći put mora ostati istinito.