Arta de a crea diagrame arhitecturale

La un moment dat, în fiecare proiect software în care suntem implicați, ar putea fi nevoie să creăm diagrame arhitecturale. Indiferent dacă urmăm un model arhitectural formal (de exemplu, Kruchten 4+1, Rozanski & Woods, etc.) sau nu, există necesitatea de a documenta unele părți ale aplicației prin crearea de diagrame. În arhitectura software, astfel de diagrame sunt create în conformitate cu punctele de vedere care sunt legate de un anumit punct de vedere care ar putea face parte dintr-un model, dar în articolul de față prefer să rămânem la termenul de diagramă arhitecturală și să nu fim foarte formali; toate celelalte aspecte nu au intenția de a fi acoperite aici.

Pe baza experienței mele ca arhitect software și formator tehnic, există multe discrepanțe între proiecte și în interiorul echipei de proiect, de la un dezvoltator la altul, în ceea ce privește modul în care sunt create diagramele arhitecturale. Am văzut o mulțime de probleme în ceea ce privește inconsecvența, fragmentarea și granularitatea informațiilor redate și aspectul diagramelor. În comparație cu un model arhitectural care trebuie să fie formal și standardizat, diagramele ar putea să nu fie neapărat formalizate sau să urmeze un standard specific.

Cu toate acestea, diagramele trebuie să fie autodescriptive, coerente, suficient de precise și conectate la cod. De aceea, este important ca fiecare arhitect sau inginer software să se bazeze pe mai multe linii directoare atunci când creează diagrame de arhitectură, deoarece acestea reprezintă baza comună de comunicare a arhitecturii aplicației de-a lungul timpului (de exemplu, structură, elemente, relații, proprietăți, principii) și între diferite părți interesate care au diferite pregătiri tehnice și preocupări.

Currente capcane la proiectarea diagramelor de arhitectură

Înainte de a aprofunda posibilele probleme, aș dori să fac o analogie cu un idiom englezesc care spune că „o imagine face cât o mie de cuvinte”. Conform acestei explicații de pe wiki, „se referă la noțiunea că o idee complexă poate fi transmisă doar cu o singură imagine statică sau că o imagine a unui subiect transmite sensul sau esența acestuia mai eficient decât o face o descriere”. Același concept se aplică și în cazul unei diagrame de arhitectură: dacă aceasta ridică mai multe întrebări decât răspunsuri, diagrama nu este bine creată. Nu lăsați ca o diagramă arhitecturală să necesite mii de cuvinte sau clarificări!

Exemplu de diagramă arhitecturală necorespunzătoare. Suferă majoritatea problemelor descrise mai jos

Să parcurgem acum o listă de capcane care ar putea împiedica procesul de creare corectă a diagramelor de arhitectură.

Ce denotă o cutie sau o formă?

• Utilizarea oricărui tip de cutie sau formă care nu este documentată corespunzător ar putea cauza interpretări multiple. Ea ar putea fi asociată fie cu o bucată de date, fie cu o grămadă de cod, fie cu un proces. Doar o simplă cutie într-o diagramă ar putea ridica mai multe îndoieli și este foarte important să le evitați prin adăugarea explicită de detalii despre semnificația cutiei sau formei în legenda diagramei.

Ce reprezintă diferitele muchii ale unei forme?

• Care muchie a unei forme (de exemplu, punctată, punctată etc.) poate fi înțeleasă greșit în cazul unei diagrame slabe. O anumită margine se referă la un anumit tip de componentă (de exemplu, o linie punctată se referă la un container, un microserviciu, un strat etc.) sau este doar o preferință a designerului de a avea un aspect bogat? Evitați astfel de confuzii furnizând detalii precise în diagrama de legendă atunci când alegeți margini multiple sau non-standard.

Ce denotă o linie sau o săgeată?

