Pięć książek, jeden system: architektura od decyzji do niezawodnej produkcji

ARCCLOUD / PRACOWNIA ARCHITEKTA / 02

W czwartek wszystko działało. W piątek dwie osoby dostały ten sam termin.

Zespół dopisał integrację z magazynem, poprawił formularz i wypuścił wersję. Pipeline był zielony. Rano konsultant przyjął dwa zlecenia na tę samą ekipę. Jedno z nich miało już zarezerwowaną część, drugie zdążyło wysłać potwierdzenie klientowi. Każdy fragment kodu robił coś rozsądnego. Cały proces przestał się zgadzać.

W takich chwilach architektura przestaje być rysunkiem z prostokątami. Staje się odpowiedzią na konkretne pytania: kto może potwierdzić termin, czyja jest rezerwacja i co obiecaliśmy człowiekowi po drugiej stronie ekranu?

Wybrałem pięć książek, które pomagają przejść przez te pytania w dobrej kolejności. Zaczniemy od wymagań, zajrzymy do kodu, uporządkujemy istniejący system, a na końcu sprawdzimy, czy potrafimy utrzymać go po wdrożeniu. Każda książka wnosi inny sposób patrzenia. Łączy je odpowiedzialność za konsekwencje własnych decyzji.

Wymagania · Wzorce w kodzie · Refaktoryzacja · Granice i zdarzenia · Niezawodność · Sprawdź decyzje

01 / FUNDAMENTALS OF SOFTWARE ARCHITECTURE

Dobry projekt zaczyna się od problemu, który potrafimy nazwać.

Mark Richards i Neal Ford porządkują style architektoniczne oraz cechy jakościowe systemu. Ich punkt wyjścia jest prosty: decyzja architektoniczna ma cenę. Wybierając większą niezależność wdrożeń, możemy zapłacić trudniejszym śledzeniem błędów. Upraszczając transakcję, możemy związać część zmian jednym wdrożeniem. Książkę warto czytać jako trening uzasadniania wyborów. Opis drugiego wydania u wydawcy.

W Serwisie Północ trzy osoby rozwijają jedną aplikację. Najwięcej zgłoszeń dotyczy terminów i rezerwacji części. To wystarczający powód, żeby zacząć od reguł procesu. Sama informacja, że firma chce „nowoczesnej architektury”, nie mówi jeszcze, jakie rozwiązanie jej pomoże.

Dopiero teraz rozmowa o stylu architektury nabiera sensu. Dla tej firmy wybieramy na początek modularny monolit: jedno wdrożenie, ale jawne granice odpowiedzialności. Zyskujemy prostsze uruchomienie i możliwość użycia lokalnych transakcji. Przyjmujemy też koszt wspólnego wydania i potrzebę pilnowania zależności pomiędzy modułami.

To wybór dla opisanych warunków. Gdy harmonogram zacznie rozwijać osobny zespół albo jego obciążenie będzie wyraźnie inne od reszty aplikacji, wrócimy do tej decyzji. Dobry dokument architektoniczny zawiera również sygnał, po którym trzeba go ponownie przeczytać.

02 / PATTERNS OF ENTERPRISE APPLICATION ARCHITECTURE

Wzorzec pomaga dopiero wtedy, gdy pasuje do skomplikowania reguł.

Martin Fowler, wraz ze współautorami, opisuje powtarzające się problemy aplikacji biznesowych: organizację logiki, zapis danych czy współbieżną zmianę informacji. Starsza data publikacji nie odbiera wartości pytaniom, które stawia. W praktyce przydaje się odróżnienie prostego Transaction Script od bogatszego Domain Model oraz rozumienie granicy Unit of Work. Strona książki autora.

Załóżmy, że administracja zmienia opis stanowiska serwisowego. Walidacja uprawnień, sprawdzenie długości, zapis — prosty przypadek może pozostać prostym skryptem transakcyjnym. Nie musimy budować wokół niego rozbudowanego modelu.

Potwierdzenie naprawy jest trudniejsze. Potrzebujemy zatwierdzonej wyceny, części i ekipy. Jeżeli te warunki są sprawdzane osobno w kontrolerze, zadaniu nocnym i integracji, po kilku miesiącach dostaniemy trzy różne definicje „potwierdzonego zlecenia”. Warto zebrać regułę w jednym modelu.

public enum WorkOrderState { Draft, Confirmed }

public sealed record ConfirmationEvidence(
    bool QuoteAccepted,
    bool PartsReserved,
    bool TechnicianReserved);

