Mermaid.js Sequenzdiagramm-Syntaxanleitung

Was ist ein Sequenzdiagramm?

Ein Sequenzdiagramm ist ein wesentliches Verhaltens-UML-Diagramm , das entwickelt wurde, um den zeitlichen Ablauf von Nachrichten, Funktionsaufrufen und Datenpaketen zwischen verschiedenen Systementitäten über eine lineare Zeitleiste zu visualisieren. Als Kern-UML-Diagrammtyp, zeichnet es Laufzeitinteraktionen durch Stapeln von Systemkomponenten entlang der X-Achse als vertikale Lebenslinien und verfolgt Nachrichtenaustausche entlang der Y-Achse nach. Diese Bauplanung ist für Entwickler unverzichtbar, um verteilte API-Handschlag-Abstürze, Mikroservice-Orchestrierungspfade oder Echtzeit-Authentifizierungsabläufe zu debuggen.

Mit Mermaid.js, können Sie komplexe zeitliche Prozesse mit einer intuitiven Textstruktur skripten. Die Engine verarbeitet automatisch den vertikalen Abstand, verwaltet die Ausrichtung von Nachrichtenpfeilen und zeichnet Laufzeit-Aktivitätsblöcke sauber über Ihre Leinwand.

Grundlagen der Syntax: Elemente und Konstrukte

Um ein genaues, leicht scannbares UML-Sequenzdiagramm in Mermaid zu gestalten, müssen Sie die Deklarationen von Teilnehmern, Varianten von Nachrichtenpfeilen, explizite Lebenslinien und bedingte Blockstrukturen beherrschen.

1. Deklaration von Teilnehmern und Akteuren

Sie deklarieren eine Standard-Systementität mit dem Teilnehmer -Schlüsselwort. Wenn die Entität einen menschlichen Endbenutzer oder einen externen Bediener darstellt, verwenden Sie das Akteur -Schlüsselwort, um ein Standard-Stickfiguren-Symbol auf der Leinwand darzustellen:

sequenzDiagramm
    akteur Client
    teilnehmer API als Gateway-Router

Pro-Tipp: Verwenden Sie das als -Schlüsselwort, um lange Komponentennamen auf kompakte interne Aliase abzubilden, wodurch Ihre Nachrichtenskripte knapp und lesbar bleiben.

2. Formatierung von Nachrichtenpfeilen

Der Typ der Linie und der Pfeilspitze, die Sie verwenden, bestimmt den Kommunikationsstil zwischen Ihren Systemteilnehmern:

• ->> **Synchroner Aufruf:** Eine durchgezogene Linie mit einem gefüllten Pfeilkopf. Stellt eine blockierende Anforderung dar, die auf die Ausführung abwartet.
• --> **Antwortlinie:** Eine gestrichelte Linie mit einem offenen Pfeilkopf. Wird verwendet, um Datenpakete oder Bestätigungs-Tokens zurückzugeben.
• -> **Asynchroner Aufruf:** Eine durchgezogene Linie mit einem offenen Pfeilkopf. Zeigt eine nicht-blockierende Nachricht oder Ereignisübertragung an.

sequenceDiagram
    App->>Server: Anfrage-Payload
    Server-->App: 200 OK Antwort

3. Verwaltung der Aktivitätsleisten

Um genau darzustellen, wann ein Systemkomponente eine Aufgabe ausführt oder Thread-Speicher belegt, verwenden Sie die Befehleactivate und deactivate Befehle. Alternativ können Sie ein Pluszeichen (+) oder ein Minuszeichen (-) direkt an Ihre Nachrichtziele anhängen, um eine schnelle visuelle Kurzform zu verwenden:

sequenceDiagram
    Client->>+Server: Daten verarbeiten
    %% Server ist nun visuell aktiv
    Server-->-Client: Ergebnisse zurückgeben

4. Strukturieren von Bedingungen und Alternativen (Alt, Opt, Loop)

Um verzweigte Laufzeitlogik, Token-Auswertungen oder wiederholte Anforderungsversuche zu behandeln, umschließen Sie Ihre Nachrichtenskripte mit standardmäßigen Blockfragmenten:

• alt / else — Bewertet bedingte Pfade (ähnlich wie if/else-Codeblöcke).
• opt — Definiert einen optionalen Schritt, der nur unter bestimmten Kriterien ausgeführt wird.
• Schleife — Wiederholt eine Ausführungssequenz, bis eine Bedingung erfüllt ist.

sequenceDiagram
    Schleife Alle 30 Sekunden
        Client->>Server: Herzschlag-Ping
    Ende

Best Practices für saubere Ablaufzeiten

