The Art of Crafting Architectural Diagrams

W pewnym momencie, w każdym projekcie oprogramowania, w który jesteśmy zaangażowani, może zaistnieć potrzeba stworzenia diagramów architektonicznych. Niezależnie od tego, czy stosujemy formalny model architektoniczny (np. Kruchten 4+1, Rozanski & Woods, itp.), czy nie, istnieje potrzeba udokumentowania pewnych części aplikacji poprzez tworzenie diagramów. W architekturze oprogramowania takie diagramy są tworzone zgodnie z widokami, które są związane z określonym punktem widzenia, który może być częścią modelu, ale w obecnym artykule wolę trzymać się terminu diagram architektoniczny i nie być bardzo formalnym; wszystkie inne aspekty nie mają być tutaj poruszane.

Bazując na moim doświadczeniu jako architekta oprogramowania i trenera technicznego, istnieje wiele rozbieżności pomiędzy projektami i wewnątrz zespołu projektowego od dewelopera do dewelopera w sposobie tworzenia diagramów architektonicznych. Zaobserwowałem wiele problemów dotyczących niespójności, fragmentacji i ziarnistości renderowanych informacji oraz wyglądu diagramów. W porównaniu do modelu architektonicznego, który musi być formalny i ustandaryzowany, diagramy niekoniecznie muszą być sformalizowane lub podążać za określonym standardem.

Niemniej jednak diagramy muszą być samoopisowe, spójne, wystarczająco dokładne i połączone z kodem. Dlatego ważne jest, aby każdy architekt lub inżynier oprogramowania polegał na kilku wytycznych podczas tworzenia diagramów architektonicznych, ponieważ są one wspólną podstawą do komunikowania architektury aplikacji w czasie (np. struktura, elementy, relacje, właściwości, zasady) i między różnymi interesariuszami mającymi różne techniczne tła i obawy.

Potencjalne pułapki podczas projektowania diagramów architektonicznych

Przed zagłębieniem się w możliwe problemy, chciałbym mieć analogię do angielskiego idiomu, który mówi „obraz jest wart tysiąca słów”. Zgodnie z wyjaśnieniem wiki, „odnosi się to do pojęcia, że złożona idea może być przekazana za pomocą jednego nieruchomego obrazu lub że obraz przedmiotu przekazuje jego znaczenie lub istotę bardziej skutecznie niż opis”. Ta sama koncepcja odnosi się do diagramu architektonicznego: jeśli rodzi on więcej pytań niż odpowiedzi, diagram nie jest dobrze stworzony. Nie pozwól, aby diagram architektoniczny wymagał tysięcy słów lub wyjaśnień!

Przykład niewłaściwego diagramu architektonicznego. Cierpi na większość z opisanych poniżej problemów

Prześledźmy teraz listę pułapek, które mogą utrudnić proces poprawnego tworzenia diagramów architektonicznych.

Co oznacza pole lub kształt?

• Użycie jakiegokolwiek pola lub kształtu, który nie jest odpowiednio udokumentowany, może spowodować wiele interpretacji. Może być kojarzone z kawałkiem danych, wiązką kodu lub procesem. Zwykłe pudełko w diagramie może budzić wiele wątpliwości i bardzo ważne jest, aby ich uniknąć poprzez wyraźne dodanie szczegółów dotyczących znaczenia pudełka lub kształtu w legendzie diagramu.

Co reprezentują różne krawędzie kształtu?

• Każda krawędź kształtu (np. przerywana, kropkowana, itp.) może być źle zrozumiana w przypadku słabego diagramu. Czy dana granica odnosi się do konkretnego typu komponentu (np. linia przerywana odnosi się do kontenera, mikroserwisu, warstwy, itp.), czy jest to tylko preferencja projektanta, aby mieć bogaty wygląd i odczucie? Unikaj takich nieporozumień, podając dokładne szczegóły w legendzie diagramu przy wyborze wielu lub niestandardowych krawędzi.

Co oznacza linia lub strzałka?

