UML v repozitáři: Mermaid
Export, který se vzdá nejvíc a koupí jedinou věc, kterou ostatní neumí: diagram, který žije vedle kódu a mění se ve stejném pull requestu.
5 min čteníXMI 2.5.13 z 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.
04Časté dotazy
Které UML diagramy Mermaid podporuje?
Diagram tříd, sekvenční, stavový a případů užití mají přímé ekvivalenty a existuje i diagram entit a vztahů. Diagramy komponent, nasazení, časové, složené struktury a další nemají syntaxi, takže model, který je obsahuje, se exportuje jen částečně nebo vůbec.
Proč vůbec exportovat do Mermaidu, když ztrácí detail?
Protože je to text a text patří do repozitáře. Mermaid diagram se objeví v diffu pull requestu, na GitHubu a GitLabu se vykreslí sám a projde revizí spolu se změnou, kterou popisuje - a to je jediný mechanismus, který spolehlivě udrží diagram pravdivý.
Je Mermaid náhradou modelovacího nástroje?
Ne. Mermaid kreslí diagramy; modelovací nástroj drží jeden model za mnoha pohledy. Když přejmenujete třídu v Mermaidu, upravili jste jeden soubor - když ji přejmenujete v modelu, aktualizuje se každý pohled, který ji zobrazuje. Mermaid použijte na pohledy, které musí žít v repozitáři.
Související články