Cum scrii o diagramă de secvență mermaid
O diagramă de secvență arată cine vorbește cu cine, în ce ordine. În mermaid durează cam cât să o descrii cu voce tare, motiv pentru care este tipul de diagramă care supraviețuiește cel mai mult într-o bază de cod. Tot ce urmează e gata de copiat-lipit în editor.
Minimul necesar
Declari tipul diagramei, apoi scrii câte o linie pentru fiecare mesaj. Participanții sunt creați la prima mențiune, în ordinea în care apar.
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order id
API-->>User: 201 CreatedDeclari participanții explicit cu participant User când vrei o ordine de la stânga la dreapta anume, nu ordinea primei mențiuni.
Tipuri de săgeți
| Sintaxă | Sens |
|---|---|
A->>B: text | Cerere — linie continuă, vârf de săgeată plin |
A-->>B: text | Răspuns — linie întreruptă, vârf de săgeată plin |
A->B: text | Linie continuă, vârf de săgeată gol |
A-)B: text | Mesaj asincron — vârf de săgeată gol, fără răspuns așteptat |
A-xB: text | Mesaj care eșuează sau este pierdut |
Convenția care merită păstrată: continuu pentru apel, întrerupt pentru răspuns. Un cititor poate deosebi atunci o cerere de un răspuns fără să citească nicio etichetă.
Participanți și alias-uri
sequenceDiagram
participant U as Browser
participant A as API gateway
participant S as Order service
U->>A: GET /orders
A->>S: list(userId)
S-->>A: orders
A-->>U: 200 OKFolosește actor U as Browser în loc de participant pentru a desena un om stilizat — util pentru persoana de la marginea stângă a unui flux de autentificare.
Bare de activare
Barele de activare arată cât timp este ocupat un participant. Le marchezi explicit cu activate/deactivate, sau adaugi + și - la săgeți, ceea ce e mai scurt și mai greu de dezechilibrat.
sequenceDiagram
User->>+API: POST /pay
API->>+Bank: charge
Bank-->>-API: authorised
API-->>-User: receiptBucle, condiționale și lucru în paralel
sequenceDiagram
User->>API: POST /import
loop every row
API->>DB: upsert row
end
alt all rows valid
API-->>User: 200 OK
else some failed
API-->>User: 422 with errors
end
par notify
API->>Email: send summary
and audit
API->>Log: write entry
endloop <label>…end— repetiție.alt <label>…else <label>…end— ramuri care se exclud reciproc.opt <label>…end— o ramură care poate pur și simplu să nu se întâmple.par <label>…and <label>…end— lucruri care se întâmplă simultan.critical/break— o secțiune care nu trebuie întreruptă, și o ieșire timpurie.
Note
sequenceDiagram
User->>API: POST /login
Note right of API: Rate limited<br>5 per minute
API-->>User: token
Note over User,API: Token is valid for 30 daysNote over A,B acoperă doi participanți și este locul potrivit pentru o constrângere care aparține interacțiunii, nu uneia dintre părți.
Un exemplu complet
sequenceDiagram
actor U as User
participant A as App
participant P as Provider
U->>+A: Click "Sign in"
A-->>-U: Redirect to provider
U->>+P: Authorise
P-->>-U: Redirect back with code
U->>+A: GET /callback?code=…
A->>+P: Exchange code for token
P-->>-A: access token
Note right of A: Session cookie set here
A-->>-U: Signed inEditează această diagramă
Lipește-o în fila de cod și schimbă o linie — previzualizarea se redesenează pe măsură ce scrii.
Întrebări frecvente
Cum numerotez mesajele?
Pune autonumber pe linia imediat de după sequenceDiagram. Fiecare mesaj primește atunci un număr secvențial, ceea ce face o diagramă mult mai ușor de discutat în comentariile de review.
Poate un participant să își trimită un mesaj sieși?
Da — scrii același nume pe ambele părți: API->>API: retry. Mermaid desenează bucla înapoi pe aceeași linie de viață.
Cum arăt că un participant este distrus?
Folosește destroy <name> înainte de mesajul care îl termină, sau create participant <name> pentru ca acesta să apară la mijlocul diagramei, nu la început.
Pot edita o diagramă de secvență pe pânza vizuală?
Pânza vizuală editează flowchart-uri. Diagramele de secvență se scriu în fila de cod, unde se randează live în previzualizare — ceea ce e de obicei mai rapid oricum, pentru că o diagramă de secvență este în esență o listă de linii.