• Halte Lebenslinien übersichtlich: Vermeide das Auflisten von Dutzenden von Mikro-Entitäten entlang der X-Achse. Wenn ein Prozess mit kleineren Hilfsklassen interagiert, abstrahiere sie hinter einer hochwertigen Systemgrenze wie[Auth-Arbeiter] oder [Cache-Pool].
• Kennzeichne Statuscodes explizit: Wenn du Antwortrückgaben schreibst (-->), schreibe nicht einfach „Daten zurückgeben“. Kennzeichne den Pfad mit expliziten HTTP-Statuscodes oder Ereignistypen (z. B. "201 Erstellt (JWT-Token)") um Ingenieuren präzisen Kontext zu geben.
• Implementiere Notizen für komplexe Berechnungen: Verwende die Note über, Note links von, oder Note rechts von Anweisungen, um nicht-visualisierte Operationen zu dokumentieren, wie interne Verschlüsselungsschritte oder Datenhashing in der Datenbank.

Beispiele für echte Mermaid.js-Ablaufdiagramme

Beispiel 1: Gesicherter OAuth2-Token-Austausch-Fluss (Aktivierungs- und Alternativblöcke)

Dieser funktionale Entwurf modelliert einen sicheren Benutzeranmeldevorgang. Er zeigt, wie menschliche Akteure, explizite Systemlebenslinien und komplexe Validierungswege mit einem alt/else-Block kombiniert werden können.

sequenceDiagram
    actor User als Endbenutzer
    participant App als Mobile-App-Client
    participant Auth als Auth0-Identitätsanbieter

    User->>+App: Klicken Sie auf "Anmelden mit OAuth"
    App->>+Auth: Umleitung mit client_id und scope
    Auth-->>User: Anmelde-Oberfläche anzeigen
    User->>Auth: Anmeldeinformationen übermitteln
    
    Auth->>Auth: Passwort-Hash überprüfen
    
    alternativ Anmeldeinformationen gültig
        Auth-->>App: 302-Umleitung mit Auth-Code
        App->>Auth: Austausch des Codes gegen Zugriffstoken
        Auth-->>-App: JWT-Token (IdToken) zurückgeben
        App-->>User: Benutzerkonto-Startseite anzeigen
    sonst Ungültige Anmeldeinformationen
        Auth-->>App: 401-Fehler „Nicht autorisiert“ zurückgeben
        App-->>-User: „Ungültiger Benutzername/Kennwort“-Warnung anzeigen
    ende

Syntax-Aufschlüsselung: Dieser Zeitstrahl verfolgt eine mehrparteienbasierte Handshake-Interaktion. Die alt / else Container zeigt die binären Überprüfungswege klar auf, wodurch sichergestellt wird, dass Fehlerzustände zusammen mit dem normalen Ablauf vollständig dokumentiert sind.

Beispiel 2: Verteilter Bestellinventar-Checkout (parallele Prozesse und Notizen)

Dieser erweiterte Systementwurf zeigt eine Unternehmens-eCommerce-Checkout-Pipeline auf. Er nutzt parallele Blöcke (par) zur Darstellung paralleler API-Ausführungsabläufe und zur Behandlung von Datenbank-Sperrhinweisen innerhalb der Topologie.

sequenceDiagram
    participant Web als Web-Frontend
    participant Ord als Bestell-Orchestrator
    participant Inv als Inventar-Service
    participant Pay als Zahlungsgateway

    Web->>+Ord: Checkout-Anfrage senden
    Note über Ord: Überprüfung der Artikel-Vorratsverfügbarkeit
    
    par Concurrente API-Aufrufe ausführen
        Ord->>+Inv: Inventar-Elemente sperren
        Inv-->-Ord: Inventar reserviert (Vorrat gesperrt)
    und
        Ord->>+Pay: Autorisierung der Kreditkartenbelastung
        Pay-->-Ord: Erfolgreiche Erfassung (Belastung abgeschlossen)
    ende
    
    opt Prozess-Zuweisung schlägt fehl
        Note rechts von Ord: Rollback-Saga ausführen, falls ein Aufruf fehlschlägt
    ende
    
    Ord-->-Web: 200 Erfolg Checkout bestätigt

Syntax-Aufschlüsselung: Der par / and Container weist die Engine an, parallele Ausführungen zusammenzufassen und gleichzeitige Backend-Abläufe zu dokumentieren. Die Note über und Note rechts von Tags fügen technische Laufzeit-Erklärungen direkt in das Raster des Canvas ein, wodurch Teams die Hintergrundtransaktionen wie Daten-Sperrungen und Rollback-Sagas verstehen können, ohne die Hauptnachrichten-Pfeile zu überladen.