Mermaid.js Flowchart-Syntaxleitfaden

Was ist ein Flussdiagramm?

Ein Flussdiagramm ist eine grundlegende Verhaltenskarte, die einen schrittweisen operativen Ablauf, einen algorithmischen Prozess oder eine sequenzielle Geschäftslogik visualisiert. Indem Systemaktionen als unterschiedliche geometrische Formen dargestellt und der Steuerungsfluss mit gerichteten Pfeilen verfolgt wird, erleichtert ein Flussdiagramm es Softwareentwicklern und Systemarchitekten, bedingte Ausführungswege nachzuverfolgen, einzelne Ausfallpunkte zu isolieren und Systemlogik-Schleifen zu analysieren, bevor tatsächlich Backend-Code geschrieben wird.

Mit Mermaid.js, müssen Sie keine Stunden damit verbringen, Kästchen zu ziehen, Gitterlinien mikromanagen oder Padding-Variablen neu berechnen. Der Layout-Engine werden Knotenkoordinaten dynamisch aus Ihren rohen deklarativen Skripten berechnet, sodass Sie sich vollständig auf die zugrundeliegende Logik Ihres Systems konzentrieren können.

Kern-Syntaxleitfaden: Elemente und Konstrukte

Um ein elegantes, leicht scannbares Flussdiagramm in Mermaid zu gestalten, müssen Sie die Canvas-Richtungsindikatoren, geometrischen Knoteneinschließungen, Verbindungsleitungsvariablen und strukturellen Untergraphen beherrschen.

1. Festlegen der Canvas-Richtungen

Die Ausrichtung Ihres Flussdiagramms wird direkt in Zeile eins durch die Schlüsselwortpaarung bestimmt, die auf die graph oder flowchartWrapper angewendet wird. Sie können die visuelle Skalierungsrichtung Ihres Layouts mit vier primären Ausrichtungsschlüsseln steuern:

• flowchart TD (Oben nach Unten / Vertikale Ausrichtung)
• flowchart BU (Unten nach Oben Ausrichtung)
• flowchart LR (Links nach Rechts / Horizontale Ausrichtung)
• flowchart RL (Rechts nach Links Ausrichtung)

2. Anpassen der Knotengeometrie (Formen)

Standardmäßig wird eine einfache ID-Deklaration als scharfes rechteckiges Feld dargestellt. Um Ihre Diagramme leichter scannbar zu machen, verwenden Sie Mermaids spezialisierte umschließende Klammern, um sofortige visuelle Kontextinformationen in verschiedene Arbeitsablauf-Schritte einzufügen. Jeder einzelne Definitionsbereich muss durch einen Richtungslayout-Bezeichner vorangestellt werden, um korrekt analysiert zu werden:

• Runde Ecken: id(Text) — Stellt einen allgemeinen Prozessschritt dar.
• Stadion-/Kapsel-Form: id([Text]) — Standardmarkierung für Start- und Stop-Grenzmeilensteine.
• Unterprogramm/Vordefiniertes Verfahren: id[[Text]] — Stellt eine eingeschlossene Systemroutine oder externe Klassenskript dar.
• Zylinder/Datenbank: id[(Text)] — Stellt Datenbank-Persistenz, Caches oder Data-Warehouses dar.
• Rauten-/Entscheidungs-Diamant: id{Text} — Stellt bedingte Schalter, if/else-Zweige oder Auswertepunkte dar.
• Parallelogramm: id[/Text/] oder id[Text] — Zeichnet schräge Grenzen, um explizite Daten-Eingabe/Ausgabe (I/O) darzustellen.

Flussdiagramm TD
    start_node([Ausführung starten])
    query_db[(PostgreSQL-Instanz)]
    validate_check{Ist autorisiert?}

3. Verkabelungsregeln für Verbindungen und eingebettete Beschriftungen

Sie können Ihre Verbindungsleitungen anpassen, um unterschiedliche strukturelle Beziehungen und Kommunikationsstile darzustellen. Um Ihre Diagramme übersichtlich zu halten, fügen Sie beschreibende Beschriftungen direkt auf Ihre Verbindungspfade ein:

Flussdiagramm TD
    %% Standardverbindungspfeil mit Textbeschriftung
    A --> |"JSON-Nutzlast"| B

    %% Punktierte/asynchrone Linie mit Textbeschriftung
    B -.-> |"Asynchrones Ereignis"| C

    %% Dicke fettgedruckte Linie mit Textbeschriftung
    C ==> |"Kritischer Schreibvorgang"| D

4. Modulare Isolation über Untergraphen

Um klare Netzwerkperimeter zu schaffen, Microservices zu gruppieren oder Teamverantwortlichkeiten zu isolieren, gruppieren Sie Ihre Elemente innerhalb strukturellerUntergraphWrapper. Sie definieren einen Untergraphen, indem Sie ihm eine interne ID, einen optionalen Anzeigetitel geben und ihn mit einemend Tag:

