Come scrivere un diagramma di sequenza mermaid
Un diagramma di sequenza mostra chi parla con chi, in quale ordine. In mermaid richiede circa lo stesso tempo che descriverlo a voce, ed è per questo che è il tipo di diagramma che sopravvive più a lungo in una codebase. Tutto quanto segue è pronto da copiare e incollare nell'editor.
Il minimo indispensabile
Dichiara il tipo di diagramma, poi scrivi una riga per ogni messaggio. I partecipanti vengono creati alla prima menzione, nell'ordine in cui appaiono.
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order id
API-->>User: 201 CreatedDichiara i partecipanti esplicitamente con participant User quando vuoi un ordine specifico da sinistra a destra invece dell'ordine di prima menzione.
Tipi di freccia
| Sintassi | Significato |
|---|---|
A->>B: text | Richiesta — linea continua, punta piena |
A-->>B: text | Risposta — linea tratteggiata, punta piena |
A->B: text | Linea continua, punta aperta |
A-)B: text | Messaggio asincrono — punta aperta, nessuna risposta attesa |
A-xB: text | Messaggio che fallisce o viene perso |
La convenzione da mantenere: linea continua per la chiamata, tratteggiata per la risposta. Un lettore può così distinguere una richiesta da una risposta senza leggere una sola etichetta.
Partecipanti e alias
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 OKUsa actor U as Browser invece di participant per disegnare un omino stilizzato — utile per la persona al margine sinistro di un flusso di autenticazione.
Barre di attivazione
Le barre di attivazione mostrano per quanto tempo un partecipante è occupato. Puoi indicarle esplicitamente con activate/deactivate, oppure aggiungere + e - alle frecce, più breve e più difficile da sbilanciare.
sequenceDiagram
User->>+API: POST /pay
API->>+Bank: charge
Bank-->>-API: authorised
API-->>-User: receiptLoop, condizioni e lavoro parallelo
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— ripetizione.alt <label>…else <label>…end— rami che si escludono a vicenda.opt <label>…end— un ramo che potrebbe semplicemente non verificarsi.par <label>…and <label>…end— cose che accadono nello stesso momento.critical/break— una sezione che non deve essere interrotta, e un'uscita anticipata.
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 copre due partecipanti ed è il posto giusto per un vincolo che appartiene all'interazione piuttosto che a uno dei due lati.
Un esempio completo
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 inModifica questo diagramma
Incollalo nella scheda codice e cambia una riga — l'anteprima si ridisegna mentre scrivi.
Domande frequenti
Come numero i messaggi?
Metti autonumber sulla riga subito dopo sequenceDiagram. Ogni messaggio riceve così un numero progressivo, il che rende un diagramma molto più facile da commentare in una review.
Un partecipante può inviare un messaggio a se stesso?
Sì — scrivi lo stesso nome su entrambi i lati: API->>API: retry. Mermaid disegna il ciclo che torna sulla stessa lifeline.
Come mostro che un partecipante viene distrutto?
Usa destroy <name> prima del messaggio che lo conclude, oppure create participant <name> per farlo apparire a metà diagramma invece che in cima.
Posso modificare un diagramma di sequenza sulla tela visiva?
La tela visiva modifica i flowchart. I diagrammi di sequenza si scrivono nella scheda codice, dove si renderizzano dal vivo nell'anteprima — di solito è comunque più veloce, dato che un diagramma di sequenza è essenzialmente un elenco di righe.