• Linia lub strzałka może być interpretowana jako przepływ danych (np. dane przepływają z systemu A do systemu B) lub jako relacja pomiędzy elementami (np. komponent A zależy od komponentu B). W większości przypadków relacje lub przepływy danych reprezentowane przez strzałki nie zbiegają się w tych samych kierunkach i ważne jest, aby wyraźnie napisać o tym w legendzie diagramu.

Jaki jest typ komunikacji/asocjacji wskazywany przez linię lub strzałkę?

• Nawet jeśli linia odnosi się do przepływu danych lub relacji pomiędzy elementami, typ komunikacji (np. w przypadku przepływu danych) lub typ asocjacji (np. w przypadku relacji) oznaczany przez tę linię lub strzałkę musi być szczegółowo opisany. Na przykład, jeśli linia reprezentuje przepływ danych, komunikacja może być synchroniczna lub asynchroniczna, ale jeśli linia odnosi się do relacji, może być reprezentowana przez zależność, dziedziczenie, implementację, itp. Wszystkie te szczegóły muszą być obecne w legendzie diagramu.

Co oznacza ten kolor?

• Posiadanie diagramu policolor 'perrot’ (np. wiele kolorów dla pudełek, linii) bez odpowiedniego udokumentowanego zamiaru może powodować wiele pytań (np. dlaczego niektóre pudełka są zielone, a inne czerwone? Dlaczego niektóre linie są czarne, a inne niebieskie?) W diagramie kolorystyka jest mniej istotna, a użycie dużej liczby kolorów nie wnosi zbyt wiele dodatkowych treści czy wartościowych informacji. Diagram może być również zrozumiały i dobrze zaprojektowany tylko dzięki użyciu czarno-białych kolorów, chyba że istnieje ścisły wymóg podkreślenia niektórych części diagramu poprzez użycie rozróżnialnych kolorów. W każdym przypadku, zawsze lepiej jest trzymać się prostoty w zakresie używanych kolorów, ale jeśli tak nie jest, nie zapomnij podać szczegółów wyboru.

Brak relacji pomiędzy elementami diagramu lub odizolowanymi jednostkami

• Brak relacji pomiędzy elementami lub odizolowanymi jednostkami w diagramie może być wskazówką niekompletności. Zarówno z perspektywy strukturalnej, jak i behawioralnej, każdy element lub jednostka powinna polegać na / mieć relację (reprezentowaną przez linię lub strzałkę) z inną częścią systemu reprezentowaną przez inny element.

Wprowadzające w błąd/nieudokumentowane akronimy lub zbyt niejasne/ogólne terminy

• Podczas używania etykiety dla elementu w diagramie, zaleca się nie używać żadnych wprowadzających w błąd lub nieudokumentowanych akronimów, które mogą powodować nieporozumienia. TFH, RBPM) nic nie znaczą bez odpowiedniego wyjaśnienia na elemencie diagramu lub, jeszcze lepiej, w legendzie diagramu (np. TFH – ticket feed handler, RBPM – rates business process manager).

• Inna cecha nazewnictwa elementów diagramu dotyczy bardzo nieprecyzyjnych lub ogólnych określeń (np. business logic, integration logic), które nie wnoszą zbyt wiele cennych informacji, ponieważ ich nazwy nie są właściwie samoopisowe. Ten problem może występować również na poziomie kodu, a sugestia byłaby taka, aby zawsze używać samowyjaśniających i sugestywnych nazw, stosując się do zasad czystego kodu.

Podkreślanie technologii, frameworków, języków programowania lub skryptów, IDE lub metodologii rozwoju na diagramach

• Projekt architektoniczny nie jest związany lub zasadniczo oparty na jakiejkolwiek technologii, frameworku, języku programowania lub skryptów, IDE lub metodologii rozwoju. Wszystkie te elementy pojawiają się później w procesie, aby pomóc w budowaniu architektury, ale nie są punktem centralnym. Nie powinny być włączone do diagramów, ale zawarte w opisie architektury, łącznie z uzasadnieniem ich wyboru.

Mieszanie elementów runtime i statycznych w tym samym diagramie

