Системскиот дијаграм често се раѓа во момент на јасност: неколку кутии, неколку стрелки и заедничко чувство дека сите конечно разбираат како апликацијата се вклопува во целината. Потоа системот се менува. Се додава кеш, се појавува worker во заднина, API добива втор потрошувач, а една табела во базата на податоци станува три. Дијаграмот останува недопрен бидејќи неговото ажурирање изгледа помалку итно од испорачувањето на следната функционалност.

Така архитектонската документација станува декоративна. Таа е технички присутна, повремено корисна и сè понеповрзана со системот што развивачите навистина го одржуваат.

Живата архитектонска документација применува поинаков пристап. Таа го третира архитектонското знаење како нешто што еволуира заедно со кодот, распоредувањето, оперативната пракса и одлуките на тимот. Целта не е да се документира секој детаљ од имплементацијата. Таа е да се зачуваат одлуките и границите што им помагаат на луѓето безбедно да го менуваат системот.

Статичните дијаграми не успеваат поради предвидливи причини

Еден дијаграм на високо ниво не може да одговори на секое архитектонско прашање. Тој може да покаже дека PHP апликација комуницира со PostgreSQL и Redis, но не и дали запишувањата се синхрони, која услуга поседува дел од податоците или што се случува кога потрошувач на редица не е достапен.

Проблемот ретко е во тоа што тимовите не ја ценат документацијата. Почесто, документацијата е премногу скапа за одржување или премногу широка за да биде корисна. Дијаграмот што се одржува во алатка за дизајн може да бара посебен работен тек, специјален пристап и некој што ги памети сите неодамнешни промени. Под притисок за испорака, тој губи.

Документацијата исто така застарува кога се обидува да го опфати погрешното ниво на детали. Дијаграм што содржи секој контролер, табела и контејнер е тежок за читање и речиси сигурно ќе отстапи од реалната состојба. Архитектурата треба да објаснува значајна структура, а не графички да го репродуцира репозиториумот.

Документирајте ги одлуките, границите и патеките на промени

Најтрајната архитектонска документација одговара на практични прашања. Каде влегува барањето? Која компонента го поседува деловното правило? Која база на податоци е изворот на вистината? Што може да откаже независно? Како се распоредува и враќа промена?

За типичен PHP backend, тоа може да значи документирање граница меѓу HTTP кодот за испорака и апликациската логика. Контролерот треба да го претвори барањето во апликациска команда, додека класата за случај на употреба ги координира валидацијата, перзистенцијата и настаните. Точните имиња на директориумите се помалку важни од насоката на зависностите.

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);
    }
}

Тој мал пример соопштува архитектонски избор: HTTP грижите не припаѓаат во работниот тек за фактури. Кога на потрошувач на редица, CLI команда или интерно API подоцна ќе му треба да создаде фактура, тој може да ја користи истата апликациска граница без да симулира HTTP барање.

Живиот документ треба јасно да го наведе овој избор, вклучително и исклучоците. Ако наследените контролери сè уште содржат деловна логика, кажете го тоа. Искрената документација е повредна од идеализирана слика за систем што не постои.

Држете ја архитектурата близу до кодот

Архитектонските промени треба да можат да се прегледаат во истото pull request како и кодот што ги воведува. Ова не значи дека секоја промена во кодот бара ажурирање на дијаграм. Значи дека значајните промени треба да остават лесна трага во репозиториумот: концизен запис за одлука, компонентен дијаграм изразен како текст или фокусирано ажурирање на оперативен прирачник.

Текстуалните дијаграми функционираат добро затоа што можат да живеат со кодот, да се прегледуваат во разлики и да се ажурираат без посебна алатка. Нивната вредност не е во тоа што текстот е подобар од визуелните прикази; туку во тоа што патеката за одржување е кратка.

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

Дури и овој едноставен приказ станува покорисен кога е придружен со неколку белешки: PostgreSQL ја поседува состојбата на фактурите, Redis содржи кеш-податоци што може да се отфрлат, редицата пренесува работа за известувања што може повторно да се обиде, а давателот на е-пошта е надворешна зависност со обработка на неуспеси.

