Sequence dijagrami kao kod

Za projekat dokumentacija nije „formalnost za kasnije“, već radni alat. Potrebna je da se brže usaglašavaju rešenja između timova, lakše uvedu novi učesnici u kontekst i primetno skrati vreme analize kada nešto pođe naopako u produkciji.

U svetu razvoja softvera, naročito u višekomandnim projektima, efikasna komunikacija između timova igra ključnu ulogu u uspehu projekta. Jedan od alata koji može značajno da olakša ovaj proces jesu sequence dijagrami.

Na ruskoj Vikipediji nazivaju se dijagrami sekvence.

Zašto su sequence dijagrami uopšte potrebni?

Sequence dijagrami su grafički prikaz interakcije različitih komponenti ili učesnika sistema kroz vreme. Pomažu programerima da vizualizuju redosled poziva metoda ili funkcija tokom izvršavanja određene funkcionalnosti. To ne samo da olakšava razumevanje rada sistema, već pomaže i da se uoče potencijalni problemi ili neoptimalni tokovi.

Zašto je praktičnije pisati ih kao kod?

U početku sam takve dijagrame crtao u draw.io. To je generalno bilo prilično zamorno.

Preuzmite fajl dijagrama iznad: sso-diagram.drawio.

Zatim sam otkrio PlantUML. Napisati prvi dijagram pomoću teksta bilo je takođe naporno, baš kao i crtanje u draw.io. Ali kada je došlo vreme za izmene i izradu sličnih dijagrama, tada su se u potpunosti pokazale prednosti dijagrama u formi koda, a ne slika.

Jasnoća i preciznost

Korišćenje PlantUML-a za pisanje sequence dijagrama u formi koda obezbeđuje visoku jasnoću i preciznost opisa interakcije između komponenti. PlantUML kod je formalizovan i strog, što smanjuje dvosmislenosti i pogrešna tumačenja.

Integracija sa dokumentacijom

Sequence dijagrami napravljeni u PlantUML-u lako se ugrađuju u projektnu dokumentaciju, na primer u Confluence. To omogućava jednostavan pristup vizuelnom prikazu arhitekture i interakcije komponenti za sve učesnike projekta.

Verzionisanje izmena

PlantUML omogućava praćenje izmena u dijagramima i kontrolu verzionisanja. To je korisno pri radu u Confluence-u jer omogućava čuvanje istorije i brzo vraćanje prethodnih verzija kada je potrebno.

Lakoća izmena i izrade narednih dijagrama

Pošto su sequence dijagrami u PlantUML-u predstavljeni kao kod, izmene su jednostavne i brze. Pored toga, na osnovu postojećeg koda lako je praviti naredne dijagrame, što štedi vreme i povećava efikasnost tima.

Kao minus kodiranja dijagrama izdvojio bih uglavnom manju fleksibilnost stilova prikaza.

PlantUML

Dijagram možete početi da kodirate/crtate direktno u pregledaču:

https://www.plantuml.com/plantuml/uml/SyfFKj...

Ako sadržaj dijagrama sadrži poverljive podatke, PlantUML se može pokrenuti lokalno kroz Docker, pa će isti interfejs biti dostupan lokalno i bez interneta.

https://hub.docker.com/r/plantuml/plantuml-server

Numeracija zahteva

Dijagrami su potrebni da bi se, s jedne strane, isprojektovalo i usaglasilo tehničko rešenje između timova, a s druge strane da se u radu sistema, u slučaju problema, brže pronađe uzrok i problem usmeri pravom timu.

U oba scenarija mnogo pomaže numeracija zahteva na dijagramu. Ako su zahtevi numerisani, u komunikaciji se često koristi format: „zahtev 11 šalje te i te podatke servisu vašeg tima, a u odgovoru 12 stižu neočekivani podaci“. To pomaže da se izbegnu komplikovane i duge formulacije.

Primer dijagrama za Single Sign-On