• Elementy runtime (np. wątki, procesy, maszyny wirtualne, kontenery, usługi, firewalle, repozytoria danych, itp.) nie są obecne w czasie kompilacji i zaleca się unikanie mieszania tych elementów ze statycznymi (np. komponenty, pakiety, klasy) w tym samym diagramie. Istnieją dedykowane typy diagramów (np. diagram współbieżności, diagram rozmieszczenia), które skupiają się głównie na elementach runtime i ważne jest, aby rozróżnić te dwie kategorie elementów i unikać ich mieszania tak bardzo, jak to możliwe.

Przyjmuj założenia typu „Opiszę to słownie” i „Wyjaśnię to później”

• Wszystko, co nie jest opisane przez sam diagram, jest pomijane i nie ma miejsca na dostarczanie szczegółów słownych w celu uzupełnienia diagramu. Dlaczego? Ponieważ wszystkie wyjaśnienia wspomniane ustnie, ale nie ujęte w diagramie są tracone i później, gdy inni interesariusze (np. deweloper, architekt) będą czytać diagram, nie będą o nich wiedzieli. Spróbuj zawrzeć wszystkie niezbędne szczegóły w diagramie, aby uniknąć potrzeby dalszych wyjaśnień.

Konfliktowe poziomy szczegółowości lub mieszane abstrakcje

• Dodawanie elementów związanych z różnymi poziomami abstrakcji w tym samym diagramie może powodować konflikt, ponieważ są one widziane z różnych perspektyw. Na przykład, dodanie komponentów do diagramu kontekstu architektonicznego lub klas do diagramu rozmieszczenia może spowodować rozbieżność z celem samego diagramu. Podczas tworzenia diagramu, staraj się trzymać tego samego poziomu abstrakcji.

Zagmatwane lub zbyt niejasne diagramy próbujące pokazać zbyt duży lub niewystarczający poziom szczegółowości

• „Wszystko powinno być tak proste, jak to tylko możliwe, ale nie prostsze” jest dobrze znanym cytatem należącym do Alberta Einsteina. Dotyczy to również diagramów architektonicznych; poziom i ziarnistość przechwytywanych informacji powinny być sensownie dobrane. Nie jest to łatwe; zależy to od zastosowanego modelu architektonicznego, doświadczenia architekta i złożoności systemu.

Wskazówki, których należy przestrzegać podczas tworzenia diagramów architektonicznych

Oprócz powyższych pułapek, które muszą być częścią wstępnej listy kontrolnej, aby ich uniknąć, istnieją również ogólne wskazówki, jak prawidłowo tworzyć diagramy:

Wybierz optymalną liczbę diagramów

• Jak powiedział Philippe Kruchten, „architektura jest złożoną bestią”. Używanie jednego schematu do reprezentowania architektury skutkuje niezrozumiałym semantycznym bałaganem.” Aby udokumentować nowoczesne systemy nie możemy skończyć z tylko jednym rodzajem diagramu, ale podczas tworzenia diagramów architektonicznych nie zawsze jest proste, jakie diagramy wybrać i ile ich stworzyć. Istnieje wiele czynników, które należy wziąć pod uwagę przed podjęciem decyzji; na przykład, charakter i złożoność architektury, umiejętności i doświadczenie architekta oprogramowania, dostępny czas, ilość pracy potrzebnej do ich utrzymania oraz to, co ma sens lub jest użyteczne dla zaspokojenia obaw interesariuszy. Na przykład, inżynier sieciowy prawdopodobnie będzie chciał zobaczyć wyraźny model sieci, w tym hosty, porty komunikacyjne i protokoły; administrator bazy danych jest zainteresowany tym, jak system manipuluje, zarządza i dystrybuuje dane, itp. W oparciu o wszystkie te aspekty zaleca się zebranie optymalnej liczby diagramów, niezależnie od tego, jaka to liczba.
• Jeśli diagramów jest za mało (np. under-documenting), części architektury mogą być ukryte lub nieudokumentowane; z drugiej strony, jeśli jest ich za dużo (np. nadmiernie udokumentowane), wysiłek potrzebny do utrzymania ich spójności, aktualizacji i nie fragmentacji może znacznie wzrosnąć.

