Zenn
NCDCエンジニアブログ
🔥

PlantUMLでテーブル定義とER図を作成したら結構良かった

おーぬま
2024/11/01に公開
PlantUML
UML
documentation
idea

概要

テーブル定義書やER図をExcelで書くことは珍しくないと思います。私も経験があります。
PlantUMLで作ってみたら良さげだったのでこの記事を書きました。

よくあるシナリオ

テーブル定義書は〜〜_20241010_ver2.0.xlsxなど別名保存してファイル名でバージョン管理し、変更箇所を赤字や取り消し線などで差分を管理、それら変更は変更履歴用のシートに漏れなく追記する。もちろん変更を加える際はセル結合や関数は壊さないように注意する必要があるし、初版の納品時はそれら赤字や取り消し線などは綺麗にした上でA1セルにカーソルを合わせて保存する。
いざレビューに出したら、共有したファイルのURLが間違えていた、ER図側への反映が漏れていた、赤字が残ったままだった、コピペでフォントが崩れた、最新ではないバージョンに上書き保存してしまっていた、など指摘が上がってきてしまった。

このシナリオは極端な例ですが、作る側も、レビューする側も、内容ではなく見た目やファイル自体の管理方法について多くの時間を割かなければなりません。こういった「Excelのための作業」が結構苦手なので、開発ドキュメントはなるべくGit管理したい派閥です。

参考記事

この記事では実際にやってみた効果や所感を記載していこうと思うので、PlantUMLの具体的な使い方などは別の記事を参照していただければ幸いです。

https://qiita.com/Tachy_Pochy/items/752ef6e3d38e970378f0
https://qiita.com/murakami-mm/items/4c50d1949a8b10016ef7

実際にやったこと

テーブル毎のファイルを作成する

  • 1テーブルごとに.pumlファイルを作成する
  • 作成したファイルはentities/配下に置く
  • VSCodeの拡張で生成したpngファイルも同階層に置く
サンプル
members.puml
@startuml members
package 組織集約 {
	entity メンバー {
        * id [メンバーID] [integer] < PK >
        * organization_id [所属組織ID] [integer] < FK >
        --
        * name [氏名] [varchar(10)]
        * email [メールアドレス] [varchar(255)]
          tel [電話番号] [varchar(11)]
        * role [ロール] [enum]
        * created_at [作成日時] [datetime]
        * updated_at [更新日時] [datetime]
	}

    note right of メンバー
        tel
        ハイフンなしのVARCHARで登録

        role
        * ADMIN : システム管理権限
        * USER : 通常権限
    end note
}
@enduml


レンダリングした画像のサンプル。prefixに*がついているカラムはNotNullを指しています。

メリット

  • 画像になってくれるので見やすい
    • 参考記事のサンプルにある通り1ファイルに複数テーブルの情報をまとめて記述してみましたが、私が実践したプロジェクトではテーブル数やカラム数が多く、レンダリングされた図が小さくなりすぎてしまい単純に見辛かったです
  • 更新しやすい、レビューしやすい
    • 以前別の案件ではMarkdownの表でテーブル定義を書いていたのですが、VSCodeの拡張入れているとはいえ個人的には書きにくかったです。またMarkdownの表だと同じ内容でも以下のような余計な差分[^1]が発生してしまうのもデメリットでしたが、PlantUMLだと発生しないので助かります。

デメリット

  • ファイル数が増えすぎる
    • 同階層に.pumlと.pngのどちらも配置しているので、テーブル数が多いと単純に2倍のファイル数になってしまいます。画像だけ別ディレクトリに分けることも検討して良いと思います
    • VSCodeの拡張機能で同階層にpngを吐き出すのが一番ラクそうだし、なるべく手作業で移動させるとかはミスの原因になるのでやりたくなかったから私は同階層に置いたままにしています。（これで走り始めてしまったから今さら面倒というのが一番の理由ですが...）
  • 作り始めの段階ではかなり面倒
    • テーブル数が多いと1ファイルずつ移動しながら作るので大変でしたし、レビューする側も file changes の数が多くて面食らってしまいます。

ここら辺は好みかなとも思いますし、図が小さくなってでもある程度の粒度の集約毎にテーブルを見たいケースもあるはずなので、プロジェクトごとにカスタマイズするのをオススメします。

ER図を別ファイルで作成する

  • entities/配下のテーブル全てをincludeしたER図用のファイルを.puml作成する
  • 作成したファイルはer/配下に置く
  • VSCodeの拡張で生成したpngファイルも同階層に置く
サンプル
er.puml
@startuml er

skinparam linetype ortho

!include ../entities/sample1.puml
!include ../entities/sample2.puml
!include ../entities/sample3.puml
!include ../entities/sample4.puml

'長いので省略

サンプル１ |o----o{ サンプル2
サンプル2 }|----o{ サンプル3

'長いので省略

@enduml

メリット

  • テーブルの定義情報の変更がER図側に勝手に反映される
    • Excelだとそれぞれ更新する必要がありますが、その手間がないです
  • 描いた絵の修正の時間が比較的少ない
    • テーブル名同士を|o----o{など線で繋ぐだけなので、図をずらしていい感じに並べるといった手間がないです
    • draw.ioも便利ですが線や図形の重なりを気にしながら書くのはそれなりに大変です
  • レビューしやすい
    • 例えばdraw.ioなどで画像ファイル作ったとした場合、図が大きく複雑になるほど差分を目視だけで確認するのは大変ですし、結局キャプチャ撮って矢印で「ここ修正しました」などコメントする必要がありますが、PlantUMLなら数行確認すればOKなのが楽でした

デメリット

  • 図の微調整が面倒
    • 「なんでそっちに矢印伸びるの？」「右上スペースめっちゃあるのに何故そこに表示する？？」「図形同士がめっちゃ離れた...」ってことが結構起きます

まとめ

いろいろ書きましたが、結構慣れが必要なので最初は時間かかりますし、プロジェクトの規模的にマッチしない可能性も全然あります。ただ、なるべくメンテ（のための作業）をしたくない人にはおすすめなのでぜひ。

（おまけ） Error: 403 Forbidden ...

症状

  • VSCodeでPlantUMLを使ってer図を書いていたとき、なぜか403エラーが出てしまった
  • includeする数を減らしたり、小さい単位に分割したりするとレンダリングできる時がある
  • 以下の記事を確認してみたが上手くいかなかった

https://qiita.com/zonbitamago/items/7946acfb4cbaa139f00a

どうやらPlantUMLのAPIに文字数制限があるっぽい

https://stackoverflow.com/questions/75986606/plantuml-plug-in-for-vsc-on-mac-returns-403-when-option-d-render-is-selected

解決策

  1. setting.jsonにplantuml.commandArgsを追加する
    ※参考にした記事と同じ
"plantuml.commandArgs": ["-Xmx2g", "-DPLANTUML_LIMIT_SIZE=16384"]
  1. PlantUML:Render で Local を指定する
    ※参考にした記事と異なる

NCDCエンジニアブログ
NCDCエンジニアブログ

NCDC株式会社( ncdc.co.jp/ )のエンジニアチームです。 募集中のエンジニアのポジションや、採用している技術スタックの紹介などはこちら( github.com/ncdcdev/recruitment )をご覧ください！ ※エンジニア以外も記事を投稿することがあります

Discussion