• O linie sau o săgeată poate fi interpretată fie ca un flux de date (de exemplu, datele circulă de la sistemul A la sistemul B), fie ca o relație între elemente (de exemplu, componenta A depinde de componenta B). În cele mai multe cazuri, relațiile sau fluxurile de date reprezentate de săgeți nu converg în aceleași direcții și este important să se scrie explicit acest lucru în legenda diagramei.

Care este tipul de comunicare/asociere indicat de o linie sau de o săgeată?

• Chiar dacă linia se referă la un flux de date sau la o relație între componente, tipul de comunicare (de exemplu, în cazul fluxului de date) sau tipul de asociere (de exemplu, în cazul relației) denotat de acea linie sau săgeată trebuie să fie detaliat. De exemplu, în cazul în care linia reprezintă un flux de date, comunicarea poate fi sincronă sau asincronă, dar dacă linia se referă la o relație, aceasta poate fi reprezentată de o dependență, o moștenire, o implementare etc. Toate aceste detalii trebuie să fie prezente în legenda diagramei.

Ce înseamnă acea culoare?

• Având o diagramă policoloră „perrot” (de exemplu, mai multe culori pentru cutii, linii) fără o intenție documentată corespunzător ar putea ridica multiple întrebări (de exemplu, de ce sunt unele cutii verzi și altele roșii? De ce unele linii sunt negre și altele albastre?). Schema de culori este mai puțin importantă într-o diagramă, iar utilizarea unui număr bogat de culori nu aduce prea mult conținut suplimentar sau informații valoroase. O diagramă ar putea fi, de asemenea, autoexplicativă și bine proiectată doar prin utilizarea culorilor alb-negru, cu excepția cazului în care există o constrângere strictă de a sublinia anumite părți ale diagramei prin utilizarea unor culori care se disting. În orice caz, este întotdeauna mai bine să rămânem la simplitate în ceea ce privește culorile folosite, dar dacă nu este cazul, nu uitați să detaliați alegerea făcută.

Relații lipsă între elementele diagramei sau entități izolate

• Relațiile lipsă între elementele sau entitățile izolate dintr-o diagramă ar putea fi un indiciu al incompletitudinii. Atât din punct de vedere structural, cât și comportamental, fiecare element sau entitate ar trebui să se bazeze pe / să aibă o relație (reprezentată printr-o linie sau o săgeată) cu o altă parte a sistemului reprezentată de un element diferit.

Acronime înșelătoare/nedocumentate sau termeni prea vagi/generici

• Când se utilizează o etichetă pentru un element într-o diagramă, se recomandă să nu se utilizeze niciun acronim înșelător sau nedocumentat care ar putea provoca confuzii. Doar o secvență de litere (de exemplu, TFH, RBPM) nu înseamnă nimic fără o explicație adecvată pe elementul diagramei sau, chiar mai bine, în legenda diagramei (de exemplu, TFH – ticket feed handler, RBPM – rates business process manager).

• O altă caracteristică a denumirii elementelor diagramei se referă la termeni extrem de vagi sau generici (de exemplu, logică de afaceri, logică de integrare) care nu aduc prea multe informații valoroase deoarece denumirile lor nu sunt autodescriptive în mod corespunzător. Această problemă ar putea să rezidă și la nivel de cod, iar sugestia ar fi să se utilizeze întotdeauna nume autoexplicative și sugestive, urmând principiile codului curat.

Emiterea în diagrame a tehnologiilor, cadrelor, limbajelor de programare sau de scripting, IDE sau metodologiei de dezvoltare

• Proiectarea arhitecturală nu este legată sau bazată în mod fundamental pe nicio tehnologie, cadru, limbaj de programare sau de scripting, IDE sau metodologie de dezvoltare. Toate acestea vin mai târziu în cadrul procesului pentru a ajuta la construirea arhitecturii, dar nu reprezintă punctul central. Ele nu ar trebui să fie incluse în diagrame, ci declarate în descrierea arhitecturii, inclusiv în raționamentul care a stat la baza alegerii lor.

Mixați elemente de timp de execuție și elemente statice în aceeași diagramă

• Elementele de timp de execuție (de exemplu, fire de execuție, procese, mașini virtuale, containere, servicii, firewall-uri, depozite de date etc.) nu sunt prezente în momentul compilării și se recomandă să se evite amestecarea acestor elemente cu cele statice (de exemplu, componente, pachete, clase) în aceeași diagramă. Există tipuri de diagrame dedicate (de exemplu, diagrama de concurență, diagrama de desfășurare) care se concentrează în principal pe elementele din timpul de execuție și este important să se facă distincția între aceste două categorii de elemente și să se evite pe cât posibil amestecarea lor.

Faceți presupuneri de genul „voi descrie verbal acest lucru” și „îl voi explica mai târziu”

• Tot ceea ce nu este descris de diagrama în sine lipsește și nu există loc pentru a oferi detalii verbale care să completeze o diagramă. De ce? Pentru că toate explicațiile menționate verbal, dar care nu sunt surprinse în diagramă, se pierd, iar mai târziu, când alte părți interesate (de exemplu, dezvoltatorul, arhitectul) vor citi diagrama, nu vor fi la curent cu aceste explicații. Încercați să includeți toate detaliile necesare într-o diagramă pentru a evita orice nevoie de clarificări suplimentare.

Niveluri conflictuale de detalii sau abstracțiuni mixte

• Adăugarea de elemente legate de diferite niveluri de abstractizare în aceeași diagramă ar putea intra în conflict, deoarece acestea sunt văzute din perspective diferite. De exemplu, adăugarea de componente la o diagramă de context arhitectural sau de clase la o diagramă de implementare ar putea diverge de la scopul diagramei în sine. Atunci când creați o diagramă, încercați să rămâneți la același nivel de abstractizare.

Diagrame aglomerate sau prea vagi care încearcă să arate un nivel de detaliu prea mare sau insuficient

• „Totul ar trebui să fie făcut cât mai simplu posibil, dar nu mai simplu” este un citat binecunoscut aparținând lui Albert Einstein. Acest lucru este valabil și pentru diagramele de arhitectură; nivelul și granularitatea informațiilor capturate ar trebui să fie alese în mod semnificativ. Acesta nu este un lucru ușor; depinde de modelul arhitectural utilizat, de experiența arhitectului și de complexitatea sistemului.

Direcții de urmat la crearea diagramelor de arhitectură

Pe lângă capcanele de mai sus, care trebuie să facă parte dintr-o listă de verificare a condițiilor prealabile pentru a le evita, există, de asemenea, îndrumări generale cu privire la modul în care se pot crea corect diagramele:

Alegeți numărul optim de diagrame

• Cum spunea Philippe Kruchten, „arhitectura este o fiară complexă. Folosirea unei singure schițe pentru a reprezenta arhitectura duce la o dezordine semantică neinteligibilă”. Pentru a documenta sistemele moderne nu putem ajunge să avem un singur tip de diagramă, dar atunci când creăm diagrame de arhitectură nu este întotdeauna simplu ce diagrame să alegem și câte dintre ele să creăm. Există mai mulți factori care trebuie luați în considerare înainte de a lua o decizie; de exemplu, natura și complexitatea arhitecturii, abilitățile și experiența arhitectului software, timpul disponibil, volumul de muncă necesar pentru a le întreține și ceea ce are sens sau este util pentru a răspunde preocupărilor părților interesate. De exemplu, un inginer de rețea va dori probabil să vadă un model de rețea explicit, inclusiv gazde, porturi de comunicare și protocoale; un administrator de baze de date este preocupat de modul în care sistemul manipulează, gestionează și distribuie datele etc. Pe baza tuturor acestor aspecte, se recomandă să se aleagă numărul optim de diagrame, oricare ar fi acesta.
• Dacă există un număr insuficient de diagrame (de exemplu, subdocumentare), anumite părți ale arhitecturii ar putea fi ascunse sau nedocumentate; pe de altă parte, dacă există prea multe (de ex. supra-documentare), efortul necesar pentru a le menține consecvente, actualizate și nu fragmentate ar putea crește considerabil.