Zachowaj strukturalną i semantyczną spójność diagramów

• Każdy diagram powinien być spójny z innymi pod względem pudełek, kształtów, granic, linii, kolorów, itp. Wygląd strukturalny powinien być taki sam i każdy interesariusz nie powinien mieć trudności w zrozumieniu diagramów stworzonych przez różnych programistów wewnątrz zespołu. Idealnie byłoby trzymać się wspólnego narzędzia do tworzenia diagramów i używać go we wszystkich projektach.
• Z semantycznego punktu widzenia, wszystkie te diagramy powinny być okresowo synchronizowane z najnowszymi zmianami w kodzie i pomiędzy nimi, ponieważ zmiana w jednym diagramie może wpłynąć na inne. Proces ten może być wywoływany ręcznie lub automatycznie za pomocą narzędzia do modelowania. Ten drugi mechanizm jest preferowany, ale zależy to od projektu, w każdym przypadku chodzi o zachowanie spójności pomiędzy diagramami i kodem, niezależnie od metody czy narzędzia. Simon Brown powiedział „diagramy nie są użyteczne do ulepszania architektury, jeśli nie są połączone z kodem”, co podkreśla ideę spójności semantycznej.

Przeciwdziałanie fragmentacji diagramów

• Posiadanie wielu diagramów może sprawić, że opis architektoniczny będzie trudny do zrozumienia, ale także będzie wymagał znacznego wysiłku w ich utrzymaniu. Jako efekt uboczny może pojawić się fragmentacja (np. np. dwa lub więcej diagramów ilustruje ten sam atrybut jakości – wydajność, skalowalność, itp. – ale każdy z nich jest indywidualnie niekompletny). W takich przypadkach zalecane jest albo usunięcie diagramów, które nie odzwierciedlają istotnych atrybutów jakości (związanych z istotnymi architektonicznie wymaganiami) lub, jeszcze lepiej, połączenie diagramów (np. współbieżności i rozmieszczenia).

Keep traceability across diagrams

• Możliwość sprawdzania historii, dokonywania porównań pomiędzy różnymi wersjami diagramów oraz łatwego powrotu do poprzedniej wersji jest również ważna. Używanie narzędzia do modelowania, które tego nie umożliwia, może być przeszkodą. Najnowsze trendy w branży polegają na wykorzystaniu prostego i intuicyjnego języka tekstowego do generowania z niego diagramów, co wydaje się rozwiązywać problem identyfikowalności. Inną zaletą takiego podejścia jest to, że implicite zapewnia ono jednorodną spójność strukturalną pomiędzy diagramami.

Dodaj legendy obok diagramów architektonicznych

• Jeśli nie stosujesz standardowego języka opisu architektury (np. UML, ArchiMate), wyszczególnij każdy element diagramu w legendzie (np. pola, kształty, granice, linie, kolory, akronimy, itp.).
• Jeśli tak nie jest, w legendzie wystarczy dodać język opisu architektury jako klucz i nie ma potrzeby dodatkowych wyjaśnień, ponieważ każdy czytelnik będzie śledził specyfikę tego języka, aby zrozumieć diagram.

Czy język opisu architektury (np. UML, ArchiMate, itp.) robi różnicę?

Jest wiele opinii na temat tego, który język opisu jest właściwy do przyjęcia w projekcie. Niektórzy ludzie mogą twierdzić, że UML jest sztywny i nie jest wystarczająco elastyczny do modelowania projektu architektonicznego, z czym się zgadzam. Niemniej jednak, w niektórych przypadkach może on być więcej niż wystarczający do udokumentowania podstaw architektury bez polegania na jakichkolwiek cechach rozszerzalności UML, takich jak profile i stereotypy. Patrząc na inne języki opisu, możemy zauważyć, że ArchiMate jest bardziej wydajny i odpowiedni do modelowania systemów korporacyjnych w porównaniu do UML; jest też BPMN, który jest szczególnie ukierunkowany na procesy biznesowe, itd. Porównania mogą być kontynuowane, ale nie zamierzam dokonywać ich głębokiego przeglądu, ponieważ nie jest to celem tego artykułu.

