Jak napisać diagram sekwencji w mermaid
Diagram sekwencji pokazuje, kto z kim rozmawia i w jakiej kolejności. W mermaid napisanie go zajmuje mniej więcej tyle samo czasu, ile opisanie go na głos, dlatego to typ diagramu, który przetrwa w repozytorium kodu najdłużej. Wszystko poniżej jest gotowe do skopiowania do edytora.
Minimum
Zadeklaruj typ diagramu, a potem napisz jedną linię na wiadomość. Uczestnicy są tworzeni przy pierwszej wzmiance, w kolejności, w jakiej się pojawiają.
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order id
API-->>User: 201 CreatedZadeklaruj uczestników jawnie za pomocą participant User, gdy chcesz konkretnej kolejności od lewej do prawej, zamiast kolejności pierwszej wzmianki.
Typy strzałek
| Składnia | Znaczenie |
|---|---|
A->>B: text | Żądanie — linia ciągła, wypełniony grot |
A-->>B: text | Odpowiedź — linia przerywana, wypełniony grot |
A->B: text | Linia ciągła, otwarty grot |
A-)B: text | Wiadomość asynchroniczna — otwarty grot, bez oczekiwanej odpowiedzi |
A-xB: text | Wiadomość, która kończy się niepowodzeniem lub zostaje odrzucona |
Warto trzymać się konwencji: linia ciągła dla wywołania, przerywana dla odpowiedzi. Czytelnik rozpozna wtedy żądanie od odpowiedzi bez czytania choćby jednej etykiety.
Uczestnicy i aliasy
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 OKUżyj actor U as Browser zamiast participant, aby narysować figurkę — warto przy człowieku po lewej stronie przepływu uwierzytelniania.
Paski aktywacji
Paski aktywacji pokazują, jak długo dany uczestnik jest zajęty. Oznacz je jawnie za pomocą activate/deactivate albo dodaj + i - do strzałek, co jest krótsze i trudniej wtedy stracić równowagę.
sequenceDiagram
User->>+API: POST /pay
API->>+Bank: charge
Bank-->>-API: authorised
API-->>-User: receiptPętle, warunki i praca równoległa
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— powtórzenie.alt <label>…else <label>…end— wzajemnie wykluczające się gałęzie.opt <label>…end— gałąź, która może po prostu nie wystąpić.par <label>…and <label>…end— rzeczy dziejące się w tym samym czasie.critical/break— sekcja, której nie można przerwać, oraz wcześniejsze wyjście.
Notatki
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 obejmuje dwóch uczestników i to właściwe miejsce na ograniczenie, które dotyczy samej interakcji, a nie żadnej ze stron.
Pełny przykład
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 inEdytuj ten diagram
Wklej go do zakładki kodu i zmień jedną linię — podgląd przerysuje się w locie.
Najczęściej zadawane pytania
Jak ponumerować wiadomości?
Umieść autonumber w linii zaraz po sequenceDiagram. Każda wiadomość dostaje wtedy kolejny numer, co znacznie ułatwia rozmowę o diagramie w komentarzach do code review.
Czy uczestnik może wysłać wiadomość do samego siebie?
Tak — wpisz tę samą nazwę po obu stronach: API->>API: retry. Mermaid rysuje wtedy pętlę z powrotem do tej samej linii życia.
Jak pokazać, że uczestnik zostaje zniszczony?
Użyj destroy <name> przed wiadomością, która go kończy, albo create participant <name>, aby pojawił się w środku diagramu zamiast na górze.
Czy mogę edytować diagram sekwencji na wizualnym płótnie?
Wizualne płótno edytuje flowcharty. Diagramy sekwencji pisze się w zakładce kodu, gdzie renderują się na żywo w podglądzie — co zwykle i tak jest szybsze, bo diagram sekwencji to w gruncie rzeczy lista linii.