Păstrați consecvența structurală și semantică între diagrame

• Care diagramă ar trebui să fie consecventă cu celelalte în ceea ce privește casetele, formele, marginile, liniile, culorile, etc. Aspectul structural ar trebui să fie același și fiecare parte interesată nu ar trebui să aibă dificultăți în înțelegerea diagramelor create de diferiți dezvoltatori din cadrul unei echipe. În mod ideal, respectați un instrument comun de creare a diagramelor și reutilizați-l în toate proiectele.
• Din punct de vedere semantic, toate aceste diagrame ar trebui să fie sincronizate periodic cu cele mai recente modificări de cod și între ele, deoarece o modificare într-o diagramă ar putea avea un impact asupra celorlalte. Acest proces poate fi declanșat manual sau automat prin utilizarea unui instrument de modelare. Acesta din urmă este mecanismul preferat, dar acest lucru depinde de la proiect la proiect, în toate cazurile ideea este de a menține coerența între diagrame și cod, indiferent de metodă sau instrument. Simon Brown spunea că „diagramele nu sunt utile pentru îmbunătățirea arhitecturii dacă nu sunt conectate la cod”, ceea ce subliniază ideea de coerență semantică.

Preveniți fragmentarea diagramelor

• Având mai multe diagrame ar putea face ca descrierea arhitecturală să fie dificil de înțeles, dar și un efort semnificativ în menținerea lor. Ca efect secundar, ar putea apărea fragmentarea (de exemplu, de exemplu, două sau mai multe diagrame ilustrează același atribut de calitate – performanță, scalabilitate, etc. – dar fiecare dintre ele este incompletă în mod individual). În astfel de cazuri, se recomandă fie să se elimine diagramele care nu reflectă atributele de calitate relevante (legate de cerințele semnificative din punct de vedere arhitectural), fie, și mai bine, să se fuzioneze diagramele (de exemplu, concurența și implementarea).

Măstrați trasabilitatea între diagrame

• Pentru a putea verifica istoricul, făcând comparații între diferite versiuni ale diagramelor, plus revenirea cu ușurință la o versiune anterioară este, de asemenea, important. Folosirea unui instrument de modelare care nu permite acest lucru ar putea fi un impediment. Cele mai recente tendințe din industrie se bazează pe utilizarea unui limbaj simplu și intuitiv de text simplu pentru a genera diagramele din acesta, ceea ce pare să rezolve problema trasabilității. Un alt avantaj al unei astfel de abordări este că asigură implicit o coerență structurală omogenă între diagrame.

Adaugați legende lângă diagramele de arhitectură

• Dacă nu urmați un limbaj standard de descriere arhitecturală (de exemplu, UML, ArchiMate), detaliați fiecare piesă a diagramei în legendă (de exemplu, cutii, forme, margini, linii, culori, acronime etc.).
• Dacă nu este cazul, în legendă adăugați doar limbajul de descriere arhitecturală ca o cheie și nu este nevoie de explicații suplimentare, deoarece fiecare cititor va urmări specificul acelui limbaj pentru a înțelege diagrama.

Limbajul de descriere arhitecturală (de exemplu UML, ArchiMate, etc.) face o diferență?

Există o mulțime de opinii cu privire la care este limbajul de descriere potrivit pentru a fi adoptat în proiect. Unele persoane ar putea susține că UML este rigid și nu este suficient de flexibil pentru a modela proiectarea arhitecturală, un punct de vedere cu care sunt de acord. Cu toate acestea, în unele cazuri, ar putea fi mai mult decât suficient pentru a documenta elementele fundamentale ale unei arhitecturi fără a se baza pe caracteristicile de extensibilitate ale UML, cum ar fi profilurile și stereotipurile. Dacă aruncăm o privire la alte limbaje de descriere, putem observa că ArchiMate este mai puternic și mai potrivit pentru modelarea sistemelor de întreprindere în comparație cu UML; există, de asemenea, BPMN, care este destinat în special proceselor de afaceri etc. Comparațiile ar putea continua, dar nu intenționez să fac o trecere în revistă profundă peste ele, deoarece nu acesta este scopul acestui articol.

