Az építészeti diagramok készítésének művészete

Egy bizonyos ponton, minden szoftverprojektben, amelyben részt veszünk, szükség lehet architektúra-diagramok készítésére. Akár követünk egy formális architektúramodellt (pl. Kruchten 4+1, Rozanski & Woods, stb.), akár nem, szükség van arra, hogy az alkalmazás bizonyos részeit diagramok készítésével dokumentáljuk. A szoftverarchitektúrában az ilyen diagramok a nézeteknek megfelelően készülnek, amelyek egy adott nézőponthoz kapcsolódnak, amely része lehet egy modellnek, de a jelen cikkben inkább maradok az architektúradiagram kifejezésnél, és nem nagyon formálisak; minden más szempontot nem kívánok itt tárgyalni.

Szoftverarchitektként és műszaki trénerként szerzett tapasztalataim alapján sok eltérés van a projektek között és a projektcsapaton belül fejlesztőtől fejlesztőig az architektúradiagramok készítésének módjában. Sok problémát láttam a renderelt információk következetlenségével, töredezettségével és szemcsézettségével, valamint a diagramok kinézetével kapcsolatban. Az építészeti modellhez képest, amelynek formálisnak és szabványosítottnak kell lennie, a diagramok nem feltétlenül formalizáltak vagy nem feltétlenül követnek egy adott szabványt.

A diagramoknak mindazonáltal önleírónak, következetesnek, elég pontosnak és a kódhoz kapcsolódónak kell lenniük. Ezért fontos, hogy minden építész vagy szoftvermérnök számos irányelvre támaszkodjon az architektúra-diagramok készítésekor, mivel ezek jelentik a közös alapot az alkalmazás architektúrájának idővel történő kommunikálásához (pl. struktúra, elemek, kapcsolatok, tulajdonságok, elvek) és a különböző technikai háttérrel és aggályokkal rendelkező különböző érdekeltek között.

Az architektúra-diagramok tervezésekor előforduló buktatók

Mielőtt mélyebben belemennénk a lehetséges problémákba, szeretnék egy angol idiómához hasonlítani, amely szerint “egy kép ezer szót ér”. E wiki magyarázat szerint “arra az elképzelésre utal, hogy egy összetett gondolat egyetlen állóképpel is közvetíthető, vagy hogy egy tárgyról készült kép hatékonyabban közvetíti annak jelentését vagy lényegét, mint egy leírás”. Ugyanez a koncepció érvényes egy építészeti diagramra is: ha több kérdést vet fel, mint választ, akkor a diagram nem jól van megalkotva. Ne hagyja, hogy egy építészeti diagram ezernyi szót vagy pontosítást igényeljen!

Példa egy nem megfelelő építészeti diagramra. Az alább leírt problémák többségétől szenved

Most tekintsük át a buktatók listáját, amelyek akadályozhatják az építészeti diagramok megfelelő elkészítését.

Mit jelöl egy doboz vagy alakzat?

• Minden olyan doboz vagy alakzat használata, amely nincs megfelelően dokumentálva, többféle értelmezéshez vezethet. Akár egy adatdarabhoz, akár egy csomó kódhoz, akár egy folyamathoz társulhat. Már egy egyszerű doboz egy diagramban is többszörös kételyeket vethet fel, és nagyon fontos, hogy ezeket elkerüljük azáltal, hogy a diagram legendájában kifejezetten részletezzük a doboz vagy alakzat jelentését.

Mit jelentenek egy alakzat különböző élei?

• Egy alakzat minden éle (pl. szaggatott, szaggatott stb.) félreérthető egy rossz diagram esetén. Egy adott szegély egy adott komponenstípusra utal (pl. a szaggatott vonal egy konténerre, egy mikroszolgáltatásra, egy rétegre stb. utal), vagy ez csak a tervező preferenciája a gazdag megjelenés érdekében? Kerülje el az ilyen félreértéseket azzal, hogy a legendadiagramon pontos részleteket ad meg, amikor több vagy nem szabványos éleket választ.

Mit jelöl egy vonal vagy egy nyíl?

• A vonal vagy egy nyíl értelmezhető adatáramlásként (pl. az adatok A rendszerből B rendszerbe áramlanak) vagy elemek közötti kapcsolatként (pl. A komponens függ a B komponenstől). A legtöbb esetben a nyilak által ábrázolt kapcsolatok vagy adatfolyamok nem ugyanabba az irányba konvergálnak, ezért fontos, hogy ezt a diagram legendájában explicit módon írjuk le.

Milyen kommunikációs/kapcsolati típust jelez egy vonal vagy nyíl?

• Még ha a vonal adatfolyamra vagy komponensek közötti kapcsolatra utal is, az adott vonal vagy nyíl által jelzett kommunikációs típust (pl. adatfolyam esetén) vagy kapcsolattípust (pl. kapcsolat esetén) részletezni kell. Például, ha a vonal adatáramlást jelöl, a kommunikáció lehet szinkron vagy aszinkron, de ha a vonal egy kapcsolatra utal, akkor az lehet függőség, öröklés, implementáció stb. Mindezeknek a részleteknek meg kell jelenniük a diagram legendájában.

Mit jelent ez a szín?

• A megfelelő dokumentált szándék nélkül készített “perrot” policolor diagram (pl. több szín a dobozok, vonalak számára) több kérdést is felvethet (pl. miért zöldek egyes dobozok és pirosak mások? Miért fekete néhány vonal és miért kék?). A színséma kevésbé fontos egy diagramban, és a színek gazdag számának használata nem hoz túl sok többlettartalmat vagy értékes információt. Egy diagram lehet önmagyarázó és jól megtervezett pusztán fekete és fehér színek használatával is, hacsak nem áll fenn az a szigorú kényszer, hogy a diagram egyes részeit megkülönböztethető színekkel emeljük ki. Mindenesetre mindig jobb, ha ragaszkodunk az egyszerűséghez az alkalmazott színek tekintetében, de ha ez nem így van, ne felejtsük el részletezni a választást.

A diagramelemek vagy elszigetelt entitások közötti kapcsolatok hiánya

• A diagramban az elemek vagy elszigetelt entitások közötti kapcsolatok hiánya a hiányosságra utaló jel lehet. Mind szerkezeti, mind viselkedési szempontból minden elemnek vagy entitásnak (vonallal vagy nyíllal ábrázolt) kapcsolatban kell állnia/állnia a rendszer egy másik elem által ábrázolt másik részével.

Félrevezető/nem dokumentált rövidítések vagy túl homályos/általános kifejezések

• A diagramban egy elem jelölésének használatakor ajánlott, hogy ne használjunk félrevezető vagy nem dokumentált rövidítéseket, amelyek zavart okozhatnak. Csak egy betűsorozat (pl. TFH, RBPM) nem jelent semmit a diagramelemen vagy még jobb esetben a diagramlegendán található megfelelő magyarázat nélkül (pl. TFH – ticket feed handler, RBPM – rates business process manager).

• A diagramelemek elnevezésének másik jellemzője a rendkívül homályos vagy általános kifejezésekkel kapcsolatos (pl. business logic, integration logic), amelyek nem hordoznak túl sok értékes információt, mivel nevük nem megfelelően önleíró. Ez a probléma a kód szintjén is felmerülhet, és a javaslat az lenne, hogy a tiszta kód elveit követve mindig önmagyarázó és szuggesztív neveket használjunk.

A technológiák, keretrendszerek, programozási vagy szkriptnyelvek, IDE vagy fejlesztési módszertan hangsúlyozása a diagramokon

• Az architekturális tervezés nem kapcsolódik vagy alapvetően nem alapul semmilyen technológián, keretrendszeren, programozási vagy szkriptnyelven, IDE-n vagy fejlesztési módszertanon. Mindezek később kerülnek a folyamatba, hogy segítsék az architektúra felépítését, de nem ezek állnak a középpontban. Nem szabad szerepeltetni őket az ábrákon, hanem az architektúra leírásában kell feltüntetni őket, beleértve a választásukkal kapcsolatos indoklást is.

Futásidejű és statikus elemek keveredése ugyanabban az ábrában