public sealed class WorkOrder
{
    public WorkOrderState State { get; private set; }

    public void Confirm(ConfirmationEvidence evidence)
    {
        if (State == WorkOrderState.Confirmed) return;
        if (!evidence.QuoteAccepted || !evidence.PartsReserved ||
            !evidence.TechnicianReserved)
            throw new InvalidOperationException("Confirmation is incomplete.");

        State = WorkOrderState.Confirmed;
    }
}

Ten fragment pokazuje jedną regułę, nie gotowy proces produkcyjny. W działającej aplikacji dowód rezerwacji musi pochodzić z zaufanego kontraktu i odnosić się do właściwego zlecenia oraz wersji. Trzeba również obsłużyć wygaśnięcie rezerwacji, uprawnienia i równoległe zapisy. Trzy wartości logiczne przesłane z przeglądarki nie mogą stanowić takiego dowodu.

W teście jednostkowym potwierdzamy, że model odrzuca niepełne warunki. W teście integracyjnym uruchamiamy dwa równoległe zapisy i sprawdzamy mechanizm współbieżności w bazie. To dwa różne rodzaje pewności. Test samej klasy nie wykaże podwójnej rezerwacji wykonanej przez dwa procesy.

Unit of Work pomaga zebrać zmiany należące do jednej operacji zapisu. Nie rozciąga automatycznie transakcji na zewnętrzny magazyn, broker i serwer poczty. Tę granicę dobrze jest narysować, zanim kod zacznie ją nieświadomie przekraczać. Krótkie opisy wzorców: Transaction Script, Domain Model i Unit of Work.

03 / DOMAIN-DRIVEN REFACTORING

Najpierw rozplącz znaczenia. Potem rozdziel kod.

Alessandro Colla i Alberto Acerbis pokazują zastosowanie DDD do systemu, który już istnieje: od języka domeny i kontekstów po zmianę struktury oraz bazy danych. Ważny jest sam kierunek pracy — poprawianie granic stopniowo, przy zachowaniu działającego produktu. Modularny system może być dobrym wynikiem refaktoryzacji; wydzielenie mikroserwisu wymaga własnego uzasadnienia. Książka u wydawcy.

W naszej firmie słowo „gotowe” znaczy co innego dla trzech osób. Konsultant ma na myśli uzgodnioną cenę, magazynier — odłożoną część, a technik — wykonaną naprawę. Jedna kolumna Status nie usuwa tej różnicy. Ukrywa ją do pierwszego nietypowego przypadku.

Granice zaczynamy ustalać przy rozmowie z ludźmi, którzy wykonują pracę. Pytamy o konkretną reklamację: co zaszło, kto podjął decyzję i jakiego faktu wtedy brakowało. Przydatny model wychodzi z takich rozmów. Nazwy folderów powinny dopiero go odzwierciedlać.

Jak ruszyć stary system bez wielkiego przepisywania?

1. Wybierz jeden bolesny scenariusz. Na przykład potwierdzanie terminu. Zapisz regułę z osobą odpowiedzialną za proces.
2. Zabezpiecz potrzebne zachowanie testami. Ustal, które obecne wyniki są poprawne. Utrwalenie starego błędu w teście nie robi z niego wymagania.
3. Wprowadź jedną ścieżkę dostępu. Kod zleceń prosi harmonogram o rezerwację przez kontrakt. Nie zmienia jego tabel bezpośrednio.
4. Przenieś odpowiedzialność za zapis. Ustal moment przełączenia i jednego właściciela. Dwa niezależne mechanizmy zapisujące te same dane utrudnią wykrycie rozbieżności.
5. Porównaj wyniki i usuń starą drogę. Sprawdź dane historyczne, przypadki brzegowe i plan powrotu. Dopiero potem sprzątaj zbędne zależności.

Wspólna baza może pozostać na tym etapie. Właściciel danych oznacza odpowiedzialność za ich zmianę, reguły i kontrakt, a nie automatycznie osobny serwer bazodanowy. W modularnym monolicie można zacząć od schematów, widoczności typów i testów zależności. Tam, gdzie potrzebujemy mocniejszej izolacji, dokładamy odpowiednie uprawnienia oraz granice wykonania.

04 / SOFTWARE ARCHITECTURE: THE HARD PARTS

Kiedy moduł staje się usługą, do rozmowy dołącza sieć.

Neal Ford, Mark Richards, Pramod Sadalage i Zhamak Dehghani analizują trudne decyzje dotyczące rozmiaru usług, danych, kontraktów i rozproszonych procesów. Warto sięgnąć po tę książkę, kiedy kilka rozsądnych rozwiązań ma różne, istotne koszty. Uczy porównywania kompromisów w kontekście konkretnego systemu. Opis książki u wydawcy.

