Konsten att skapa arkitekturdiagram

Vid någon tidpunkt, i varje mjukvaruprojekt som vi är involverade i, kan det finnas ett behov av att skapa arkitekturdiagram. Oavsett om vi följer en formell arkitekturmodell (t.ex. Kruchten 4+1, Rozanski & Woods osv.) eller inte, finns det ett behov av att dokumentera vissa delar av applikationen genom att skapa diagram. Inom mjukvaruarkitektur skapas sådana diagram i enlighet med vyer som är relaterade till en specifik synvinkel som kan vara en del av en modell, men i den aktuella artikeln föredrar jag att hålla mig till termen arkitektoniskt diagram och inte vara särskilt formell; alla andra aspekter är inte tänkta att täckas här.

Baserat på min erfarenhet som mjukvaruarkitekt och teknisk utbildare finns det en hel del diskrepanser mellan olika projekt och inom projektteamet, från utvecklare till utvecklare, i sättet att skapa arkitektoniska diagram. Jag såg många problem som rör inkonsekvens, fragmentering och granularitet i den återgivna informationen och diagrammens utseende. I jämförelse med en arkitekturmodell som måste vara formell och standardiserad är diagrammen kanske inte nödvändigtvis formaliserade eller följer en specifik standard.

När det gäller diagram måste de ändå vara självbeskrivande, konsekventa, tillräckligt exakta och kopplade till koden. Därför är det viktigt att varje arkitekt eller mjukvaruingenjör förlitar sig på flera riktlinjer när de skapar arkitekturdiagram, eftersom de är den gemensamma grunden för att kommunicera applikationens arkitektur över tid (t.ex. struktur, element, relationer, egenskaper, principer) och mellan olika intressenter som har olika tekniska bakgrunder och intressen.

Högsta fallgropar vid utformning av arkitekturdiagram

För att gå djupare in på möjliga problem vill jag ha en analogi till ett engelskt idiom som säger att ”en bild är mer värd än tusen ord”. Enligt denna wikiförklaring ”hänvisar det till uppfattningen att en komplex idé kan förmedlas med bara en enda stillbild eller att en bild av ett ämne förmedlar dess innebörd eller essens mer effektivt än vad en beskrivning gör”. Samma koncept gäller för ett arkitektoniskt diagram: om det väcker fler frågor än svar är diagrammet inte väl skapat. Låt inte ett arkitekturdiagram kräva tusentals ord eller förtydliganden!

Exempel på ett felaktigt arkitekturdiagram. Det lider av de flesta av de problem som beskrivs nedan

Låt oss nu gå igenom en lista över fallgropar som kan hindra processen att skapa arkitekturdiagram på rätt sätt.

Vad betecknar en ruta eller form?

• Om man använder någon form av ruta eller form som inte är ordentligt dokumenterad kan det leda till flera tolkningar. Den kan förknippas med antingen en datamängd, ett gäng kod eller en process. Bara en enkel ruta i ett diagram kan väcka flera tvivel och det är mycket viktigt att undvika dem genom att uttryckligen lägga till detaljer om rutans eller formens betydelse i diagramlegenden.

Vad representerar olika kanter i en form?

• Varje kant i en form (t.ex. streckad, streckad, etc.) kan missförstås i fallet med ett dåligt diagram. Hänvisar en specifik kant till en specifik komponenttyp (t.ex. hänvisar en streckad linje till en container, en mikrotjänst, ett lager osv.), eller är det bara designerns preferens att ha ett rikt utseende och en riklig känsla? Undvik sådan förvirring genom att tillhandahålla exakta uppgifter i legenddiagrammet när du väljer flera eller icke-standardiserade kanter.

Vad betecknar en linje eller en pil?

• En linje eller en pil kan tolkas antingen som ett dataflöde (t.ex. dataflöde från system A till system B) eller som ett förhållande mellan element (t.ex. komponent A är beroende av komponent B). I de flesta fall konvergerar inte de relationer eller dataflöden som representeras av pilar i samma riktning och det är viktigt att uttryckligen skriva detta i diagramlegenden.

Vad är den kommunikations-/associationstyp som indikeras av en linje eller en pil?