flowchart TD
    subgraph auth_sub["Sicherheitsgrenze"]
        gateway[API-Gateway] --> auth_worker(Token-Validierer)
    end

Best Practices für saubere Flussdiagramme

• Layouts horizontal entkoppeln: Für lange, mehrstufige Ingenieurpipelines wählen Sie eine flowchart LR Richtung. Dies skaliert viel sauberer auf Standard-Widescreen-Landschaftsmonitoren als ein langes vertikales Layout.
• Komplexe Schleifen isolieren: Wenn ein Workflow eine intensive Wiederholungsschleife enthält, beschriften Sie den Rückwärts-Verbindungspunkt deutlich (z. B. retry --> |"Versuch zurücksetzen"| start) um zu verhindern, dass Leser die Schleife mit einem standardmäßigen Vorwärtspfad verwechseln.
• Mischen von Diagrammtypen vermeiden: Bleiben Sie beim modernen flowchart Schlüsselwort anstelle des veralteten graph Flag beim Rendern komplexer Karten. Der flowchartEngine verwendet einen aktualisierten Layout-Algorithmus, der erweiterte Pfeilkombinationen und sauberere Pfadverläufe unterstützt.

Realitätsnahe Mermaid.js-Flussdiagramm-Beispiele

Beispiel 1: Microservice-Ereignisgesteuertes Ingestions-Netz (Architektur von links nach rechts)

Dieser funktionale Entwurf modelliert einen Web-Telemetrie-Eingabedienst. Er zeigt, wie Daten-Eingaben, Entscheidungs-Diamanten und Cloud-Datenbank-Formen über eine klare horizontale Fläche kombiniert werden können.

flowchart LR
    %% Elementknoten mit expliziten Geometrieformen definieren
    init([Webhook ausgelöst]) --> input_io[/HTTP-Anfrage erfassen/]
    input_io --> auth_check{Token überprüfen}
    
    auth_check --> |"Ungültiger Token"| err_stop([401 Unauthorized zurückgeben])
    auth_check --> |"Gültiges JWT"| write_queue[[In Kafka-Warteschlange veröffentlichen]]
    
    write_queue --> worker_proc(Consumer-Daemon)
    worker_proc --> db_store[(TimescaleDB-Cluster)]
    db_store --> term([Beendeter Fluss])

    %% Schnelle benutzerdefinierte Stilüberschreibungen
    style auth_check fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style err_stop fill:#f8d7da,stroke:#dc3545,stroke-width:1px

Syntaxanalyse: Dieses Diagramm fließt reibungslos von links nach rechts. Der Überprüfungs-Schritt verwendet eine gelbe Entscheidungs-Diamantform (auth_check{Token überprüfen}), die den Ausführungsverlauf sauber in zwei unterschiedliche Ergebnisse aufteilt. Die Datenspeicher sind dank ihrer individuellen Datenbank-Zylinder ([(TimescaleDB-Cluster)]) und Parallelogramm-Eingaben sofort erkennbar.

Beispiel 2: Enterprise-Multi-Tier-Engine für Benutzerregistrierung (Vertikal mit verschachtelten Teilgraphen)

Dieser fortgeschrittene Enterprise-Entwurf zeigt eine Anwendungs-Registrierungspipeline auf. Er ordnet die Schritte vertikal über drei separate strukturelle Teilgraphen an, um unterschiedliche architektonische Schichten darzustellen.

flowchart TD
    subgraph Client_Tier["Präsentations-UI-Schicht"]
        app[Mobile-App-Oberfläche]
        web[Web-SPA-Frontend]
    end

    subgraph Service_Tier["Kern-Gateway-Router"]
        proxy[[Nginx-Eingang-Rückwärts-Proxy]]
        auth_svc(Auth-Dienst-Arbeiter)
    end

    subgraph Persistence_Tier["Sicherer Datenzentrum"]
        main_db[(Benutzerkonten-Primär-DB)]
        cache_node[(Redis-Sitzungs-Cache)]
    end

    %% Kommunikations-Pipelines über Subsystem-Schichten definieren
    app -- "HTTPS-Anfrage" --> proxy
    web -- "HTTPS-Anfrage" --> proxy
    
    proxy --> |"Leite /v1/auth weiter"| auth_svc
    
    auth_svc --> |"Sitzung überprüfen"| cache_node
    auth_svc --> |"Konto speichern"| main_db

Syntaxanalyse: Der Top-down-Orientierungsindikator (flowchart TD) zwingt den Layout-Engine, die Komponenten sauber von oben nach unten zu stapeln. Begrenzungsblöcke gruppieren verwandte Komponenten in unterschiedliche Schichten (Client, Service und Persistenz), wodurch die Gesamtarchitektur ein intuitives, stark strukturiertes Gefühl erhält.