最近、いくつかの新しいプロジェクトの設計に参加し、クラス図やフローチャートなど、多くの設計文書を作成する必要がありました。もちろん、Visio、StarUML、draw.io などの優れた図面ツールがたくさんあります。しかし、少なくとも私にとっては、それらには致命的な欠点があります。それは、GUI操作に完全に依存しており、DSLを使って図例を作成することができないという点です。この方法にはいくつかの問題があります：
- 効率が低い。マウスでドラッグしたりクリックしたりする速度は、キーボード入力にはかなわない。
- 外部ツールを開いて編集する必要があり、エディタ内で完了できないため、この断絶感は設計思考に影響を与えます。
- バージョン管理に図例の設計を組み込むことができません。
そこでネットで半日探し回り、PlantUML というフォーマットを見つけました。これはDSLに依存してUML図を描くツールです。Markdownのようなものと理解でき、特定のマークアップ言語を使用して、普通のテキストの視覚効果を高めるものです。
実は PlantUML はすでに多くの Markdown エディターに標準機能として組み込まれており、Markdown 内に直接 PlantUML を挿入してレンダリングすることができます。ただし、Github は現在対応していないため、ドキュメントを作成する際には、専用の ***.puml ファイルを作成して記述する必要があります。
ここでIDEAの小さなツールを一つ紹介します：PlantUML integration。図例を書いている時に、リアルタイムで横にレンダリング効果を表示できます。
PlantUMLは多種多様な図をサポートしており、非常に強力です。直接中国語のドキュメントを参照することができます。
PlantUML はオープンソースプロジェクトで、以下の迅速な描画をサポートしています：シーケンス図 ユースケース図 クラス図 アクティビティ図 コンポーネント図 ステート図 オブジェクト図 デプロイメント図 タイミング図
また、以下の非UML図もサポートしています：ワイヤーフレーム アーキテクチャ図 仕様記述言語(SDL) Ditaa図 ガントチャート マインドマップ 作業分解構造(WBS)図 AsciiMathやJLaTeXMath記号の数学公式 エンティティリレーションシップ図
最後に、PlantUMLをどのように文書統合および管理するかについて述べます。
このようなエンジニアリングドキュメントは、コードと一緒にGitで管理するのが非常に適しています。私もそうしています。しかし、GitHubはPlantUMLをレンダリングすることはサポートしていません。GitHubでドキュメントを閲覧する際に、PlantUMLドキュメントをダウンロードしてから、plantumlツールで画像をレンダリングする必要があるのでしょうか？答えはノーです。PlantUMLはすでに解決策を提供してくれています — PlantUML Serverです。サーバー側で直接画像をレンダリングしてフロントエンドに表示することができます。そして、www.plantuml.com は無料でレンダリングサービスも提供しています。
https://www.plantuml.com/plantuml/proxy?src=RESOURCE&idx=INDEX&fmt=FORMAT
- src: puml ソースドキュメントのアドレスです。もしドキュメントが github 上にホストされている場合は、ファイルの CDN アドレスを直接取得できます。
- idx: 文書内に複数のUMLブロック（@startumlで始まり、@endumlで終わる）が含まれている場合、idxを使用してどのUMLをレンダリングするかを指定できます。
- 出力フォーマットはデフォルトで png です。サーバーが最大ファイルサイズを制限しているため、png でレンダリングすると画像が不完全になる可能性があります。帯域幅の消費を減らし、どこで表示しても十分にクリアな画像にするために、svg に設定することをお勧めします。
このようにして、PlantUML を画像として直接 Github 上の Markdown 文書に挿入することができます。