Posiadanie wystarczająco wszechstronnego i elastycznego języka opisu architektury jest dużym krokiem naprzód i powinno to być solidnym kryterium przy jego wyborze. Ale z mojej perspektywy, prawdziwa przyczyna leży gdzie indziej i jest związana z faktem, że dokumentacja architektoniczna nie jest w ogóle tworzona. Ludzie często uważają jej tworzenie za nudne, bezużyteczne lub bezcelowe. Liczba projektów oprogramowania bez dokumentacji, lub z niewłaściwą dokumentacją, jest ogromna. Nie sądzę, aby ludzie intensywnie tworzyli lub byli zaangażowani w tworzenie diagramów architektonicznych przy użyciu niewłaściwego języka opisu, a gdyby zastąpić je lepszym, wyniki byłyby zupełnie inne. Nie, ludzie nie tworzą żadnej dokumentacji architektonicznej (w tym diagramów architektonicznych), a co gorsza, większość z nich nie ma pojęcia o tym, jak prawidłowo ją tworzyć. To są rzeczy, którymi musimy się zająć w pierwszej kolejności – zrozumieć, dlaczego dokumentacja ma znaczenie i jak ją poprawnie tworzyć (poprzez szkolenie inżynierów oprogramowania); wtedy wybór odpowiednich narzędzi przychodzi naturalnie.

Jak diagramy mogą być aktualizowane w miarę rozwoju systemu i materializowania się zmian w architekturze

Jest kilka podejść do aktualizowania diagramów; poniżej przedstawię trzy z nich. Pierwszą opcją i najłatwiejszą byłoby automatyczne generowanie diagramów z kodu źródłowego, który jest prawdą podstawową. Gwarantuje to, że wszystkie są spójne z kodem. Niestety, z istniejącymi narzędziami nie jest to jeszcze w pełni możliwe (przynajmniej według mojej wiedzy), ponieważ obecne narzędzia nie potrafią stworzyć żadnego rodzaju dokładnego i znaczącego diagramu tylko na podstawie kodu źródłowego, bez znaczącej ręcznej interwencji. Len Bass powiedział „idealne środowisko programistyczne to takie, dla którego dokumentacja jest dostępna zasadniczo za darmo po naciśnięciu przycisku”, pośrednio automatycznie generując diagramy, ale nie osiągnęliśmy tego punktu.

Drugim podejściem byłoby najpierw zaprojektowanie diagramów za pomocą dedykowanego narzędzia, które następnie generuje szkielety kodu źródłowego (np. komponenty/pakiety z granicami, API) używane później przez programistów do wypełnienia kodu. W ten sposób każda zmiana w architekturze musi być wywołana z poziomu samego diagramu, który automatycznie może zregenerować lub zaktualizować szkielet kodu.

Ostatni przypadek wymaga ręcznej aktualizacji diagramów za każdym razem, gdy wdrażana jest nowa funkcjonalność, która ma wpływ na projekt architektoniczny. Aby mieć pewność, że wszystkie zmiany w kodzie są odzwierciedlone na diagramach, zaleca się, aby aktualizowanie diagramów było częścią definicji wykonania w procesie rozwoju. Ten scenariusz jest mniej zalecany, ponieważ może łatwo spowodować nieaktualne lub niespójne diagramy (np. programiści często zapominają lub nie są w nastroju do aktualizacji diagramów) i niestety nadal zdarza się to w większości projektów.

