Πώς να γράψετε ένα mermaid sequence diagram
Ένα sequence diagram δείχνει ποιος μιλάει σε ποιον, με ποια σειρά. Στο mermaid γράφεται περίπου στον ίδιο χρόνο που παίρνει να το περιγράψετε φωναχτά, γι' αυτό είναι ο τύπος διαγράμματος που επιβιώνει περισσότερο σε μια βάση κώδικα. Όλα τα παρακάτω είναι έτοιμα για αντιγραφή-επικόλληση στον editor.
Το ελάχιστο
Δηλώστε τον τύπο του διαγράμματος, μετά γράψτε μία γραμμή ανά μήνυμα. Οι participants δημιουργούνται με την πρώτη αναφορά τους, με τη σειρά που εμφανίζονται.
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order id
API-->>User: 201 CreatedΔηλώστε τους participants ρητά με participant User όταν θέλετε συγκεκριμένη σειρά από αριστερά προς τα δεξιά αντί για τη σειρά πρώτης αναφοράς.
Τύποι βελών
| Σύνταξη | Σημασία |
|---|---|
A->>B: text | Αίτημα — συνεχής γραμμή, γεμάτη αιχμή |
A-->>B: text | Απόκριση — διακεκομμένη γραμμή, γεμάτη αιχμή |
A->B: text | Συνεχής γραμμή, ανοιχτή αιχμή |
A-)B: text | Ασύγχρονο μήνυμα — ανοιχτή αιχμή, χωρίς αναμενόμενη απάντηση |
A-xB: text | Μήνυμα που αποτυγχάνει ή απορρίπτεται |
Η σύμβαση που αξίζει να κρατήσετε: συνεχής γραμμή για την κλήση, διακεκομμένη για την επιστροφή. Έτσι ένας αναγνώστης ξεχωρίζει ένα αίτημα από μια απόκριση χωρίς να διαβάσει ούτε μία ετικέτα.
Participants και ψευδώνυμα
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 OKΧρησιμοποιήστε actor U as Browser αντί για participant για να σχεδιάσετε μια φιγούρα ανθρωπάκι — αξίζει τον κόπο για τον χρήστη στην αριστερή άκρη μιας ροής αυθεντικοποίησης.
Activation bars
Οι activation bars δείχνουν πόσο καιρό είναι απασχολημένος ένας participant. Είτε σημειώστε τις ρητά με activate/deactivate, είτε προσθέστε + και - στα βέλη, που είναι πιο σύντομο και πιο δύσκολο να ξεφύγει από την ισορροπία.
sequenceDiagram
User->>+API: POST /pay
API->>+Bank: charge
Bank-->>-API: authorised
API-->>-User: receiptΒρόχοι, συνθήκες και παράλληλη εργασία
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— επανάληψη.alt <label>…else <label>…end— αμοιβαία αποκλειόμενοι κλάδοι.opt <label>…end— ένας κλάδος που μπορεί απλώς να μη συμβεί.par <label>…and <label>…end— πράγματα που συμβαίνουν ταυτόχρονα.critical/break— μια ενότητα που δεν πρέπει να διακοπεί, και μια πρόωρη έξοδος.
Σημειώσεις
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 daysΤο Note over A,B εκτείνεται πάνω από δύο participants και είναι το σωστό σημείο για έναν περιορισμό που ανήκει στην αλληλεπίδραση και όχι σε μία από τις δύο πλευρές της.
Ένα πλήρες παράδειγμα
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 inΕπεξεργαστείτε αυτό το διάγραμμα
Επικολλήστε το στην καρτέλα κώδικα και αλλάξτε μία γραμμή — η προεπισκόπηση ξανασχεδιάζεται καθώς πληκτρολογείτε.
Συχνές ερωτήσεις
Πώς αριθμώ τα μηνύματα;
Βάλτε autonumber στη γραμμή αμέσως μετά το sequenceDiagram. Κάθε μήνυμα παίρνει τότε έναν διαδοχικό αριθμό, που κάνει το διάγραμμα πολύ πιο εύκολο να συζητηθεί σε σχόλια αναθεώρησης.
Μπορεί ένας participant να στείλει μήνυμα στον εαυτό του;
Ναι — γράψτε το ίδιο όνομα και στις δύο πλευρές: API->>API: retry. Το mermaid σχεδιάζει τον βρόχο πίσω στην ίδια γραμμή ζωής.
Πώς δείχνω ότι ένας participant καταστρέφεται;
Χρησιμοποιήστε destroy <name> πριν το μήνυμα που τον τερματίζει, ή create participant <name> για να εμφανιστεί στη μέση του διαγράμματος αντί στην κορυφή.
Μπορώ να επεξεργαστώ ένα sequence diagram στον οπτικό καμβά;
Ο οπτικός καμβάς επεξεργάζεται flowcharts. Τα sequence diagrams γράφονται στην καρτέλα κώδικα, όπου σχεδιάζονται ζωντανά στην προεπισκόπηση — κάτι που συνήθως είναι έτσι κι αλλιώς πιο γρήγορο, αφού ένα sequence diagram είναι ουσιαστικά μια λίστα γραμμών.