• Även om linjen hänvisar till ett dataflöde eller en relation mellan komponenter måste den kommunikationstyp (t.ex. i fråga om dataflöde) eller den associationstyp (t.ex. i fråga om relation) som betecknas av den linjen eller pilen vara detaljerad. Om linjen till exempel representerar ett dataflöde kan kommunikationen vara synkron eller asynkron, men om linjen hänvisar till en relation kan den representeras av ett beroende, arv, implementering osv. Alla dessa detaljer måste finnas med i diagrammet.

Vad betyder den färgen?

• Att ha ett ”perrot” policolor-diagram (t.ex. flera färger för rutor, linjer) utan någon korrekt dokumenterad avsikt kan ge upphov till flera frågor (t.ex. varför är vissa rutor gröna och andra röda? Varför är vissa linjer svarta och andra blå?). Färgschemat är mindre viktigt i ett diagram, och att använda ett stort antal färger ger inte alltför mycket ytterligare innehåll eller värdefull information. Ett diagram kan också vara självförklarande och väl utformat bara genom att använda svarta och vita färger, om det inte finns ett strikt krav på att betona vissa delar av diagrammet genom att använda särskiljande färger. I vilket fall som helst är det alltid bättre att hålla sig till enkelhet när det gäller de färger som används, men om så inte är fallet, glöm inte att specificera valet.

Missing relationships between diagram elements or isolated entities

• Missing relationships between elements or isolated entities in a diagram might be a clue of incompleteness. Ur både ett strukturellt och beteendemässigt perspektiv bör varje element eller enhet vara beroende av/ha en relation (representerad av en linje eller en pil) med en annan del av systemet som representeras av ett annat element.

Missvisande/undokumenterade akronymer eller alltför vaga/generella termer

• När man använder en etikett för ett element i ett diagram rekommenderas att man inte använder en missvisande eller odokumenterad akronym som kan orsaka förvirring. Bara en bokstavsföljd (t.ex. TFH, RBPM) betyder ingenting utan en ordentlig förklaring på diagramelementet eller, ännu bättre, i diagramlegenden (t.ex. TFH – ticket feed handler, RBPM – rates business process manager).

• Ett annat kännetecken för namngivning av diagramelement är extremt vaga eller generiska termer (t.ex. affärslogik, integrationslogik) som inte ger så mycket värdefull information eftersom namnen inte är korrekt självbeskrivande. Detta problem kan också finnas på kodnivå, och förslaget skulle vara att alltid använda självförklarande och suggestiva namn genom att följa principerna för ren kod.

På diagrammen betonas teknik, ramverk, programmerings- eller skriptspråk, IDE eller utvecklingsmetodik

• Arkitektonisk utformning är inte relaterad till eller i grunden baserad på någon teknik, ramverk, programmerings- eller skriptspråk, IDE eller utvecklingsmetodik. Alla dessa kommer senare i processen för att hjälpa till att bygga arkitekturen, men de är inte den centrala punkten. De bör inte ingå i diagrammen, utan anges i arkitekturbeskrivningen, inklusive resonemanget kring valet av dem.

Blandning av körtids- och statiska element i samma diagram

• Körtidselement (t.ex. trådar, processer, virtuella maskiner, containrar, tjänster, brandväggar, dataregister osv.) finns inte vid kompileringstid och det rekommenderas att man undviker att blanda dessa element med de statiska (t.ex. komponenter, paket, klasser) i samma diagram. Det finns särskilda diagramtyper (t.ex. samtidighetsdiagram, driftsättningsdiagram) som i första hand är inriktade på element under körtid och det är viktigt att skilja mellan dessa två elementkategorier och att undvika att blanda dem så mycket som möjligt.

Gör antaganden som ”Jag kommer att beskriva det här verbalt” och ”Jag kommer att förklara det senare”

• Allt som inte beskrivs i själva diagrammet saknas, och det finns inget utrymme för att ge verbala detaljer för att komplettera ett diagram. Varför? Därför att alla förklaringar som nämns muntligt men som inte finns med i diagrammet går förlorade, och när andra intressenter (t.ex. utvecklare, arkitekter) senare läser diagrammet kommer de inte att känna till dessa förklaringar. Försök att inkludera alla nödvändiga detaljer i ett diagram för att undvika behov av ytterligare förtydliganden.

Konflikterande detaljnivåer eller blandade abstraktioner

• Att lägga till element relaterade till olika abstraktionsnivåer i samma diagram kan skapa konflikter, eftersom de ses från olika perspektiv. Om man till exempel lägger till komponenter i ett arkitektoniskt kontextdiagram eller klasser i ett distributionsdiagram kan det leda till att syftet med själva diagrammet avviker. När du skapar ett diagram bör du försöka hålla dig till samma abstraktionsnivå.

