Bevor Sie sich spezifischen architektonischen Layouts wie komplexen Flussdiagrammen oder zeitlichen Ablaufdiagrammen widmen, ist es unbedingt erforderlich, die grundlegenden Regeln zu verstehen, die dieMermaid-Handbuch. Mermaid basiert auf einem sauberen, hochintuitiven Textnotationssystem. Sobald Sie verstehen, wie der Engine einen Canvas-Typ initialisiert, strukturelle Komponenten benennt und Richtungspfeile routet, wird das Erstellen jedes komplexen Systemlayouts völlig natürlich.
Dieser kurze Überblick behandelt die globalen strukturellen Syntaxmechanismen, die sich auf nahezu jedes Mermaid-Diagrammtyp innerhalb der VPasCode-Umgebung beziehen.
1. Die obligatorischen Diagrammtyp-Umwicklungen
Jeder einzelne Block von Mermaid-Code muss mit einer expliziten Deklaration seines Diagrammtyps in der allerersten Zeile beginnen. Dies sagt dem VPasCode-Parser genau, welchen strukturellen Engine er in Ihrem Vorschaucanvas starten soll:
graph TD— Gibt ein Flussdiagrammlayout von oben nach unten an.sequenceDiagram— Gibt ein zeitlich geordnetes Ablaufdiagramm für die Laufzeit an.classDiagram— Gibt eine strukturelle objektorientierte Software-Skizze an.
Im Gegensatz zu anderen Text-zu-Diagramm-Engines erfordert Mermaid keine abschließenden End-Tags. Der Parser liest einfach die strukturelle Deklaration in Zeile eins und kompiliert alles, was direkt darunter in Ihrem Codeblock-Container geschachtelt ist.
2. Deklarieren von Elementen: IDs im Vergleich zu Anzeigetexten
Beim Modellieren eines Software-Systems erstellen Sie verschiedene strukturelle Elemente wie Komponenten, Datenbanken oder Mikrodienste. In Mermaid deklarieren Sie ein Element, indem Sie eine kurze interne alphanumerische ID definieren, gefolgt unmittelbar von einem eckigen Klammerstil, der seine visuelle Form steuert, sowie einem benutzerfreundlichen Anzeigetext:
microservice_id[Bezahlverarbeitungs-API]
db_id[(Benutzertransaktions-SQL)]Warum dies eine Best-Practice ist: Die Verwendung einer kurzen, sauberen internen ID (wiemicroservice_id) macht das Zeichnen von Beziehungslinien später deutlich schneller. Wenn Sie jemals den Kunden-facing-Label von „Bezahlverarbeitungs-API“ auf „Globaler Kassen-Service“ ändern müssen, müssen Sie ihn nur in der einen Zeile bearbeiten, in der er deklariert ist, anstatt Dutzende von Zeilen in Ihrem Skript zu aktualisieren.
3. Beherrschen von Beziehungspfeilen und Richtungsverläufen
Verbindungen zwischen Systemknoten werden mit Kombinationen von Strichen (-), Gleichheitszeichen (=), und Pfeilklammern (>). Die Art Ihrer Linien gibt Ihnen implizite Kontrolle darüber, wie der automatisierte Layout-Engine Ihr Diagramm skaliert:
A --> Bzeichnet einen standardmäßigen gerichteten Pfeil, der von Element A geradewegs zu Element B zeigt.A --- Bzeichnet eine flache, ungerichtete Verbindungslinie ohne Pfeilspitze, ideal für einfache Assoziationen.A -.-> Berstellt eine gepunktete Abhängigkeitslinie, die als Branchenstandard für die Kennzeichnung asynchroner Abhängigkeiten oder Netzwerk-Webhooks gilt.A ==> Berstellt eine dicke, fettgedruckte Verbindungslinie, ideal zum Hervorheben primärer Datenverarbeitungspfade oder kritischer Infrastrukturverbindungen.
4. Inline-Hinzufügen von Kontext: Beschriftungen und Code-Kommentare
Klare Dokumentation beruht stark darauf, angemessenen Kontext um Ihre visuellen Linien und Text-Skripte zu setzen:
Beschriftung von Verbindungslinien
Sie können erklärenden Text direkt auf jede Verbindungslinie setzen, indem Sie den Text zwischen zwei Strichmengen einfügen oder ein Pipe-Zeichen (“|Text|) direkt nach Ihrer Beziehungskennzeichnung:
client_id -- "HTTPS POST /v1/checkout" --> api_id
client_id --> |HTTPS POST /v1/checkout| api_idSchreiben von Code-Kommentaren
Wenn Sie eine administrative Notiz, ein Design-Credit oder eine architektonische Erklärung innerhalb Ihrer Skript-Datei hinterlassen möchten, ohne dass eine sichtbare Box auf der Leinwand angezeigt wird, verwenden Sie doppelte Prozentzeichen (%%). Dies teilt dem Engine mit, diese Zeile vollständig zu überspringen:
%% TODO: Wir müssen diese Grenzbox aktualisieren, sobald die DevOps-Migration abgeschlossen ist
[Legacy Monolith] --> [Neues Microservice]