• A futásidejű elemek (pl. szálak, folyamatok, virtuális gépek, konténerek, szolgáltatások, tűzfalak, adattárak stb.) a fordítási időben nincsenek jelen, és ajánlatos elkerülni, hogy ezeket az elemeket a statikus elemekkel (pl. komponensek, csomagok, osztályok) keverjük ugyanabban az ábrában. Vannak olyan dedikált diagramtípusok (pl. párhuzamossági diagram, telepítési diagram), amelyek elsősorban a futásidejű elemekre koncentrálnak, és fontos, hogy különbséget tegyünk e két elemkategória között, és lehetőség szerint kerüljük a keveredésüket.

Tegyünk olyan feltevéseket, mint “ezt majd verbálisan leírom”, és “majd később elmagyarázom”

• Minden, amit nem maga a diagram ír le, hiányzik, és nincs hely arra, hogy verbális részletekkel egészítsük ki a diagramot. Hogy miért? Mert minden szóban említett, de a diagramban nem rögzített magyarázat elvész, és később, amikor más érdekelt felek (pl. fejlesztő, építész) elolvassák a diagramot, nem lesznek tisztában ezekkel a magyarázatokkal. Próbáljon meg minden szükséges részletet felvenni a diagramba, hogy elkerülje a további pontosítások szükségességét.

A részletek ütköző szintjei vagy vegyes absztrakciók

• A különböző absztrakciós szintekhez tartozó elemek hozzáadása ugyanabban a diagramban konfliktusba kerülhet, mivel azokat különböző perspektívákból látjuk. Például komponensek hozzáadása egy architektúra-kontextus diagramhoz vagy osztályok hozzáadása egy telepítési diagramhoz eltérhet magának a diagramnak a céljától. Amikor diagramot készít, próbáljon meg ragaszkodni az azonos absztrakciós szinthez.

A túlságosan zsúfolt vagy túl homályos diagramok túl sok vagy elégtelen részletezettségi szintet próbálnak bemutatni

• “Mindent a lehető legegyszerűbbé kell tenni, de nem egyszerűbbé” – ez egy jól ismert, Albert Einsteinhez tartozó idézet. Ez az építészeti diagramokra is érvényes; a rögzített információk szintjét és szemcsézettségét értelmesen kell megválasztani. Ez nem könnyű dolog; függ az alkalmazott architektúramodelltől, az építész tapasztalatától és a rendszer összetettségétől.

Az építészeti diagramok készítésekor követendő irányelvek

A fenti buktatókon kívül, amelyek elkerülése érdekében egy előfeltételként összeállított ellenőrzőlista részét kell képezni, vannak általános irányelvek is a diagramok megfelelő elkészítésére:

A diagramok optimális számának kiválasztása

• Ahogy Philippe Kruchten mondta, “az építészet egy komplex fenevad. Ha egyetlen tervrajzot használunk az építészet ábrázolására, az értelmezhetetlen szemantikai zűrzavart eredményez”. A modern rendszerek dokumentálásához nem juthatunk csak egyfajta diagramhoz, de az architektúra-diagramok készítésekor nem mindig egyértelmű, hogy milyen diagramokat válasszunk és hányat hozzunk létre belőlük. A döntés meghozatala előtt több tényezőt is figyelembe kell venni; például az architektúra jellegét és összetettségét, a szoftverépítész készségeit és tapasztalatát, a rendelkezésre álló időt, a karbantartásukhoz szükséges munka mennyiségét, valamint azt, hogy mi az, aminek van értelme vagy hasznos az érdekeltek aggályainak kielégítése szempontjából. Például egy hálózati mérnök valószínűleg egy explicit hálózati modellt szeretne látni, beleértve a hosztokat, kommunikációs portokat és protokollokat; egy adatbázis-adminisztrátort az érdekli, hogy a rendszer hogyan manipulálja, kezeli és osztja el az adatokat stb. Mindezen szempontok alapján ajánlott az optimális számú diagramot felvenni, bármennyi is legyen ez a szám.
• Ha nincs elegendő diagram (pl. aluldokumentálás), az architektúra egyes részei rejtve maradhatnak vagy dokumentálatlanok lehetnek; másrészt, ha túl sok van (pl. túldokumentálás), jelentősen megnőhet a konzisztens, frissített és nem töredezett diagramok fenntartásához szükséges erőfeszítés.