Röriga eller alltför vaga diagram som försöker visa för mycket eller otillräcklig detaljnivå

• ”Allting bör göras så enkelt som möjligt, men inte enklare” är ett välkänt citat av Albert Einstein. Detta gäller även för arkitekturdiagram; nivån och granulariteten på den insamlade informationen bör väljas på ett meningsfullt sätt. Detta är inte lätt; det beror på vilken arkitekturmodell som används, arkitektens erfarenhet och systemets komplexitet.

Riktlinjer att följa vid skapandet av arkitekturdiagram

Avse de ovan nämnda fallgroparna, som måste ingå i en checklista för förutsättningarna för att undvika dem, finns det också allmänna riktlinjer för hur man skapar diagram på rätt sätt:

Välj det optimala antalet diagram

• Som Philippe Kruchten sa: ”Arkitektur är ett komplext odjur. Att använda en enda ritning för att representera arkitektur resulterar i en obegriplig semantisk röra”. För att dokumentera moderna system kan vi inte sluta med endast en sorts diagram, men när vi skapar arkitekturdiagram är det inte alltid okomplicerat vilka diagram som ska väljas och hur många av dem som ska skapas. Det finns flera faktorer att ta hänsyn till innan man fattar ett beslut, till exempel arkitekturens karaktär och komplexitet, programvaruarkitektens kompetens och erfarenhet, tillgänglig tid, mängden arbete som krävs för att underhålla dem och vad som är meningsfullt eller användbart för att tillgodose intressenternas önskemål. En nätverksingenjör vill till exempel förmodligen se en explicit nätverksmodell med värdar, kommunikationsportar och protokoll; en databasadministratör är intresserad av hur systemet manipulerar, hanterar och distribuerar data osv. Baserat på alla dessa aspekter rekommenderas att man väljer det optimala antalet diagram, oavsett vilket antal det är.
• Om det inte finns tillräckligt många diagram (t.ex. underdokumentation) kan delar av arkitekturen vara dolda eller odokumenterade; å andra sidan, om det finns för många (t.ex. överdokumentering), kan den ansträngning som krävs för att hålla dem konsekventa, uppdaterade och inte fragmenterade öka avsevärt.

Håller strukturell och semantisk konsistens mellan diagrammen

• Varje diagram bör vara konsekvent med de andra när det gäller rutor, former, ramar, gränser, linjer, färger osv. Det strukturella utseendet bör vara detsamma och varje intressent bör inte ha några svårigheter att förstå diagram som skapats av olika utvecklare inom ett team. Helst bör man hålla sig till ett gemensamt diagramverktyg och återanvända det i alla projekt.
• Från den semantiska synvinkeln bör alla dessa diagram regelbundet synkroniseras med de senaste kodändringarna och mellan dem, eftersom en ändring i ett diagram kan påverka andra. Denna process kan utlösas manuellt eller automatiskt med hjälp av ett modelleringsverktyg. Det sistnämnda är den föredragna mekanismen, men detta beror på projekt till projekt, i alla fall är tanken att upprätthålla konsistens mellan diagram och kod, oberoende av metod eller verktyg. Simon Brown sa ”diagram är inte användbara för arkitektoniska förbättringar om de inte är kopplade till koden”, vilket understryker idén om semantisk konsistens.

Förhindra fragmentering av diagram

• Att ha flera diagram kan göra den arkitektoniska beskrivningen svårbegriplig, men det kan också innebära en betydande ansträngning för att underhålla dem. Som bieffekt kan fragmentering uppstå (t.ex. kan två eller flera diagram illustrera samma kvalitetsattribut – prestanda, skalbarhet osv. – men vart och ett av dem är individuellt ofullständigt). I sådana fall rekommenderas att antingen ta bort de diagram som inte återspeglar relevanta kvalitetsattribut (kopplade till arkitektoniskt viktiga krav) eller, ännu bättre, att slå ihop diagram (t.ex. samtidighet och utplacering).

Håller spårbarhet mellan diagram