Przypuśćmy, że harmonogram ma już własny zespół i integruje się z kilkoma partnerami. Osobna usługa może dać temu zespołowi swobodę wdrażania. Jednocześnie zwykłe wywołanie metody zamienia się w operację, która może się opóźnić, wykonać dwukrotnie lub zakończyć bez odpowiedzi. Biznesowa reguła nadal obowiązuje, ale zmieniły się warunki jej obrony.

Outbox zamyka konkretną lukę. Cały proces wymaga jeszcze kilku decyzji.

Jeżeli zapiszemy zlecenie, a potem wyślemy zdarzenie, proces może zakończyć się pomiędzy tymi operacjami. Rekord zostanie, wiadomość nie dotrze. Wzorzec transactional outbox zapisuje zmianę biznesową i zamiar publikacji w tej samej lokalnej transakcji. Osobny mechanizm publikuje później zdarzenie. Broker albo publisher nadal może dostarczyć duplikat, dlatego odbiorca musi być na to przygotowany. Opis outbox w Azure Architecture Center.

W odbiorcy zapis identyfikatora obsłużonego zdarzenia i zmiana biznesowa powinny tworzyć jedną lokalną transakcję, z ograniczeniem unikalności dla pary odbiorca–EventId. Samo sprawdzenie „czy już widziałem?” przed zapisem nie wystarcza przy równoległych wiadomościach. Jeśli efektem ma być wywołanie zewnętrznego API, jego bezpieczeństwo ponowień wymaga osobnego rozwiązania, na przykład klucza idempotencji obsługiwanego przez dostawcę.

Potrzebujemy też polityki kolejności. Zdarzenie z wersją 8 nie powinno po cichu cofnąć projekcji, która zna wersję 9. Możemy kontrolować wersje i obsługiwać luki albo użyć mechanizmu uporządkowania dla danego zlecenia. Wybór zależy od brokera, sposobu przetwarzania i tego, czy wymagamy kolejności dla jednego obiektu, czy szerszej grupy. Globalne porządkowanie wszystkiego często kosztuje więcej, niż daje.

Saga i kompensacja: co naprawdę potrafimy odwrócić?

Po wydzieleniu magazynu i harmonogramu nie mamy jednej transakcji obejmującej cały proces. Możemy koordynować lokalne kroki sagą. Gdy rezerwacja ekipy się nie powiedzie, uruchamiamy uzgodnione działania naprawcze: zwalniamy część, zapisujemy wynik i informujemy obsługę. Kompensacja sama może się nie udać, więc potrzebuje trwałego stanu, ponowień i ścieżki ręcznej interwencji. Wzorzec Saga w dokumentacji Microsoft.

Nie cofniemy czasu ani przeczytanej wiadomości. „Anulowano” musi mieć znaczenie ustalone z firmą. Jeśli stan zewnętrznej rezerwacji jest nieznany po timeout, nie oznaczamy jej od razu jako nieudanej. Najpierw uzgadniamy wynik. Interfejs powinien pokazać uczciwy stan oczekiwania lub potrzebę weryfikacji, zamiast obiecywać zakończenie.

05 / SITE RELIABILITY ENGINEERING

Architektura musi jeszcze pomóc człowiekowi, który odbierze telefon po awarii.

Książka pod redakcją Betsy Beyer, Chrisa Jonesa, Jennifer Petoff i Nialla Richarda Murphy’ego pokazuje, jak połączyć rozwój produktu z odpowiedzialnością za jego działanie. Przydatnym początkiem są SLI, SLO oraz budżet błędów: co mierzymy, jaki poziom uznajemy za wystarczający i jak reagujemy, gdy go tracimy. Oficjalna, bezpłatna wersja książki.

Dla Serwisu Północ ustalamy przykładowy cel: w ruchomym oknie 28 dni co najmniej 99,5% poprawnie przyjętych zleceń otrzymuje prawidłowy, trwały wynik w ciągu 120 sekund. Wynikiem może być potwierdzenie albo uzasadnione odrzucenie. Błąd infrastruktury nazwany „odrzuceniem” nie staje się poprawnym wynikiem. Definicję uzgadniamy przed pomiarem.