Szerkezeti és szemantikai konzisztencia fenntartása a diagramok között

• Minden diagramnak konzisztensnek kell lennie a többivel a dobozok, formák, határok, vonalak, színek stb. tekintetében. A szerkezeti megjelenésnek azonosnak kell lennie, és minden érdekelt félnek nem okozhat nehézséget a csapaton belüli különböző fejlesztők által készített diagramok megértése. Ideális esetben ragaszkodjon egy közös diagramkészítő eszközhöz, és használja azt újra az összes projektben.
• Szemantikai szempontból az összes ilyen diagramot rendszeresen szinkronizálni kell a legújabb kódváltozásokkal és egymás között, mivel az egyik diagramban bekövetkező változás hatással lehet a többire. Ez a folyamat történhet manuálisan vagy automatikusan, egy modellező eszköz használatával. Ez utóbbi a preferált mechanizmus, de ez projektenként változó, a lényeg minden esetben a diagramok és a kód közötti konzisztencia fenntartása, függetlenül a módszertől vagy eszköztől. Simon Brown szerint “a diagramok nem hasznosak az architektúra javítására, ha nincsenek kapcsolatban a kóddal”, ami a szemantikai konzisztencia gondolatát hangsúlyozza.

A diagramok töredezettségének megakadályozása

• A több diagram megléte megnehezítheti az architektúra leírásának megértését, de jelentős erőfeszítést jelenthet a karbantartásuk is. Mellékhatásként töredezettség jelenhet meg (pl. például két vagy több diagram illusztrálja ugyanazt a minőségi attribútumot – teljesítmény, skálázhatóság stb. – de mindegyikük külön-külön hiányos). Ilyen esetekben ajánlott vagy eltávolítani a releváns minőségi attribútumokat nem tükröző (építészetileg jelentős követelményekhez kapcsolódó) diagramokat, vagy – ami még jobb – összevonni a diagramokat (pl. párhuzamosság és telepítés).

A diagramközi nyomon követhetőség fenntartása

• Az előzmények ellenőrizhetősége, a különböző diagramverziók közötti összehasonlítás, valamint a korábbi verzióhoz való könnyű visszatérés is fontos. Egy olyan modellező eszköz használata, amely ezt nem teszi lehetővé, akadályt jelenthet. Az iparág legújabb trendjei egy egyszerű és intuitív egyszerű szöveges nyelv használatára támaszkodnak, amelyből a diagramokat generálják, ami úgy tűnik, hogy megoldja a nyomon követhetőséggel kapcsolatos aggályokat. Az ilyen megközelítés másik előnye, hogy implicit módon biztosítja a diagramok közötti homogén szerkezeti konzisztenciát.

Legendák hozzáadása az építészeti diagramok mellé

• Ha nem követ egy szabványos építészeti leíró nyelvet (pl. UML, ArchiMate), részletezze a diagram minden darabját a legendában (pl. dobozok, alakzatok, határok, vonalak, színek, rövidítések stb.).
• Ha ez nem így van, akkor a legendában csak az építészeti leíró nyelvet kell kulcsként feltüntetni, és nincs szükség további magyarázatokra, hiszen minden olvasó követni fogja a nyelvi sajátosságokat, hogy megértse a diagramot.

Változik-e az építészeti leíró nyelv (pl. UML, ArchiMate, stb.)?

Azzal kapcsolatban, hogy melyik a megfelelő leíró nyelv a projektben, sokféle vélemény létezik. Egyesek azzal érvelhetnek, hogy az UML merev és nem elég rugalmas az építészeti tervezés modellezéséhez, ezzel az állásponttal én is egyetértek. Mindazonáltal bizonyos esetekben több mint elegendő lehet az architektúra alapjainak dokumentálására anélkül, hogy az UML bővíthetőségi jellemzőire, például profilokra és sztereotípiákra támaszkodna. Ha megnézzük más leíró nyelveket, láthatjuk, hogy az ArchiMate az UML-hez képest sokkal erősebb és alkalmasabb a vállalati rendszerek modellezésére; ott van még a BPMN is, amely kifejezetten az üzleti folyamatokat célozza, stb. Az összehasonlításokat lehetne folytatni, de nem áll szándékomban mélyreható áttekintést végezni rajtuk keresztül, mivel ennek a cikknek nem ez a célja.