@startuml

<style>
group {
    LineThickness 1
    LineColor #4d4d4d
    LineStyle 1
  }

  groupHeader {
    LineThickness 1
    LineStyle 1
  }
</style>

skinparam sequence {
ArrowColor #000000
ActorBorderColor #000000
LifeLineBorderColor #000000
LifeLineBackgroundColor #FFFFFF
ParticipantBorderColor #000000
ParticipantBackgroundColor #FFFFFF
ParticipantFontColor #000000
BoxBorderColor #000000
BoxBackgroundColor #FFFFFF
BoxFontColor #000000 }

participant Customer order 10
participant Browser order 20 #fff2cc
participant App1 order 30 #dcebf7
participant App2 order 40 #e2efda
participant App3 order 50 #d9d2e9
participant App4 order 60 #F5F5F5
participant App5 order 70  #FCE4D6  

group App1 Group Authentication
 
Customer -> Browser : A1. Go to App1
activate Browser
Browser -> App1 : A2. GET index
activate App1
App1 -> Browser : A3. index
deactivate App1

Customer -> Browser : A4. Click Login
Browser -> App2 : A5. GET authorization.oauth2, CustID: App1
activate App2

App2 -> Browser : A6. Login form

Customer -> Browser : A7. Login information

Browser -> App2 : A8. POST Login information
App2 --> Browser : A9. 302 Redirect + auth code

Browser -> App1 : A10. GET redirect uri_endpoint + auth hash
activate App1

App1 -> App2 : A11. Request access token by auth hash

App2 -> App1 : A12. Access Token + User_Info

App1 -> Browser : A13. Logged in content
deactivate App1

Browser -> Customer : A14. Logged in content

end

group  App1 User Authentication
 
Customer -> Browser : B1. Click User Login
Browser -> App1 : B2. GET
activate App1

App1 -> Browser : B3. Login form

Customer -> Browser : B4. User Login information

Browser -> App1 : B5. POST User Login information
App1 -> Browser : B6. User Logged in content + Cookie with User Id
deactivate App1

Browser -> Customer : B7. User Logged in content

end

Customer -> Browser : C1. Go to App

Browser -> App3 : C2. GET initial URI (with ID, pass and language parameters)
activate App3
App3 --> Browser : C3. 302 Redirect to App2, set state parameter to 'initial URI'

Browser -> App2 : C4. GET authorization.oauth2, CustID: App1

App2 --> Browser : C5. 302 Redirect + auth hash

Browser -> App3 : C6. GET redirect uri_endpoint + auth hash

App3 -> App2 : C7. Request tokens by auth hash

App2 -> App3 : C8. Access, Refresh, Id Tokens

App3 --> Browser : C9. 302 Redirect to certain Data Center depending on User from Id Token, GET initial URI
deactivate App3

Browser -> App4 : C10. GET initial URI
activate App4

App4 --> Browser : C11. 302 Redirect to App2, set state parameter to 'initial URI'
Browser -> App2 : C12. GET authorization.oauth2, ClientID: App1

App2 --> Browser : C13. 302 Redirect + auth hash

Browser -> App4 : C14. GET redirect uri_endpoint + auth hash


App4 -> App2 : C15. Request tokens by auth hash

App2 -> App4 : C16. Access, Refresh, Id Tokens
deactivate App2

App4 -> App5 : C17. Socket: Id Token + User
activate App5
rnote over App5
App5 gets Id token,
extracts user information,
creates internal context
for this user
+ Login to User, if defined
endrnote
App5 -> App4 : 18. Success status
deactivate App5

App4 -> Browser : C19. App4 Logged in content, depending on parameters from App2 'state' about 'initial URI'
deactivate App4
Browser -> Customer : C20. App4 Logged in content


deactivate Browser

@enduml

Link ka punoj verziji ovog dijagrama na PlantUML serveru: http://www.plantuml.com/plantuml/uml/fLLjRz....