To budżet liczby operacji, nie minut przestoju. Ponowienia tej samej operacji nie powinny zwiększać mianownika. Musimy też ustalić, jak traktujemy operacje przyjęte tuż przed końcem okresu obserwacji, które jeszcze nie miały pełnych 120 sekund na zakończenie. Bez takiej definicji dwa zespoły mogą uczciwie wyliczyć różne wyniki. SLI i SLO według Google SRE.

Sam zielony endpoint zdrowia nie potwierdzi tego celu. Potrzebujemy zdarzeń początku i końca procesu oraz zgodnych identyfikatorów. Pomocniczo obserwujemy wiek najstarszej wiadomości w outbox, opóźnienie odbiorcy, liczbę stanów wymagających weryfikacji i nieskuteczne kompensacje. Te sygnały mają pomagać odnaleźć przyczynę, a nie zastępować pomiar doświadczenia użytkownika.

Z budżetem wiążemy wcześniej uzgodnioną reakcję. Jeśli tempo błędów zapowiada szybkie wyczerpanie budżetu, zespół ogranicza ryzykowne wydania, szuka przyczyny i poprawia niezawodność. Awaryjne poprawki oraz zmiany bezpieczeństwa mają osobną ocenę ryzyka. Konkretna polityka należy do produktu i jego zespołu; można zacząć od przykładowej polityki z The Site Reliability Workbook.

Co powinno czekać obok kodu?

• Mapa własności. Kto prowadzi incydent i kto zna każdy fragment procesu.
• Instrukcja działania. Jak odnaleźć zlecenie po identyfikatorze, rozpoznać bezpieczne ponowienie i skierować sprawę do weryfikacji.
• Plan odtwarzania. Kopia bazy oraz przećwiczona procedura przywrócenia i uzgodnienia stanu integracji. Sam status „backup wykonany” nie jest testem odtworzenia.
• Warunki wdrożenia. Zgodność kontraktów i migracji, kontrolowane uruchomienie oraz mierzalny warunek zatrzymania wydania.
• Wnioski po incydencie. Co utrudniło diagnozę, jaka ochrona zawiodła i jak sprawdzimy skuteczność poprawki.

Powrót do poprzedniej wersji aplikacji nie odwraca sam z siebie zmian danych ani skutków w zewnętrznym systemie. Plan awaryjny trzeba więc sprawdzić na scenariuszu z prawdziwą kolejnością operacji, a nie wyłącznie na pustej bazie testowej.

WARSZTAT / OD ROZUMIENIA DO DECYZJI

Ułóż przepływ. Potem obroń pięć decyzji.

W pierwszym ćwiczeniu wybierz kroki w poprawnej kolejności. Zakładamy jeden lokalny zapis zlecenia z outbox oraz osobnego odbiorcę. Wiadomości mogą zostać dostarczone ponownie. Wynik ćwiczenia pozostaje w tej karcie przeglądarki.

Po lekturze wybierz jedną decyzję, którą poprawisz w swoim systemie.

Nie musisz wdrażać wszystkich wzorców naraz. Opisz jeden proces: co przyjmuje, gdzie zapisuje prawdę, jak reaguje na powtórzenie i po czym rozpoznajesz jego zakończenie. Zaznacz miejsca, w których odpowiedź jest dziś zgadywana. Z takiej kartki często wychodzi lepszy plan pracy niż z listy nowych technologii.

Kolejność czytania: Fundamentals pomoże nazwać wymagania i kompromisy. U Fowlera sprawdzisz wzorce pasujące do logiki. Domain-Driven Refactoring przyda się przy porządkowaniu istniejącego kodu, The Hard Parts przy rozdzielaniu usług i danych, a SRE przy zamianie obietnic w pomiar oraz codzienną praktykę. Wracaj do odpowiedniego rozdziału, kiedy pojawi się konkretna decyzja.

Książki i źródła do dalszej pracy

To autorski poradnik oparty na zagadnieniach poruszanych w wymienionych publikacjach oraz dokumentacji. Linki prowadzą do autorów, wydawców i oficjalnych materiałów. Ćwiczenia nie wymagają zakupu książek.

1. Fundamentals of Software Architecture, 2nd Edition — Mark Richards, Neal Ford.
2. Patterns of Enterprise Application Architecture — Martin Fowler, ze współautorami wskazanymi na stronie książki.
3. Domain-Driven Refactoring — Alessandro Colla, Alberto Acerbis.
4. Software Architecture: The Hard Parts — Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani.
5. Site Reliability Engineering — redakcja: Betsy Beyer, Chris Jones, Jennifer Petoff, Niall Richard Murphy.

Dodatkowo: Saga, Transactional Outbox, Service Level Objectives oraz Error Budget Policy.