Biorąc pod uwagę istniejące narzędzia, moim zaleceniem jest posiadanie mieszanki; mieszanie automatycznego i ręcznego tworzenia diagramów. Na przykład, starać się automatycznie generować diagramy, które mogą być rozsądnie renderowane przez narzędzia oparte na kodzie źródłowym bez zbytniego szumu (np. zbyt zagracone lub bezsensowne informacje). Do tej kategorii możemy zaliczyć zarówno diagramy o wysokim stopniu zmienności (np. bardziej podatne na częste zmiany w rozwoju, zwykle posiadające niższy poziom abstrakcji), jak i, przeciwnie, diagramy statyczne. Niektóre z takich diagramów mogą odnosić się do diagramów kontekstowych, diagramów architektury referencyjnej, diagramów pakietów, diagramów klas, diagramów encji, itp. Niemniej jednak, w niektórych przypadkach, nie jest oczywiste na podstawie samego kodu źródłowego, w jaki sposób system spełnia pewne atrybuty jakości (np. dostępność, skalowalność, wydajność), dlatego też automatyczne tworzenie diagramów nie jest wystarczającą opcją. Musi być ono uzupełnione o ręcznie modelowane diagramy. Niektóre przykłady takich diagramów obejmują diagramy sekwencji, diagramy stanów, diagramy współbieżności, diagramy wdrożeń, diagramy operacyjne itp.

Jakie komplikacje (lub uproszczenia) pojawiają się dla diagramów architektonicznych, gdy mamy do czynienia z nowoczesnymi architekturami (np. mikroserwisami)?microservices)?

Microservices lub jakikolwiek inny nowoczesny styl architektoniczny (np. serverless, event driven) napędza jedynie strukturę systemu, to jak komponenty komunikują się ze sobą (np. relacje między nimi) i jakie zasady nimi rządzą. Osobiście uważam, że styl architektoniczny nie powinien zmieniać przesłanek czy koncepcji wokół tworzenia diagramów (i pośrednio opisu architektonicznego), ani tego, co powinny one ujmować. Niemniej jednak, kiedy mówimy o nowoczesnych architekturach systemów, zwykle mających wyższy poziom złożoności w porównaniu do starych i klasycznych systemów (np. monolit), zdecydowanie mają one wpływ na opis architektoniczny i pośrednio na diagramy, w tym sensie, że istnieje wiele czynników, o które należy zadbać. Takie rozważania mogą dotyczyć zrozumienia liczby rozproszonych komponentów (np. rozproszone mikroserwisy), typu każdego komponentu, sposobu, w jaki komponenty komunikują się ze sobą (np. granice, API, wiadomości), ich cyklu życia i tego, kto jest właścicielem każdego komponentu.

Biorąc to wszystko pod uwagę, widoki przechwytujące dekompozycję systemu, rozwój, wdrożenie i operacyjność powinny być domyślnie brane pod uwagę. Wyobraźmy sobie na przykład system z imponującą liczbą mikroserwisów; w takim przypadku liczba diagramów może znacząco wzrosnąć, ponieważ każdy mikroserwis może w końcu mieć swój własny zestaw diagramów. Kwestie dotyczące spójności (np. zmiana API jednej usługi wpływa na inne usługi X, dlatego wszystkie diagramy, na które ma to wpływ, muszą zostać zaktualizowane), fragmentacji (np. wysoka dostępność lub wydajność pomiędzy rozproszonymi usługami nie jest skonsolidowana w jednym diagramie) lub problemów przekrojowych (np. kto jest odpowiedzialny za zilustrowanie w skonsolidowany sposób aspektów takich jak monitorowanie lub bezpieczeństwo w całych elementach systemu) mogą nie być łatwe do rozwiązania. Do tego mogą dojść wyzwania związane ze współistnieniem i współpracą zespołów podczas rozwoju projektu, a nawet później, w celu jego utrzymania.

Podsumowując, nowoczesne systemy o złożonych architekturach mogą wnosić dodatkowe problemy, które mogą prowadzić do komplikacji nawet na poziomie diagramów.

O autorze

Ionut Balosin jest architektem oprogramowania i niezależnym trenerem technicznym. Jest regularnym prelegentem na konferencjach i spotkaniach dotyczących rozwoju oprogramowania na całym świecie, prowadząc prezentacje, szkolenia i warsztaty. Więcej szczegółów można znaleźć na jego stronie internetowej.