Mermaid を用いたマークダウンにおける UML 記述の基礎

UML をコードベースで記述する方法の覚え書き

検証環境

• Windows 11 Home
• WSL2 Ubuntu 24

そもそも Mermaid とは?

• JavaScript ベースの UML 作成ツール (公式サイト)
• コードベースで UML を作成する場合は他に PlantUML が選択肢として考えられるが, PlantUML が Java の環境構築が必要なのに対し Mermaid は VSCode の拡張だけで済むのでお手軽な印象
• github などでも動作するらしい

環境構築

• VSCode の拡張機能 "Markdown Preview Enhanced" をインストールすれば完了

実行方法

• markdown ファイルを作成し, mermaid のコードブロック (バッククォートで囲い先頭に mermaid と書いたもの) 内にコードを記述するとプレビュー画面で対応する図が表示される

共通基礎文法

コメントアウト

• コメントアウトはパーセント二つを用いる

A --> B
%% this is a comment
        

• 次のように行内にコメントを含めることはできない

A --> B %% this comment cause error
        

グラフの成長方向

• グラフの成長方向を宣言することで, 上下左右どの方向からどの方向に伸びるか指定できる

TB: Top to Bottom
BT: Bottom to Top
LR: Left to Right
RL: Right to REFT

• 指定はグラフの種類 (flowchart, graph など) の後につけるか, 以下のように指定

direction TB
        

• 詳しくは公式ドキュメントの 方向性に関する部分 を参照のこと

各種グラフの基礎

以下は各種グラフの書き方についての説明

フローチャート

• 基本は以下の通り

flowchart
    START --> END
        

• "end" など一部の単語は予約語になってしまっているので使用を避ける必要あり

• テキトウな依存関係を書いても自動でレイアウトを考えてくれる

flowchart LR
A --> B
C --> D
D --> A
B --> C
        

• 各記号に括弧をつけることで中のテキストを設定可能
• 括弧の種類によってノードの形状も変更可能

flowchart LR
A[test-A] --> B[(test-B)]
B --> C(test-C)
D([test-D]) --> E[[test-E]]
E --> F((test-F))
G[\test-G\] --> H[/test-H\]
H --> I>test-I]
        

• その他の形状については ドキュメント にいろいろ載っている

グラフ

• 基礎的なグラフ (フローチャートも同じような図がかけるので使い分けは不明)

graph TD
graph TD
  A[app.py] --> B[utils.py]
  A --> C[models/user.py]
  C --> D[database/db.py]
  D --> E[(PostgreSQL)]
  B --> E
  C --> B
  %% comment
  A --> C
        

• 括弧の種類などはフローチャートと同じ
• 複雑な依存関係でもどうにか図にしてくれる

シーケンス図

• 基本的には主体から別主体へ矢印を引き, コロンの後に内容を記述する

sequenceDiagram
  A ->> B: normal arrow
  B --> A: dot dot dot
  B -->> A: dot with arrow
  actor C
  participant D as testD
  C <<-->> D: test
  activate D
  D --x C: activated!
  deactivate D
        

• 記号にテキストを付けたい場合は participant A as hoge のように記述する
• activate, deactivate を用いて期間を記述

アーキテクチャ (システム構成)

• ベータ版なのでこれから気泡が変わる可能性もあるが, 以下のようにアーキテクチャを記述できる

architecture-beta
 group api1(cloud)[test cloud]
 group api2(cloud)[test 2]
 
 service db1(database)[db hoge] in api1
 service disk1(disk)[disk hoge] in api1
 service server1(server)[server hoge] in api1

 db1:L -- R:disk1
 server1:T -- B:disk1

 service net1(internet)[local net] in api2
 service net2(internet)[private net] in api2

 net1:B -- B:net2
        

• 簡易的な模式図ならこれでよさそう