Editor di diagrammi di flusso Mermaid
Un diagramma di flusso mostra come procede un processo: quali passi esistono, dove si dirama e dove i rami si ricongiungono. Va bene quando il tema è l'ordine delle decisioni — un rilascio, il percorso di una richiesta, un flusso di approvazione. Se il tema è chi parla con chi e quando, il diagramma di sequenza è migliore.
Una pipeline di rilascio con due percorsi di errore
Quasi tutti i diagrammi di flusso di questo sito partono da questa forma: un percorso lineare che funziona e i rombi decisionali che se ne staccano. Nota le virgolette nel penultimo nodo. Mettere tra virgolette le parentesi dentro un'etichetta è obbligatorio, e dimenticarlo è l'errore più comune di tutti.
flowchart TD
Push[Push su main] --> Lint[Analisi statica e tipi]
Lint --> Test{I test passano}
Test -->|No| Avviso[Avvisa chi ha fatto il commit]
Test -->|Sì| Build[Costruisci l'immagine]
Build --> Scan{Scansione sicurezza pulita}
Scan -->|No| Blocca["Blocca il rilascio (revisione manuale)"]
Scan -->|Sì| Deploy[Rilascia in produzione]
Deploy --> Fumo[Test di fumo]
Fumo --> Fine[Rilascio completato]Esempi commentati
1. Il diagramma di flusso più piccolo
Due nodi e una freccia. `TD` va dall'alto in basso, `LR` da sinistra a destra; un diagramma più largo che alto si legge quasi sempre meglio con `LR`.
flowchart TD
Ricezione[Ricevi la richiesta] --> Risposta[Invia la risposta]2. Una diramazione con etichette
Le graffe disegnano un rombo. Il testo fra le barre verticali etichetta l'arco, non il nodo. Questa distinzione tornerà più sotto, fra gli errori.
flowchart TD
Inizio[Ricevi la richiesta] --> Auth{Token valido}
Auth -->|Sì| Elabora[Esegui il gestore]
Auth -->|No| Rifiuta[Restituisci 401]
Elabora --> Ok[Restituisci 200]3. Far dire qualcosa alla forma
Le forme sono il modo più economico di aggiungere informazione a un diagramma di flusso. Le estremità arrotondate indicano inizio e fine, il rombo una decisione, il cilindro un archivio dati.
flowchart LR
Avvia([Avvia il job]) --> Leggi[(Leggi da Postgres)]
Leggi --> Nuove{Ci sono righe nuove}
Nuove -->|No| Termina([Termina senza modifiche])
Nuove -->|Sì| Trasforma[/Trasforma i dati/]
Trasforma --> Scrivi[(Scrivi su S3)]
Scrivi --> Termina4. Sottografi per raggruppare per responsabile
Un sottografo racchiude nodi correlati in una cornice. Serve soprattutto a raggruppare per responsabile, non per fase: quando si vede quale squadra o quale servizio si occupa di cosa, i passaggi di consegne saltano fuori da soli.
flowchart TD
subgraph client [Browser]
UI[Invia il modulo]
end
subgraph api [Servizio ordini]
Valida[Valida l'input]
Salva[Salva l'ordine]
end
subgraph async [Lavori in background]
Mail[Invia la conferma]
Fattura[Genera la fattura]
end
UI --> Valida
Valida --> Salva
Salva --> Mail
Salva --> Fattura5. Un ciclo di tentativi con un limite
I diagrammi di flusso gestiscono bene i cicli. Il ciclo di tentativi è il caso in cui servono davvero, perché dal disegno si vede a colpo d'occhio se il ciclo ha un'uscita vera.
flowchart TD
Invia[Invia il webhook] --> Esito{Ricevuto 2xx}
Esito -->|Sì| Riuscito[Segna come consegnato]
Esito -->|No| Tentativi{Meno di 5 tentativi}
Tentativi -->|Sì| Attendi[Attesa esponenziale]
Attendi --> Invia
Tentativi -->|No| Coda[Metti in coda di scarto]Riepilogo della sintassi del diagramma di flusso
Tutto quello che segue vale solo per il diagramma di flusso. Le frecce soprattutto: non si spostano in altri tipi. Il `->>` del diagramma di sequenza qui è un errore di sintassi.
| Sintassi | Significato |
|---|---|
| flowchart TD | Dall'alto in basso. `TB` è la stessa cosa. La direzione naturale per leggere un processo. |
| flowchart LR | Da sinistra a destra. Esiste anche `RL`. Per flussi larghi e poco profondi. |
| A[Testo] | Rettangolo — un passo qualunque. |
| A(Testo) | Rettangolo con angoli arrotondati. |
| A([Testo]) | Forma a stadio — per convenzione inizio o fine. |
| A[(Testo)] | Cilindro — archivio dati. |
| A{Testo} | Rombo — decisione. |
| A[/Testo/] | Parallelogramma — input o output. |
| A --> B | Freccia. |
| A --- B | Linea senza punta. |
| A -.-> B | Freccia punteggiata — per convenzione asincrono o facoltativo. |
| A ==> B | Freccia spessa — per convenzione il percorso principale. |
| A -->|testo| B | Arco etichettato. Con parentesi servono le virgolette. |
| A["Testo (con parentesi)"] | Etichetta fra virgolette — necessaria per parentesi, virgolette e ogni carattere letto come sintassi di forma. |
| subgraph nome [Titolo] ... end | Raggruppa i nodi in una cornice. Si chiude con `end`. |
| %% commento | Riga di commento. Non viene disegnata. |
I sei errori che rompono davvero un diagramma di flusso
Riprodotti tutti sul motore che usa questo sito (Mermaid 11.12.2). Incolla la versione sbagliata nell'editor e ottieni esattamente l'errore descritto; quella corretta viene disegnata. Il modo più rapido di leggere un errore di Mermaid è guardarne la fine: dopo la parola `got` c'è il token su cui il parser si è fermato.
Cosa vedi
Parse error che finisce con: got 'PS'
Perché
Dentro un'etichetta fra parentesi quadre c'è una parentesi tonda aperta. Le tonde sono sintassi di forma — `A(testo)` è un nodo arrotondato — quindi una tonda nuda dentro le quadre viene letta come l'inizio di una forma nuova.
Soluzione
Metti l'intera etichetta fra virgolette doppie. Fra virgolette tutto conta come testo.
flowchart TD
A[Riprova (al massimo 5 volte)] --> B[Fine]flowchart TD
A["Riprova (al massimo 5 volte)"] --> B[Fine]Cosa vedi
Parse error sulla riga in cui hai dato un nome al nodo
Perché
Nell'identificatore del nodo c'è uno spazio. In italiano è difficile evitarlo, perché i nomi naturali sono formati da più parole: «servizio di autenticazione», «base dati utenti». L'identificatore è il token che precede la freccia, e lo spazio lo tronca lasciando una parola che non ha dove stare.
Soluzione
Dai al nodo un identificatore di una sola parola e metti il testo leggibile nell'etichetta. Accenti e apostrofo funzionano senza problemi in un identificatore — verificato: `L'ordine`, `Città` e `Verificò` vengono disegnati. Rompe solo lo spazio.
flowchart TD
servizio di autenticazione --> base dati utentiflowchart TD
auth[Servizio di autenticazione] --> db[(Base dati utenti)]Cosa vedi
Parse error che finisce con: got 'end'
Perché
Hai usato la parola `end` come identificatore di nodo. In minuscolo `end` chiude un sottografo, quindi il parser vede la fine di un blocco dove si aspettava un nodo. Capita più spesso di quanto sembri: seguendo esempi in inglese, l'ultimo nodo finisce per chiamarsi `end` anche se il resto del diagramma è in italiano.
Soluzione
Scrivilo con la maiuscola oppure dai al nodo un altro identificatore e sposta la parola nell'etichetta. `Fine` non crea alcun problema.
flowchart TD
Inizio[Inizio] --> endflowchart TD
Inizio[Inizio] --> Fine[Completato]Cosa vedi
Parse error nell'etichetta dell'arco fra le barre verticali
Perché
Dentro l'etichetta dell'arco ci sono delle parentesi. Il testo fra `|…|` ha lo stesso vincolo dell'etichetta di un nodo: anche lì le parentesi sono sintassi, non testo.
Soluzione
Metti fra virgolette anche l'etichetta dell'arco.
flowchart TD
A -->|sì (sempre)| Bflowchart TD
A -->|"sì (sempre)"| BCosa vedi
Parse error che finisce con: got 'STR'
Perché
Dentro l'etichetta di un nodo c'è una virgoletta doppia dritta. Il parser la prende per l'inizio di una stringa e poi incontra la quadra dell'etichetta dove si aspettava la virgoletta di chiusura.
Soluzione
Racchiudi l'intera etichetta fra virgolette dritte e usa dentro le virgolette caporali, oppure scrivi il carattere come entità HTML #quot;.
flowchart TD
A[Ha detto "va bene"] --> B[Fine]flowchart TD
A["Ha detto «va bene»"] --> B[Fine]Cosa vedi
Lexical error on line 1. Unrecognized text.
Perché
La direzione non è valida. Il diagramma di flusso accetta solo TB, TD, BT, LR e RL; qualunque altra cosa cade nell'analisi lessicale prima che venga letto anche un solo nodo. Per questo l'errore indica la riga 1 e non il punto del refuso.
Soluzione
Usa una delle cinque. TD e LR coprono quasi tutto.
flowchart ALTOBASSO
A --> Bflowchart TD
A --> BNote sul disegno
Niente di tutto questo è copiato dalla documentazione: è tutto misurato su Mermaid 11.12.2, la versione che usa questo sito. Sono i comportamenti che contano quando il diagramma smette di essere un giocattolo.
Accenti e apostrofo funzionano anche negli identificatori
Vale la pena dirlo, perché in italiano l'apostrofo è ovunque e istintivamente si sospetta che rompa qualcosa. Verificato: `L'ordine --> Spedizione` viene disegnato senza obiezioni e l'identificatore risultante è proprio `L'ordine`. Lo stesso per le vocali accentate: `Città`, `Attività`, `Autenticità` e `Verificò` funzionano come identificatori di nodo, come nomi di stato e come nomi di classe. Non serve spogliare il modello degli accenti per farlo disegnare. L'unico carattere che tronca davvero un identificatore è lo spazio.
Le etichette vanno a capo solo sugli spazi
Misurato: un'etichetta di nodo si allarga fino al limite di 276 pixel di viewBox, poi va a capo e cresce verso l'alto di circa 24 pixel per riga. Il dettaglio che sorprende è che l'interruzione avviene solo sugli spazi: una singola parola lunga non va mai a capo e sfonda il limite deformando tutto il diagramma. In italiano capita meno che in tedesco o in olandese, perché componiamo con le preposizioni invece che per agglutinazione, ma parole come «sovrapposizione» o «internazionalizzazione» ci vanno vicino.
L'altezza cresce di circa 105 pixel per nodo, la larghezza quasi si ferma
In un diagramma dall'alto in basso tre nodi danno un viewBox di circa 126×278. Con quaranta nodi diventa 135×4126: la larghezza è cresciuta di 9 pixel, l'altezza si è moltiplicata per quindici. Un diagramma lungo è una striscia sottile che non sta in nessuno schermo. Il pulsante di centratura nell'anteprima serve a questo. Quando diventa spropositato, passare a `flowchart LR` spesso dimezza quasi il rapporto fra i lati.
L'esportazione PNG era rotta perché le etichette sono HTML
Le etichette del diagramma di flusso sono disegnate come vero HTML dentro un `<foreignObject>` nell'SVG. È per questo che `<br>` e un po' di Markdown funzionano nelle etichette. Per lo stesso motivo il browser si rifiuta di dipingere questo SVG su un canvas: l'esportazione PNG di questo sito ha restituito in silenzio un file SVG per parecchio tempo. Adesso, prima di esportare, il diagramma viene ridisegnato con etichette di testo SVG semplice e il PNG esce corretto. Il prezzo è che la composizione tipografica del PNG esportato differisce di pochissimo da quella a schermo.
Il tema cambia i colori, mai la geometria
Lo stesso diagramma disegnato in tema chiaro e in tema scuro produce un viewBox identico. Cambiare tema non ricompone nulla e non fa uscire un'etichetta dal suo riquadro. Quello che sembra storto in tema scuro è storto esattamente allo stesso modo in tema chiaro.
Quando conviene un altro diagramma
Se il punto è chi manda cosa a chi e l'ordine temporale pesa più delle diramazioni, il diagramma di sequenza si legge meglio e continua a leggersi bene mentre cresce. Un diagramma di flusso con sei partecipanti scritti come nomi di nodo è un diagramma di sequenza che non lo ha ancora ammesso.
Se non stai descrivendo una procedura ma gli stati in cui una cosa può trovarsi, usa il diagramma di stati. Distinguerli è facile: se le etichette dei nodi sono stati come «ordine in attesa» o «ordine spedito», è una macchina a stati; se sono azioni come «valida l'input» o «invia la mail», è un diagramma di flusso.
Superati i quaranta nodi, a essere onesti, nessun diagramma salva la situazione. O lo dividi in più diagrammi che condividono un ingresso comune, o accetti che quello che stai cercando di raccontare è troppo complesso per stare in una sola immagine. Anche questa, di per sé, è un'informazione utile.
Altri tipi di diagramma
Scritto da Dominik Malsch · Ultimo aggiornamento: