Diagramma di sequenza
Mostra come dialogano sistemi e persone
Che cos’è un Diagramma di sequenza?
Un diagramma di sequenza mostra i messaggi scambiati tra i partecipanti nel tempo: chiamate API, flussi di autenticazione, comunicazione tra microservizi. È lo standard per documentare le interazioni nell’architettura software.
I diagrammi di sequenza si guadagnano il loro posto nelle revisioni di progettazione e nei rapporti post-incidente, dove la domanda è sempre la stessa: chi ha chiamato chi, in che ordine, e che cosa è tornato indietro. Niente mostra più in fretta un errore di ordinamento o un timeout mancante. Quello che non sanno mostrare è lo stato: una lifeline dice che un partecipante è occupato, mai in quale stato interno si trova o che cosa ricorda tra due esecuzioni.
Esempio dal vivo
sequenceDiagram
autonumber
participant U as User
participant A as API
participant D as Database
U->>A: POST /login
A->>D: SELECT user
D-->>A: user row
A-->>U: 200 + JWT token
U->>A: GET /profile (Bearer)
A-->>U: 200 profileQuando usarlo
Errori frequenti
Attivazioni lasciate aperte
Ogni + richiede un - corrispondente, e ogni activate un deactivate. Una coppia sbilanciata disegna una barra che scende fino in fondo al diagramma oppure fallisce con «Trying to inactivate an inactive participant».
L’ordine dei partecipanti è quello di dichiarazione
Mermaid dispone i partecipanti da sinistra a destra nell’ordine in cui li incontra, quindi uno citato solo in un ramo di errore finisce all’estrema destra. Dichiara ogni participant in cima, nell’ordine in cui vuoi vederli disegnati.
Una freccia semplice non è una chiamata
A->B disegna una linea continua senza punta, che si legge come se non fosse successo nulla. Le chiamate sincrone sono ->>, le risposte -->>, i messaggi fire-and-forget -). I trattini definiscono lo stile della linea; il significato sta nella punta.
Sintassi di base
sequenceDiagram
participant A as Alice
participant B as Bob
A->>B: Sync request
B-->>A: Async responsesequenceDiagram autonumberautonumber antepone un numero a ogni messaggio, così in revisione si può parlare del «passaggio 4» in un commento invece di descrivere a parole quale freccia si intende.
U->>+API: POST /orders API-->>-U: 201 CreatedUn + su una freccia apre una barra di attivazione sul destinatario e un - la chiude, mostrando esattamente per quanto ogni partecipante resta occupato a gestire la chiamata.
note over API,DB: single transactionLe note portano il dettaglio che le frecce non possono contenere: confini transazionali, politica di retry, timeout. Usa note left of o note right of per agganciarne una a un solo partecipante.
box Payment domain participant PSP endbox disegna una cornice etichettata attorno ai partecipanti che appartengono allo stesso sistema o allo stesso team. Anteponi all’etichetta il nome di un colore per colorare la cornice.
Domande su questo diagramma
Cosa significano i tipi di freccia in un diagramma di sequenza Mermaid?
Le frecce piene (->>) sono chiamate sincrone, le frecce tratteggiate (-->>) sono risposte o messaggi asincroni. Le attivazioni mostrano quando un partecipante è impegnato nell’elaborazione.
Posso rappresentare cicli e condizioni?
Sì — Mermaid supporta i blocchi loop, alt (if/else), opt (opzionale) e par (parallelo) per esprimere la logica di protocolli reali.
Posso mettere un diagramma di sequenza nella descrizione di una pull request su GitHub?
Sì: incolla il codice in un blocco di codice con il tag mermaid e GitHub lo renderizza direttamente in pull request, issue e commenti. A differenza di uno screenshot, il diagramma si confronta come testo alla modifica successiva.
Un diagramma di sequenza Mermaid può mostrare il tempo trascorso o la latenza?
No. L’asse verticale rappresenta solo l’ordine: non esiste una scala temporale, quindi due frecce distanti un millisecondo sono identiche a due distanti un’ora. Metti il numero in una nota, o usa un diagramma di Gantt quando conta la durata.
Come mostro un partecipante che esiste solo per una parte del flusso?
Dichiaralo dove compare con create participant Worker e chiudilo con destroy Worker. La lifeline parte allora dal messaggio che lo crea e finisce con una croce: è così che si disegna un job, una sessione o un processo temporaneo.
Come evidenzio un gruppo di messaggi?
Racchiudili in rect rgb(240,240,255) … end per colorare lo sfondo, utile per marcare un blocco di retry o una transazione. I blocchi rect si annidano, quindi un retry dentro una transazione resta leggibile. I blocchi loop, alt e opt disegnano una propria cornice etichettata.
Diagramma di sequenza o un altro tipo di diagramma?
Diagramma di sequenza o diagramma di flusso?
Conta i sistemi. Un processo che gira dentro un solo componente è un diagramma di flusso; due o più partecipanti che si scambiano messaggi sono un diagramma di sequenza. Se ti ritrovi a scrivere «il servizio B riceve…» dentro un riquadro, cambia: le lifeline fanno quel lavoro al posto tuo.
Diagramma di sequenza o diagramma degli stati?
Entrambi descrivono un comportamento nel tempo. Il diagramma di sequenza segue una singola esecuzione attraverso il sistema e mostra il traffico tra i partecipanti; il diagramma degli stati copre tutte le esecuzioni di un partecipante e mostra ciò che ricorda. Con il primo si fa debug, con il secondo si specifica.
Crea ora il tuo Diagramma di sequenza
Descrivilo in linguaggio naturale — l’IA scrive il codice Mermaid per te.
Apri Mermaid Studio