Az, hogy egy architektúraleíró nyelv elég átfogó és rugalmas legyen, nagy előrelépés, és ez legyen szilárd kritérium a kiválasztásakor. De az én szemszögemből nézve az igazi ok máshol rejlik, és azzal függ össze, hogy egyáltalán nem készül építészeti dokumentáció. Az emberek gyakran unalmasnak, haszontalannak vagy értelmetlennek találják a létrehozását. A dokumentáció nélküli vagy nem megfelelő dokumentációval rendelkező szoftverprojektek száma óriási. Nem hiszem, hogy az emberek intenzíven készítenek vagy részt vesznek az építészeti diagramok készítésében egy nem megfelelő leírónyelv használatával, és ha egy jobbal helyettesítenék, az eredmények nagyon eltérőek lennének. Nem, az emberek nem készítenek semmilyen építészeti dokumentációt (beleértve az építészeti diagramokat is), és ami még rosszabb, a legtöbbjüknek fogalma sincs arról, hogyan kell azt megfelelően elkészíteni. Ezekkel a dolgokkal kell először foglalkoznunk – hogy megértsük, miért fontos a dokumentáció, és hogyan kell helyesen létrehozni (a szoftvermérnökök képzésével); ezután a megfelelő eszközök kiválasztása magától értetődően következik.

Hogyan lehet az ábrákat naprakészen tartani, ahogy a rendszer fejlődik, és az architektúra változásai megvalósulnak

Az ábrák naprakészen tartására néhány megközelítés létezik; az alábbiakban ezek közül hármat fogok kifejteni. Az első és legegyszerűbb lehetőség az lenne, hogy a diagramok automatikusan generálódnak a forráskódból, ami az alapigazság. Ez garantálja, hogy mindannyian konzisztensek a kóddal. Sajnos a meglévő eszközökkel ez még nem teljesen lehetséges (legalábbis tudomásom szerint), mivel a tényleges eszközök nem képesek csak a forráskód alapján, jelentős kézi beavatkozás nélkül bármilyen pontos és értelmes diagramot létrehozni. Len Bass azt mondta, hogy “az ideális fejlesztőkörnyezet olyan, amelyhez a dokumentáció lényegében ingyenesen, egy gombnyomással elérhető”, ami implicit módon automatikusan generálja a diagramokat, de ezt a pontot még nem értük el.

A második megközelítés az lenne, hogy először a diagramokat egy erre a célra kifejlesztett eszközzel tervezzük meg, amely aztán létrehozza a forráskód vázát (pl. komponensek/csomagok határokkal, API-kkal), amelyet a fejlesztők később a kód kitöltéséhez használnak. Ily módon az architektúrában bekövetkező minden változást magából a diagramból kell kiváltani, amely automatikusan regenerálhatja vagy frissítheti a kódvázlatot.

Az utolsó esetben a diagramokat kézzel kell frissíteni minden alkalommal, amikor egy új – az architektúratervezésre hatást gyakorló – funkció bevezetésre kerül. Annak biztosítása érdekében, hogy minden kódváltoztatás megjelenjen a diagramokban, ajánlott, hogy a diagramok frissítése a fejlesztési folyamat során elvégzett meghatározás része legyen. Ez a forgatókönyv kevésbé ajánlott, mert könnyen elavult vagy inkonzisztens diagramokhoz vezethet (pl. a fejlesztők gyakran elfelejtik vagy nincs kedvük frissíteni a diagramokat), és sajnos ez még mindig előfordul a projektek többségében.