Având un limbaj de descriere arhitecturală suficient de cuprinzător și flexibil este un mare pas înainte și acesta ar trebui să fie un criteriu solid în alegerea lui. Dar, din punctul meu de vedere, adevărata cauză rezidă în altă parte și este legată de faptul că documentația arhitecturală nu este creată deloc. Oamenii consideră adesea că crearea acesteia este plictisitoare, inutilă sau lipsită de sens. Numărul de proiecte de software fără documentație sau cu documentație necorespunzătoare este imens. Nu cred că oamenii creează sau se implică în mod intensiv în crearea de diagrame arhitecturale folosind un limbaj de descriere necorespunzător, iar dacă ar trebui să le înlocuiască cu unul mai bun, rezultatele ar fi foarte diferite. Nu, oamenii nu creează nicio documentație arhitecturală (inclusiv diagrame arhitecturale) și, chiar mai rău, cei mai mulți dintre ei nu au nicio idee despre cum să o creeze în mod corespunzător. Acestea sunt lucrurile pe care trebuie să le abordăm în primul rând – să înțelegem de ce este importantă documentația și cum să o creăm în mod corespunzător (prin instruirea inginerilor de software); apoi, selecția instrumentelor adecvate vine în mod natural.

Cum pot fi actualizate diagramele pe măsură ce sistemul este dezvoltat și se materializează modificări ale arhitecturii

Există câteva abordări pentru a menține diagramele actualizate; mai jos voi exprima trei dintre ele. Prima opțiune, și cea mai simplă, ar fi generarea automată a diagramelor pornind de la codul sursă, care reprezintă adevărul de bază. Acest lucru garantează că toate diagramele sunt în concordanță cu codul. Din păcate, cu instrumentele existente, acest lucru nu este încă pe deplin posibil (cel puțin din câte știu eu), deoarece instrumentele actuale nu pot crea niciun tip de diagramă precisă și semnificativă doar pe baza codului sursă, fără o intervenție manuală semnificativă. Len Bass a spus că „mediul de dezvoltare ideal este unul pentru care documentația este disponibilă în mod esențial gratuit prin apăsarea unui buton”, implicit generarea automată a diagramelor, dar nu am ajuns la acest punct.

A doua abordare ar fi să se proiecteze mai întâi diagramele cu ajutorul unui instrument dedicat care să genereze apoi scheletele de cod sursă (de exemplu, componente/pachete cu limite, API-uri) folosite ulterior de dezvoltatori pentru a completa codul. În acest fel, fiecare modificare a arhitecturii trebuie să fie declanșată din diagrama însăși, care ar putea regenera sau actualiza automat scheletul de cod.

Ultimul caz implică actualizarea manuală a diagramelor de fiecare dată când este implementată o nouă caracteristică – care are un impact asupra proiectării arhitecturale. Pentru a fi siguri că toate modificările de cod sunt reflectate în diagrame, se recomandă ca actualizarea diagramelor să facă parte din definiția de făcut în procesul de dezvoltare. Acest scenariu este mai puțin recomandat deoarece ar putea cauza cu ușurință diagrame învechite sau incoerente (de exemplu, dezvoltatorii uită adesea sau nu au chef să actualizeze diagramele) și, din păcate, acest lucru încă se întâmplă în majoritatea proiectelor.

