Wie man ein Mermaid-Sequenzdiagramm schreibt

Das Minimum

Deklariere den Diagrammtyp, dann schreibe eine Zeile pro Nachricht. Teilnehmer werden bei der ersten Erwähnung angelegt, in der Reihenfolge, in der sie auftauchen.

sequenceDiagram
  User->>API: POST /orders
  API->>DB: INSERT order
  DB-->>API: order id
  API-->>User: 201 Created

💡Deklariere Teilnehmer explizit mit participant User, wenn du eine bestimmte Links-nach-rechts-Reihenfolge willst statt der Reihenfolge der ersten Erwähnung.

Pfeiltypen

Die Konvention, an die man sich halten sollte: durchgezogen für den Aufruf, gestrichelt für die Rückgabe. Ein Leser erkennt dann eine Anfrage von einer Antwort, ohne eine einzige Beschriftung zu lesen.

Teilnehmer und Aliase

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

Benutze actor U as Browser statt participant, um eine Strichfigur zu zeichnen — lohnt sich für den Menschen am linken Rand eines Authentifizierungsflusses.

Aktivierungsbalken

Aktivierungsbalken zeigen, wie lange ein Teilnehmer beschäftigt ist. Markiere sie entweder explizit mit activate/deactivate, oder hänge + und - an die Pfeile — das ist kürzer und schwerer aus dem Gleichgewicht zu bringen.

sequenceDiagram
  User->>+API: POST /pay
  API->>+Bank: charge
  Bank-->>-API: authorised
  API-->>-User: receipt

Loops, Bedingungen und parallele Abläufe

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
  end

• loop <label> … end — Wiederholung.
• alt <label> … else <label> … end — sich gegenseitig ausschließende Zweige.
• opt <label> … end — ein Zweig, der einfach nicht eintreten kann.
• par <label> … and <label> … end — Dinge, die gleichzeitig passieren.
• critical / break — ein Abschnitt, der nicht unterbrochen werden darf, und ein früher Ausstieg.

Notizen

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 erstreckt sich über zwei Teilnehmer und ist der richtige Ort für eine Einschränkung, die zur Interaktion gehört statt zu einer der beiden Seiten.

Ein vollständiges Beispiel

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