• Att kunna kontrollera historiken, göra jämförelser mellan olika diagramversioner plus att enkelt kunna återgå till en tidigare version är också viktigt. Att använda ett modelleringsverktyg som inte tillåter detta kan vara ett hinder. De senaste trenderna i branschen bygger på att man använder ett enkelt och intuitivt klartextspråk för att generera diagrammen ur det, vilket verkar lösa problemet med spårbarhet. En annan fördel med ett sådant tillvägagångssätt är att det implicit säkerställer en homogen strukturell konsistens mellan diagrammen.

Lägg till legender bredvid arkitekturdiagram

• Om du inte följer ett standardiserat arkitekturbeskrivningsspråk (t.ex. UML, ArchiMate), ska du specificera varje del av diagrammet i legenden (t.ex. lådor, former, ramar, linjer, färger, akronymer, etc).
• Om detta inte är fallet kan man i legenden bara lägga till det arkitektoniska beskrivningsspråket som en nyckel och det finns inget behov av ytterligare förklaringar, eftersom varje läsare kommer att följa de språkspecifika detaljerna för att förstå diagrammet.

Gör det arkitektoniska beskrivningsspråket (t.ex. UML, ArchiMate, etc.) någon skillnad?

Det finns många åsikter om vilket som är det rätta beskrivningsspråket som bör antas i ett projekt. Vissa kan hävda att UML är stelt och inte tillräckligt flexibelt för att modellera den arkitektoniska utformningen, en åsikt som jag håller med om. I vissa fall kan det dock vara mer än tillräckligt för att dokumentera grunderna för en arkitektur utan att förlita sig på UML:s utvidgningsfunktioner som profiler och stereotyper. Genom att ta en titt på andra beskrivningsspråk kan vi se att ArchiMate är mer kraftfullt och lämpligt för modellering av företagssystem jämfört med UML; det finns också BPMN som är särskilt inriktat på affärsprocesser osv. Jämförelserna kan fortsätta, men jag har inte för avsikt att göra någon djupgående genomgång över dem, eftersom detta inte är målet med den här artikeln.

Att ha ett arkitekturbeskrivningsspråk som är tillräckligt omfattande och flexibelt är ett stort steg framåt och detta bör vara ett solitt kriterium när man väljer det. Men från mitt perspektiv ligger den verkliga orsaken någon annanstans och är relaterad till det faktum att arkitektonisk dokumentation inte skapas alls. Människor tycker ofta att det är tråkigt, onödigt eller meningslöst att skapa den. Antalet programvaruprojekt utan eller med olämplig dokumentation är enormt. Jag tror inte att människor skapar eller deltar intensivt i skapandet av arkitekturdiagram med hjälp av ett olämpligt beskrivningsspråk, och om de skulle ersätta dem med ett bättre skulle resultaten bli mycket annorlunda. Nej, människor skapar ingen arkitekturdokumentation (inklusive arkitekturdiagram), och ännu värre är att de flesta av dem inte har någon aning om hur man skapar den på rätt sätt. Det är dessa saker vi måste ta itu med först – att förstå varför dokumentation är viktig och hur man skapar den på rätt sätt (genom att utbilda mjukvaruingenjörer); sedan kommer valet av rätt verktyg naturligt.

Hur kan diagrammen hållas uppdaterade när systemet utvecklas och förändringar i arkitekturen materialiseras

Det finns några få tillvägagångssätt för att hålla diagrammen uppdaterade; nedan kommer jag att redogöra för tre av dem. Det första alternativet, och det enklaste, skulle vara att automatiskt generera diagram ur källkoden, som är grundsanning. Detta garanterar att de alla är konsekventa i förhållande till koden. Tyvärr är detta med befintliga verktyg ännu inte helt möjligt (åtminstone inte vad jag vet), eftersom de faktiska verktygen inte kan skapa någon typ av korrekt och meningsfullt diagram enbart baserat på källkoden, utan betydande manuellt ingripande. Len Bass sade att ”den ideala utvecklingsmiljön är en miljö där dokumentationen är tillgänglig i princip gratis genom att trycka på en knapp”, vilket implicit innebär att diagrammen genereras automatiskt, men vi har inte nått den punkten.

Det andra tillvägagångssättet skulle vara att först utforma diagrammen med hjälp av ett särskilt verktyg som sedan genererar källkodsskeletten (t.ex. komponenter/paket med avgränsningar, API:er) som senare används av utvecklarna för att fylla i koden. På detta sätt måste varje ändring i arkitekturen utlösas från själva diagrammet som automatiskt kan regenerera eller uppdatera kodskelettet.

Det sista fallet innebär att man manuellt uppdaterar diagrammen varje gång en ny funktion – som har en inverkan på den arkitektoniska utformningen – implementeras. För att vara säker på att alla kodändringar återspeglas i diagrammen rekommenderas att uppdatering av diagrammen att vara en del av definitionen av gjort i utvecklingsprocessen. Detta scenario rekommenderas mindre eftersom det lätt kan leda till föråldrade eller inkonsekventa diagram (t.ex. glömmer utvecklarna ofta eller är inte på humör att uppdatera diagrammen) och tyvärr sker detta fortfarande i flertalet projekt.

Med hänsyn till befintliga verktyg är min rekommendation att ha en blandning; att blanda automatiskt och manuellt skapade diagram. Försök till exempel att automatiskt generera diagram som på ett rimligt sätt kan återges av verktyg baserade på källkod utan alltför mycket brus (t.ex. alltför rörig eller meningslös information). I den här kategorin kan vi inkludera antingen diagram med en hög grad av volatilitet (t.ex. mer benägna till frekventa utvecklingsändringar, som vanligtvis har en lägre abstraktion) eller, tvärtom, statiska diagram. Några sådana diagram kan vara kontextdiagram, referensarkitekturdiagram, paketdiagram, klassdiagram, entitetsdiagram osv. I vissa fall är det dock inte uppenbart enbart utifrån källkoden hur systemet uppfyller vissa kvalitetsegenskaper (t.ex. tillgänglighet, skalbarhet, prestanda), och därför är det inte tillräckligt att automatiskt skapa diagram. Det måste kompletteras med manuellt modellerade diagram. Några exempel på sådana diagram är sekvensdiagram, tillståndsdiagram, samtidighetsdiagram, driftsdiagram, driftsdiagram osv.

Vilka komplikationer (eller förenklingar) uppstår för arkitekturdiagram när man hanterar moderna arkitekturer (t.ex.

Mikrotjänster eller någon annan modern arkitekturstil (t.ex. serverlös, händelsestyrd) styr endast systemets struktur, hur komponenterna kommunicerar med varandra (t.ex. relationer mellan dem) och vilka principer som styr dem. Personligen anser jag inte att arkitekturstilen bör förändra resonemanget eller koncepten kring skapandet av diagrammen (och underförstått den arkitektoniska beskrivningen), och inte heller vad de bör fånga upp. När vi talar om moderna systemarkitekturer, som vanligtvis har högre komplexitetsnivåer jämfört med gamla och klassiska system (t.ex. monolit), har de definitivt en inverkan på arkitekturbeskrivningen och underförstått på diagrammen, i den bemärkelsen att det finns flera överväganden att ta hänsyn till. Sådana överväganden kan gälla förståelsen av antalet distribuerade komponenter (t.ex. distribuerade mikrotjänster), typen av varje komponent, hur komponenterna kommunicerar med varandra (t.ex. gränser, API:er, meddelanden), deras livscykel och vem som äger varje komponent.

Med hänsyn till allt detta bör synpunkter som fångar upp systemets nedbrytning, utveckling, driftsättning och driftbarhet beaktas som standard. Föreställ dig till exempel ett system med ett imponerande antal mikrotjänster. I ett sådant fall kan antalet diagram öka avsevärt eftersom varje mikrotjänst kan sluta med att ha en egen uppsättning diagram. Frågor som rör konsistens (t.ex. att ändra API:et för en tjänst påverkar andra X-tjänster, vilket innebär att alla berörda diagram måste uppdateras), fragmentering (t.ex. att hög tillgänglighet eller prestanda mellan distribuerade tjänster inte konsolideras i ett diagram) eller övergripande frågor (t.ex. vem som ansvarar för att på ett konsoliderat sätt illustrera aspekter som övervakning eller säkerhet över hela systemelement) kanske inte är lätta att hantera. Dessutom kan det finnas utmaningar i samband med teamens samexistens och samarbete under projektutvecklingen, och även efteråt, för att upprätthålla den.

För att sammanfatta kan man säga att moderna system med komplexa arkitekturer kan medföra ytterligare problem som kan leda till komplikationer även på diagramnivå.

Om författaren

Ionut Balosin är mjukvaruarkitekt och oberoende teknisk utbildare. Han är en regelbunden talare på mjukvaruutvecklingskonferenser och meetups runt om i världen, där han håller presentationer, utbildningar och workshops. Mer information finns på hans webbplats.