A meglévő eszközöket figyelembe véve az én ajánlásom a vegyes megoldás; az automatikusan és a manuálisan készített diagramok keverése. Például próbáljon meg automatikusan olyan diagramokat generálni, amelyeket a forráskódon alapuló eszközökkel ésszerűen, túl sok zaj (pl. túl zsúfolt vagy értelmetlen információk) nélkül lehet megjeleníteni. Ebbe a kategóriába sorolhatjuk a nagyfokú változékonysággal rendelkező (pl. gyakori fejlesztési változásokra hajlamosabb, általában alacsonyabb absztrakcióval rendelkező) diagramokat, vagy éppen ellenkezőleg, a statikus diagramokat. Néhány ilyen diagram utalhat a kontextusdiagramokra, referenciaarchitektúra-diagramokra, csomagdiagramokra, osztálydiagramokra, entitásdiagramokra stb. Mindazonáltal egyes esetekben pusztán a forráskód alapján nem nyilvánvaló, hogy a rendszer hogyan felel meg bizonyos minőségi jellemzőknek (pl. rendelkezésre állás, skálázhatóság, teljesítmény), ezért a diagramok automatikus létrehozása nem elegendő lehetőség. Ezt ki kell egészíteni kézzel modellezett diagramokkal. Néhány példa az ilyen diagramokra: szekvencia-diagramok, állapotdiagramok, párhuzamossági diagramok, telepítési diagramok, működési diagramok stb.

Milyen komplikációk (vagy egyszerűsítések) merülnek fel az architektúra-diagramok esetében, amikor modern architektúrákról van szó (pl.pl. mikroszolgáltatások)?

A mikroszolgáltatások vagy bármely más modern architektúrális stílus (pl. szerver nélküli, eseményvezérelt) csak a rendszer szerkezetét, a komponensek egymás közötti kommunikációját (pl. a köztük lévő kapcsolatokat) és az őket irányító elveket határozza meg. Személy szerint nem hiszem, hogy az architekturális stílusnak meg kellene változtatnia az ábrák (és implicit módon az architekturális leírás) létrehozása körüli logikát vagy koncepciókat, és azt sem, hogy mit kell megörökíteniük. Mindazonáltal, amikor modern rendszerarchitektúrákról beszélünk, amelyek általában magasabb szintű komplexitással rendelkeznek a régi és klasszikus rendszerekhez képest (pl. monolit), ezek mindenképpen hatással vannak az architektúra leírására és implicit módon a diagramokra is, abban az értelemben, hogy több szempontot kell figyelembe venni. Ilyen megfontolások lehetnek az elosztott komponensek számának (pl. elosztott mikroszolgáltatások), az egyes komponensek típusának, a komponensek egymással való kommunikációjának (pl. határok, API-k, üzenetek), életciklusuknak és az egyes komponensek tulajdonosának megértésével kapcsolatosak.

Mindezeket figyelembe véve a rendszer dekompozícióját, fejlesztését, telepítését és működőképességét megragadó nézeteket alapértelmezetten figyelembe kell venni. Képzeljünk el például egy olyan rendszert, amely lenyűgöző számú mikroszolgáltatással rendelkezik; ilyen esetben a diagramok száma jelentősen megnövekedhet, mivel minden egyes mikroszolgáltatás végül saját diagramokkal rendelkezhet. A konzisztenciával (pl. az egyik szolgáltatás API-jának módosítása hatással van a többi X szolgáltatásra, ezért az összes érintett diagramot frissíteni kell), a széttagoltsággal (pl. az elosztott szolgáltatások közötti nagyfokú rendelkezésre állás vagy teljesítmény nem egy diagramban van összevonva) vagy az átfogó problémákkal (pl. ki a felelős az olyan szempontok összevont módon történő bemutatásáért, mint a felügyelet vagy a biztonság a teljes rendszerelemekben) kapcsolatos kérdések nem feltétlenül kezelhetők könnyen. Mindezeken túlmenően a projektfejlesztés során, sőt, azt követően is, annak fenntartása érdekében a csapatok együttélésével és együttműködésével kapcsolatos kihívások merülhetnek fel.

Összefoglalva, a komplex architektúrájú modern rendszerek további aggályokat vethetnek fel, amelyek már a diagramok szintjén is bonyodalmakhoz vezethetnek.

A szerzőről

Ionut Balosin szoftverépítész és független műszaki tréner. Rendszeres előadója a világ szoftverfejlesztési konferenciáinak és találkozóinak, ahol előadásokat, képzéseket és workshopokat tart. További részletekért kérjük, látogasson el a weboldalára.