Користете записи за одлуки за „зошто“

Кодот покажува што прави системот сега. Записот за одлука објаснува зошто е направен значаен избор и каков компромис е прифатен. Нека овие записи бидат кратки. Корисниот запис обично ги вклучува контекстот, одлуката, последиците и датумот кога била прифатена.

На пример, тим може да запише дека создавањето фактура останува синхроно бидејќи повикувачот мора да добие дефинитивен идентификатор пред да продолжи, додека испораката на е-пошта е асинхрона бидејќи привремените неуспеси на давателот не треба да ја блокираат трансакцијата. Таа разлика спречува идно „подобрување на перформансите“ да ја премести погрешната работа во редица.

Записите за одлуки не треба да станат церемонија за именување променливи или реорганизирање папки. Зачувајте ги за избори што влијаат на доверливоста, сопственоста, безбедноста, распоредувањето, конзистентноста на податоците или идните опции.

Направете го видливо однесувањето при извршување

Архитектурата не е само збир од компоненти. Таа е и однесување во нормални и ненормални услови. Текот на барање може да изгледа едноставен сè додека не се појават истекување на време во базата на податоци, дупликат порака, неуспешно распоредување или промашување на кешот.

Документирајте ги важните патеки на неуспех. Ако worker повторно се обидува со задачи, дефинирајте каде се наоѓаат ограничувањата за повторни обиди и backoff. Ако повратен повик за плаќање може да пристигне двапати, идентификувајте го клучот за идемпотентност и ограничувањето во базата на податоци што го штити. Ако Redis не е достапен, наведете дали API деградира грациозно, ги заобиколува читањата од кешот или го одбива барањето.

Овие детали се особено важни кога е вклучен Docker. Локална околина docker compose може да им покаже на развивачите кои услуги се потребни и како се поврзуваат, но не треба да имплицира продукциски гаранции што не постојат. Документирајте ги проверките на здравјето, променливите на околината, трајните волумени и зависностите при стартување одделно од претпоставките за продукциски оркестратор.

• Опишете ги сопственикот и изворот на вистината за секој важен збир на податоци.
• Наведете кои операции се синхрони, а кои се во редица.
• Забележете го однесувањето за повторни обиди, истекување на време и идемпотентност при надворешни интеракции.
• Поврзете ги чекорите за распоредување и враќање со компонентите врз кои влијаат.

Прегледувајте ја архитектурата преку промени, а не преку церемонија

Најдобро време за ажурирање на архитектонската документација е кога тимот веќе го има релевантниот контекст: за време на имплементацијата и прегледот на кодот. Практичното прашање при прегледот е едноставно: дали оваа промена создаде нова зависност, промени граница на доверба, премести сопственост на податоци, воведе режим на неуспех или го промени однесувањето при распоредување?

Ако одговорот е да, ажурирајте го најмалиот корисен артефакт. Додавањето read replica може да бара белешка за компонента и запис за одлука. Промената на индекс на барање може да бара само миграција и документација фокусирана на перформансите во близина на барањето. Не секоја промена заслужува дијаграм.

Архитектонските прегледи имаат корист и од бришење. Повлечете дијаграми што дуплираат подобра документација, заменете нејасни страници со поостри и означете ги познатите неточности сè додека не можат да се поправат. Помал сет доверливи документи е подобар од голем архив на неизвесност.

Документот е заедничкиот модел

Живиот архитектонски документ не е полиран артефакт создаден откако ќе заврши вистинската работа. Тој е дел од инженерскиот систем: заеднички модел што им помага на развивачите да размислуваат за последиците пред да направат промена.

Кога документацијата еволуира со софтверот, воведувањето на нови членови станува побрзо, инцидентите полесно се истражуваат, а техничките дебати стануваат поконкретни. Системот сè уште ќе се менува на изненадувачки начини. Разликата е во тоа што тимот има сигурно место да забележи што се променило, зошто се променило и што мора да остане точно следниот пат.