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
01The trade, stated plainly
Mermaid is the worst of the three export formats at carrying a model and the only one of them that solves the problem most documentation actually has. XMI carries the metamodel; .qea carries the metamodel and the layout; Mermaid carries roughly what fits in a paragraph of text - and renders in a README without a build step.
That is the whole argument, and it is a good one. A diagram exported as PNG into a wiki is wrong within a quarter and nobody notices, because nothing about changing the code obliges anyone to look at it. A diagram in docs/architecture.md shows up in a diff when its file is touched, and a reviewer who can read the change can see the diagram disagree with it.
02What Mermaid can and cannot draw
| Element | Notation | What it means |
|---|---|---|
| Class diagram | Good | Classes, members, visibility, all six relationship kinds and multiplicities. The closest match to UML in the whole syntax. |
| Sequence diagram | Good | Participants, sync and async messages, activations, and alt, opt, loop and par blocks. |
| State diagram | Good | States, transitions with guards, composite states and history. |
| ER diagram | Good | Crow's foot cardinality and attribute lists. A close match to the ER article. |
| Use case diagram | Partial | Actors and cases, but no first-class include or extend. |
| Component, deployment, timing | Absent | No syntax at all. A flowchart approximation is possible and is not the same diagram. |
What is lost even in the good rows is worth naming: stereotypes, notes, constraints, and every trace of layout. Mermaid lays out its own diagrams, so the arrangement you spent an hour on does not survive - and for a diagram that is going to be regenerated on every change, that is a feature rather than a loss.
03Making it stick
Export the views a developer would actually open, which is almost never all of them. One class diagram of the core domain and one sequence diagram of the flow that everybody debugs is a better repository than fourteen files nobody reads.
Commit the Mermaid, not a rendered image. GitHub, GitLab and most static site generators render fenced mermaid blocks directly. An image checked in beside the source is a second copy that will disagree with it.
Regenerate rather than hand-edit. The moment somebody fixes a class name in the Markdown instead of in the model, the export has stopped being an export and the two versions begin to drift - which is the failure mode keeping a model current is entirely about.
In one line each
- 01Mermaid carries the least of the three formats and is the only one that lives in a diff.
- 02Class, sequence, state and ER map well; component, deployment and timing have no syntax.
- 03Stereotypes, notes, constraints and layout are all lost - and losing layout is fine here.
- 04Export the two or three views developers consult, not the whole model.
- 05Commit the text, never a rendered image, and regenerate rather than hand-edit.
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.
Passend dazu