UML v repozitári: Mermaid
Export, ktorý sa vzdá najviac a kúpi jedinú vec, ktorú ostatné nevedia: diagram, ktorý žije vedľa kódu a mení sa v tom istom pull requeste.
5 min čítaniaXMI 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é otázky
Ktoré UML diagramy Mermaid podporuje?
Diagram tried, sekvenčný, stavový a prípadov použitia majú priame ekvivalenty a existuje aj diagram entít a vzťahov. Diagramy komponentov, nasadenia, časové, zloženej štruktúry a ďalšie nemajú syntax, takže model, ktorý ich obsahuje, sa exportuje len čiastočne alebo vôbec.
Prečo vôbec exportovať do Mermaidu, keď stráca detail?
Pretože je to text a text patrí do repozitára. Mermaid diagram sa objaví v diffe pull requestu, na GitHube a GitLabe sa vykreslí sám a prejde revíziou spolu so zmenou, ktorú opisuje - a to je jediný mechanizmus, ktorý spoľahlivo udrží diagram pravdivý.
Je Mermaid náhradou modelovacieho nástroja?
Nie. Mermaid kreslí diagramy; modelovací nástroj drží jeden model za mnohými pohľadmi. Keď premenujete triedu v Mermaide, upravili ste jeden súbor - keď ju premenujete v modeli, aktualizuje sa každý pohľad, ktorý ju zobrazuje. Mermaid použite na pohľady, ktoré musia žiť v repozitári.
Súvisiace články