Cu luarea în considerare a instrumentelor existente, recomandarea mea este de a avea un mix; de a îmbina crearea automată și manuală a diagramelor. De exemplu, încercați să generați automat diagrame, care pot fi redate în mod rezonabil de instrumente bazate pe codul sursă fără prea mult zgomot (de exemplu, informații prea aglomerate sau fără sens). În această categorie putem include fie diagrame cu un grad ridicat de volatilitate (de exemplu, mai predispuse la schimbări frecvente de dezvoltare, având de obicei o abstractizare mai mică), fie, dimpotrivă, diagrame statice. Unele astfel de diagrame se pot referi la diagrame de context, diagrame de arhitectură de referință, diagrame de pachete, diagrame de clase, diagrame de entități etc. Cu toate acestea, în unele cazuri, nu este evident, doar pe baza codului sursă, modul în care sistemul îndeplinește anumite atribute de calitate (de exemplu, disponibilitate, scalabilitate, performanță), prin urmare, crearea automată de diagrame nu este o opțiune suficientă. Aceasta trebuie să fie completată de diagrame modelate manual. Câteva exemple de astfel de diagrame includ diagrame de secvență, diagrame de stare, diagrame de concurență, diagrame de implementare, diagrame operaționale etc.

Ce complicații (sau simplificări) apar pentru diagramele arhitecturale atunci când se abordează arhitecturi moderne (de ex.g. microservicii)?

Microserviciile sau orice alt stil arhitectural modern (de exemplu, serverless, event driven) determină doar structura sistemului, modul în care componentele comunică între ele (de exemplu, relațiile dintre ele) și ce principii le guvernează. Personal, nu cred că stilul arhitectural ar trebui să schimbe raționamentul sau conceptele care stau la baza creării diagramelor (și implicit a descrierii arhitecturale) și nici ceea ce acestea ar trebui să captureze. Cu toate acestea, atunci când vorbim despre arhitecturi de sisteme moderne, care au, de obicei, niveluri mai ridicate de complexitate în comparație cu sistemele vechi și clasice (de exemplu, monolit), acestea au cu siguranță un impact asupra descrierii arhitecturale și, implicit, asupra diagramelor, în sensul că există mai multe considerente de care trebuie să se țină seama. Astfel de considerații ar putea fi în ceea ce privește înțelegerea numărului de componente distribuite (de exemplu, microservicii distribuite), tipul fiecărei componente, modul în care componentele comunică între ele (de exemplu, granițe, API-uri, mesaje), ciclul de viață al acestora și cine deține fiecare componentă.

După toate acestea, ar trebui să se ia în considerare în mod implicit vederile care surprind descompunerea, dezvoltarea, implementarea și operabilitatea sistemului. Imaginați-vă un sistem cu un număr impresionant de microservicii, de exemplu; într-un astfel de caz, numărul de diagrame ar putea crește semnificativ, deoarece fiecare microserviciu ar putea ajunge să aibă propriul set de diagrame. Problemele legate de consecvență (de exemplu, modificarea API-ului unui serviciu are impact asupra altor servicii X, prin urmare, toate diagramele afectate trebuie actualizate), de fragmentare (de exemplu, disponibilitatea sau performanța ridicată între serviciile distribuite nu sunt consolidate într-o singură diagramă) sau problemele transversale (de exemplu, cine este responsabil de ilustrarea, într-o manieră consolidată, a unor aspecte precum monitorizarea sau securitatea în toate elementele sistemului) ar putea să nu fie ușor de gestionat. În plus, ar putea exista provocări legate de coexistența și colaborarea echipelor în timpul dezvoltării proiectului și chiar și după aceea, în vederea menținerii acestuia.

Pentru a rezuma, sistemele moderne cu arhitecturi complexe ar putea aduce preocupări suplimentare care ar putea duce la complicații chiar și la nivelul diagramelor.

Despre autor

Ionut Balosin este arhitect software și formator tehnic independent. Participă cu regularitate la conferințe și meetup-uri de dezvoltare software din întreaga lume, susținând prezentări, cursuri de formare și ateliere de lucru. Pentru mai multe detalii, vă rugăm să consultați site-ul său.

.