UML im Repository: Mermaid
Der Export, der am meisten aufgibt und das eine kauft, was die anderen nicht können: ein Diagramm, das neben dem Code lebt und sich im selben Pull Request ändert.
5 Min. LesezeitXMI 2.5.13 von 3
Die kurze Antwort
- Klasse, Sequenz, Zustand, Anwendungsfall und ER haben direkte Entsprechungen. Für Komponenten, Verteilung, Zeitverlauf und Kompositionsstruktur gibt es in Mermaid gar keine Syntax.
- Der Grund, diesen Verlust hinzunehmen: Mermaid ist Text, und Text gehört ins Repository.
- Ein Mermaid-Diagramm taucht im Diff eines Pull Requests auf und wird mit der Änderung geprüft, die es beschreibt - der einzige Mechanismus, der ein Diagramm verlässlich wahr hält.
- Es ist kein Modellierungswerkzeug. Eine Klasse in Mermaid umzubenennen ändert eine Datei; sie im Modell umzubenennen aktualisiert jede Sicht, die sie zeigt.
01Der Handel, klar benannt#
Mermaid trägt von den drei Exportformaten am wenigsten Modell und löst als einziges das Problem, das die meiste Dokumentation tatsächlich hat. XMI trägt das Metamodell; .qea trägt Metamodell und Layout; Mermaid trägt ungefähr das, was in einen Absatz Text passt - und rendert in einer README ohne jeden Build-Schritt.
Das ist das ganze Argument, und es ist ein gutes. Ein als PNG in ein Wiki exportiertes Diagramm ist binnen eines Quartals falsch und niemand merkt es, weil nichts an einer Codeänderung jemanden zwingt, hinzusehen. Ein Diagramm in docs/architecture.md taucht im Diff auf, sobald seine Datei angefasst wird, und wer die Änderung lesen kann, sieht das Diagramm ihr widersprechen.
02Was Mermaid zeichnen kann und was nicht#
| Element | Notation | Was es bedeutet |
|---|---|---|
| Klassendiagramm | Gut | Klassen, Member, Sichtbarkeit, alle sechs Beziehungsarten und Multiplizitäten. Die engste Entsprechung zu UML in der ganzen Syntax. |
| Sequenzdiagramm | Gut | Teilnehmer, synchrone und asynchrone Nachrichten, Aktivierungen und die Blöcke alt, opt, loop und par. |
| Zustandsdiagramm | Gut | Zustände, Transitionen mit Guards, zusammengesetzte Zustände, Historie. |
| ER-Diagramm | Gut | Krähenfuß-Kardinalität und Attributlisten. Eine enge Entsprechung zum ER-Artikel. |
| Anwendungsfalldiagramm | Teilweise | Akteure und Fälle, aber kein vollwertiges include oder extend. |
| Komponenten, Verteilung, Timing | Fehlt | Überhaupt keine Syntax. Eine Annäherung per Flussdiagramm ist möglich und ist nicht dasselbe Diagramm. |
Auch in den guten Zeilen lohnt es, das Verlorene zu benennen: Stereotypen, Notizen, Constraints und jede Spur von Layout. Mermaid legt seine Diagramme selbst aus, die Anordnung, an der Sie eine Stunde saßen, überlebt also nicht - und bei einem Diagramm, das bei jeder Änderung neu erzeugt wird, ist das eher ein Vorteil.
03Damit es hält#
Exportieren Sie die Sichten, die ein Entwickler tatsächlich öffnen würde, und das sind fast nie alle. Ein Klassendiagramm der Kerndomäne und ein Sequenzdiagramm des Ablaufs, den alle debuggen, ergeben ein besseres Repository als vierzehn Dateien, die niemand liest.
Checken Sie das Mermaid ein, kein gerendertes Bild. GitHub, GitLab und die meisten Static-Site-Generatoren rendern mermaid-Blöcke direkt. Ein Bild neben der Quelle ist eine zweite Kopie, die ihr widersprechen wird.
Neu erzeugen statt von Hand ändern. In dem Moment, in dem jemand einen Klassennamen im Markdown statt im Modell korrigiert, ist der Export kein Export mehr und die beiden Fassungen beginnen zu driften - genau das Versagen, um das es in ein Modell aktuell halten geht.
In je einer Zeile
- 01Mermaid trägt von den drei Formaten am wenigsten und ist das einzige, das im Diff lebt.
- 02Klassen, Sequenz, Zustand und ER passen gut; Komponenten, Verteilung und Timing haben keine Syntax.
- 03Stereotypen, Notizen, Constraints und Layout gehen verloren - und der Layoutverlust ist hier in Ordnung.
- 04Exportieren Sie die zwei oder drei Sichten, die Entwickler konsultieren, nicht das ganze Modell.
- 05Checken Sie den Text ein, nie ein gerendertes Bild, und erzeugen Sie neu statt von Hand zu ändern.
04Häufige Fragen#
Welche UML-Diagramme unterstützt Mermaid?
Klassen-, Sequenz-, Zustands- und Anwendungsfalldiagramm haben direkte Entsprechungen, und ein Entity-Relationship-Diagramm gibt es ebenfalls. Für Komponenten, Verteilung, Zeitverlauf, Kompositionsstruktur und die übrigen existiert keine Syntax, ein Modell mit ihnen exportiert also nur teilweise.
Warum überhaupt nach Mermaid exportieren, wenn Details verloren gehen?
Weil es Text ist, und Text gehört ins Repository. Ein Mermaid-Diagramm erscheint im Diff eines Pull Requests, rendert auf GitHub und GitLab von selbst und wird zusammen mit der Änderung geprüft, die es beschreibt - der einzige Mechanismus, der ein Diagramm verlässlich wahr hält.
Ersetzt Mermaid ein Modellierungswerkzeug?
Nein. Mermaid zeichnet Diagramme; ein Modellierungswerkzeug hält ein Modell hinter vielen Sichten. Wer eine Klasse in Mermaid umbenennt, hat eine Datei geändert - wer sie im Modell umbenennt, aktualisiert jede Sicht, die sie zeigt. Nutzen Sie Mermaid für die Sichten, die im Repository leben müssen.
In dieser Reihe
- 01UML nach XMI
- 02Sparx .qea Rundlauf
- 03UML nach Mermaid
Passend dazu
Modellierungspraxis
Modellierungspraxis
Modellierungspraxis
Verhaltensdiagramme