UML図とMermaid記法 — 図はすぐ嘘になる

UML図とMermaid記法。テキストの書類と図形のカード、コードを表示したノートパソコン。

私は VM(Ubuntu Server)の中でやりました。コマンド例は VM の中の Linux のものです。 Windows の PowerShell でやる場合、mkdir と node はそのまま動きますが、 ~ は $HOME に、rm -rf は Remove-Item -Recurse -Force に読み替えてください。 VM の立て方は VMを29台溜めた話 — Ubuntu Serverの立て方 にあります。

前回: デザインパターンとDI — テストが書けないのは設計のせい

これは【深掘り】の記事です。本線の順路ではありません。 このシリーズは言葉を覚える回にしません。 全部、手元で書いて、走らせて、結果を出します。 飛ばしても本線は進めます。 本線側の「何を作るか決める」話は 作らないものリストを先に書く — 個人開発の題材選び にあります。

この記事は、VMの中でも Windows でも構いません。 やることは図を書くことと、短い JavaScript を走らせることだけです。 テキストエディタと Node.js があれば足ります。作図ツールは1つも入れません。


設計図を描きました。3週間後、それは嘘になっていました。

個人開発で、注文まわりの処理を作っていたときの話です。状態がややこしくて、頭の中だけでは追えなくなりました。 そこで作図ツールを立ち上げて、状態の遷移図を描きました。きれいに描けました。 PNG で書き出して、 リポジトリの docs/ に置きました。満足しました。

そのあと、機能を足しました。「キャンセルはいつでもできるようにして」と自分で決めて、cancel の処理を1行足しました。 図は直しませんでした。 ツールを開き直して、線を引き直して、書き出して、差し替える。その手間が惜しかったからです。

3週間後、返金の処理を足そうとして、その PNG を開きました。

図には「支払い済み → キャンセル」の線が引かれていませんでした。 でもコードは、支払い済みからでもキャンセルできました。 私は図を信じて15分考え、そのあとコードを読んで、図が嘘だったことに気づきました。

このとき私が学んだのは「図を描くのは無駄だ」ではありません。逆でした。

問題は「図を描いたこと」ではなく、「図を、直すのが面倒な形で描いたこと」です。

そしてもう1つ。当時の私は「1人開発なんだから図は要らない」と思っていました。これも違いました。

3か月後の自分は、他人です。 自分が書いたコードなのに、なぜその判断をしたのかが分かりません。 コードには「どうやるか」しか書いていないからです。「なぜそうしたか」と「全体の形」はコードに書けません。

この記事では、その2つを同時に解きます。

  • 図をテキストで書く。だから Git で差分が見えて、コードと同じコミットで直せる
  • 図をコードと突き合わせる。ずれたらテストが落ちる。だから腐らない

UML の記法を網羅する記事にはしません。 UML には14種類の図があります(UML 2.5 時点)。全部覚える必要はありません。 実際に描くのは3つです。残りは読めれば十分です。その線引きまで、最後に表にします。


対象レベル: 中級〜上級 / 区分: 発展

目次

この記事でわかること

  • コードには「どうやるか」しか書いていない。「なぜそうしたか」と「全体の形」は、コードの外にしか置けない
  • 1人開発でも図は要る。3か月後の自分は他人だから。他人に説明するために描くのではなく、未来の自分が読むために描く
  • 画像で描いた図は必ず腐る。 直すのが面倒だから直されず、嘘になっても誰も気づかない
  • 対策は1つしかない。テキストで書いて、コードと同じリポジトリに置いて、Gitで差分を見る
  • UMLは13種類あるが、実際に描くのは3つ(クラス図・シーケンス図・ER図)で9割。残りは読めれば足りる
  • クラス図で一番の情報は「線の種類」ではなく「多重度」。1対多か多対多かで、テーブルの数が変わる
  • 多対多には中間テーブルが要る。 これは設計の好みではなく、リレーショナルモデルの制約
  • ステートマシン図は、そのまま状態遷移表としてコードに落とせる。 そしてテストにできる
  • 図がテストになれば、図は腐らない。 ずれた瞬間に CI が落ちるから
  • 全部のクラスを描くのは間違い。 描くのは自分が迷ったところだけ

この記事でやること

  1. 作業場所 ~/cslab/uml を作り、図を1つも画像にしないと決める
  2. クラス図を、アスキー図と Mermaid 記法の両方で書く。関連・集約・コンポジション・継承の線を見分ける
  3. シーケンス図で、ログイン処理の「誰が誰を、どの順で呼ぶか」を縦に描く
  4. ER図を4テーブルで書き、CREATE TABLE を Node.js に読ませて関係と中間テーブルを機械で出す
  5. ユースケース図・アクティビティ図・ステートマシン図を、1つずつ小さな例で描いて「読める」ようにする
  6. 山場: ステートマシン図を状態遷移表としてコードに落とし、node --test で図と実装を突き合わせる
  7. わざと図とずれた実装を用意し、テストが6箇所のずれを名指しで出すところまで確かめる
  8. どの場面でどの図を描くかの判断表を作り、作業場所を消す

先に知る言葉

基本的な言葉は用語集にもまとめてあります。

言葉1〜2行の意味
UMLUnified Modeling Language。ソフトウェアの構造や動きを図で書くための記法の集まり。13種類あるが、全部覚える必要はない
クラス図どんな「もの」があって、互いにどう繋がっているかの図。データの形を考えるときに使う
シーケンス図誰が誰を、どの順番で呼ぶかを、縦の時間軸で描いた図。処理の流れを追うときに使う
ER図Entity-Relationship図。データベースの表と、表どうしの繋がりを描いた図。クラス図のデータベース版
多重度「1つの投稿にコメントは0個以上」のような個数の関係。1、0..1、1..*、* などで書く
中間テーブル多対多の関係を表すために、間に挟む表。post_tags のように2つの外部キーだけを持つ
ステートマシン図ものが取りうる状態と、状態から状態への移り方を描いた図。注文の状態が典型例
Mermaid図をテキストで書くための記法。GitHub の Markdown や VS Code で、そのまま図として表示される
集約「持っている」が、片方が消えてももう片方は残る関係。学科と学生など
コンポジション「持っている」が、親が消えたら子も消える関係。注文と注文明細など

この記事では、Mermaid の記法で書いたコードブロックを「ソースの提示」として出します。 このサイトには Mermaid を絵に変換する仕組みが入っていないので、画面上ではテキストのまま見えます。 その代わり、同じ図をアスキー図(+--+ と | で描いた図)でも必ず併記します。 サイト上ではアスキー図のほうを見てください。Mermaid のブロックは、あなたの手元の VS Code や GitHub に貼ると図になります。


① なぜ図が要るのか — コードには書けないものが2つある

まず作業場所を作ります。

bash
$ mkdir -p ~/cslab/uml
$ cd ~/cslab/uml
$ pwd
/home/ユーザー名/cslab/uml

Node.js のバージョンを確かめておきます。⑦で node --test を使うので、18以上が要ります。

bash
$ node -v
v22.14.0

node: command not found と出たら、Node.js が入っていません。 Ubuntu なら sudo apt install nodejs で入りますが、バージョンが古いことがあります。 18未満だと node --test がありません。 その場合は公式サイトの手順で入れ直してください。

コードは「どうやるか」しか書いていない

次のコードを見てください。何をしているかは分かります。

if (order.status === 'paid') {
  order.status = 'shipped';
  await sendMail(order.userId, 'shipped');
}

分かるのは「支払い済みなら発送済みにしてメールを送る」までです。分からないのは次の3つです。

  • 注文の状態は、全部でいくつあるのか
  • 支払い済みから発送済み以外へは行けるのか
  • キャンセルはどこからできるのか

これは、コードを全部読めば分かります。でも「全部読めば分かる」は、分からないのと同じです。 50ファイルに散った if (order.status === ...) を全部集めて、頭の中で図に組み直す作業を、毎回やることになります。

コードに書けないものは2つあります。 1つ目は「なぜそうしたか」。if (order.status === 'paid') に「なぜ pending を弾くのか」は書けません。 2つ目は「全体の形」。1つの関数は1つの点で、点をいくら並べても地図にはなりません。

1人開発でも図が要る理由

「チーム開発なら図が要る。1人なら要らない」——これが私の誤解でした。

図は他人に説明するためだけのものではありません。未来の自分に説明するためのものです。

3か月後の自分は、他人です。 判断した理由を覚えていません。むしろ他人より悪いです。 他人なら「分からないから聞こう」となりますが、自分だと「分かっているはず」と思い込んで、間違った前提で直します。

私は実際にやりました。3か月前の自分が書いた「支払い済みからキャンセル可」を、仕様だと思い込んでその上に返金処理を足しました。 本当は、当時の私が深く考えずに足した1行でした。

図が効くのは「迷ったところ」だけ

ただし、全部を図にするのは間違いです。

私は一度、アプリの全クラスをクラス図に描いたことがあります。40個くらい並びました。 線が交差して読めませんでした。 そして2週間で嘘になりました。

描くのは、自分が迷ったところだけです。 「ここの繋がりが頭に入らない」「この順番が毎回分からなくなる」——そこだけ描く。 迷わなかったところを描いても、読み返さないので、腐るだけです。


② 図が腐る問題を、先に潰す

図の話をする前に、腐らせない仕組みを先に決めます。ここを後回しにすると、①で書いたことの繰り返しになります。

画像で描いた図は、必ず嘘になる

理由は1つです。直すのが面倒だから。

直す手間画像で描いた図テキストで書いた図
開く作図ツールを起動するエディタで開く(コードと同じ)
直す線を引き直す・位置を整える1行書き換える
保存書き出して差し替える保存するだけ
レビュー差分が見えない(画像なので)差分が行単位で見える
コードと一緒に直す別作業になる同じコミットに入る

一番効くのは最後の2行です。

画像だと、git diff に出るのは「バイナリファイルが変わりました」だけです。 何が変わったか誰にも分かりません。 だからレビューされず、直っているかも確認されません。

テキストなら、こうなります。

   pending --> paid: 支払い
   pending --> cancelled: キャンセル
   paid --> shipped: 発送
+  paid --> refunded: 返金
-  paid --> cancelled: キャンセル

「支払い済みからのキャンセルをやめて、返金にした」が、この5行で伝わります。 Git の使い方は GitとGitHubは別物 — VMのコードを初めて上げる にあります。

Mermaid は、GitHub の Markdown でそのまま図になる

テキストで図を書く記法はいくつかありますが、この記事では Mermaid を使います。 理由は3つです。

  1. GitHub の Markdown が、そのまま図として表示する(何も入れなくてよい)
  2. VS Code もプレビューで表示する
  3. 記法が短い。 覚えることが少ない

試してみます。~/cslab/uml/README.md を、エディタで作ります。

bash
$ cd ~/cslab/uml
$ touch README.md

ここだけは cat のヒアドキュメントで作りません。 中にバッククォート3つのコードブロックが入るので、シェルに貼ると途中で切れるからです。 VS Code から VM のファイルを開く方法は nanoで書き続けるのは無理 — VS CodeからVMを直接編集する にあります。

README.md の中身は、こうします。

  1. 1行目に # 設計メモ
  2. 次に ## 注文の状態
  3. その下に、バッククォート3つ + mermaid で始まり、バッククォート3つで終わるブロックを作る
  4. そのブロックの中に、次の6行をそのまま入れる
stateDiagram-v2
    [*] --> pending
    pending --> paid: 支払い
    pending --> cancelled: キャンセル
    paid --> shipped: 発送
    paid --> refunded: 返金
    shipped --> delivered: 配達完了

このファイルを GitHub に push すると、その部分が図として表示されます。 表示されない場合、コードブロックの言語指定が mermaid になっているかを見てください。text や空だと、テキストのまま出ます。

そして、このサイト(obmes.com)には Mermaid のレンダラが入っていません。 なので、この記事では必ずアスキー図も併記します。 上の図をアスキーで書くと、こうです。

              [開始]
                |
                v
           +----------+
           | pending  |  受付済み
           +----------+
             |      |
     支払い  |      |  キャンセル
             v      v
        +--------+  +-----------+
        |  paid  |  | cancelled |
        +--------+  +-----------+
          |    |
    発送  |    |  返金
          v    v
   +---------+ +----------+
   | shipped | | refunded |
   +---------+ +----------+
        |
  配達  |
        v
  +-----------+
  | delivered |
  +-----------+

アスキー図は「等幅フォントで見ることが前提」です。 ブラウザで崩れて見える場合、 コードブロックの中に入っているかを確認してください。本文にそのまま書くと崩れます。

ここで決めておくこと

この記事の最後まで、次のルールで進めます。

1. 図は必ずテキストで書く。 画像は1枚も作らない 2. 図はコードと同じリポジトリに置く。 docs/ でも README.md でもよい 3. 図とコードがずれたら、テストが落ちるようにする(⑦でやります)

3番目が本命です。1と2だけだと、「直しやすいが、直し忘れる」に留まります。


③ クラス図 — 一番使う。だが全部のクラスを描いてはいけない

まず、何を描くのか

クラス図は「どんなものがあって、互いにどう繋がっているか」の図です。

クラス図で一番の情報は、線の種類ではありません。多重度(個数の関係)です。

私は最初、線の種類(白菱形か黒菱形か)を必死に覚えました。現場でほとんど役に立ちませんでした。 役に立ったのは、「1対多か、多対多か」だけでした。ここを間違えると、テーブルの数が変わるからです。

多重度の書き方

書き方意味例
1ちょうど1つ注文には利用者が1人
0..10個か1個利用者にプロフィール画像は無いかもしれない
1..*1個以上注文には明細が最低1行は要る
* または 0..*0個以上投稿にコメントは0個でもよい
2..52個以上5個以下対戦は2〜5人

1..* と * の差は、設計上とても大きいです。 1..*(1個以上)なら、明細が0行の注文を作れないようにコードで弾く必要があります。 * なら、0行の注文はありえます。図に書いてあれば、この判断が1秒で終わります。

線の4種類

~/cslab/uml/class.md に、線の意味を書き出します。

線呼び方意味消えるとき
ただの線関連互いを知っている片方を消しても、もう片方は残る
白い菱形集約「持っている」が、部品は独立している親が消えても子は残る
黒い菱形コンポジション「持っている」が、部品は親のもの親が消えたら子も消える
白い三角継承(汎化)「〜の一種である」別の話(消える消えないの話ではない)

集約とコンポジションの見分け方は1つだけです。「親を消したとき、子はどうなるか」。

  • 集約: 学科と学生。学科が廃止されても、学生は他の学科へ移れる。学生は残る
  • コンポジション: 注文と注文明細。注文を消したら、その明細だけが残っていても意味がない。一緒に消える

これはデータベースの外部キーで ON DELETE CASCADE を付けるかどうか、そのものです。 外部キーと制約の話は アプリで弾いたはずの値が入る — SQL深掘り にあります。

アスキー図で描く

線の種類を、絵で見分けられるようにします。菱形と三角を、文字で描きます。

【関連】互いを知っているだけ

   +---------+   1        *   +---------+
   |  User   |----------------|  Post   |
   +---------+                +---------+

   「1人の利用者は、0個以上の投稿を持つ」
   投稿を消しても利用者は残る。利用者を消しても(消し方次第で)投稿は残せる


【集約】持っているが、部品は独立している

   +-----------+         *   +----------+
   |  Team     |<>------------|  Member  |
   +-----------+              +----------+
                ^
                |
          白い菱形(<>)= 集約
   「チームを解散しても、メンバーは会社に残る」


【コンポジション】親が消えたら子も消える

   +-----------+        1..*  +--------------+
   |  Order    |<#>-----------|  OrderLine   |
   +-----------+              +--------------+
                ^
                |
          黒い菱形(<#>)= コンポジション
   「注文を消したら、その明細も消える」
   多重度が 1..* なので「明細0行の注文」は作れない


【継承】〜の一種である

            +-------------+
            |   Payment   |   (抽象)
            +-------------+
                   /_\        白い三角
                    |
        +-----------+-----------+
        |                       |
 +-------------+        +---------------+
 | CardPayment |        | BankTransfer  |
 +-------------+        +---------------+

   「カード払いも銀行振込も、支払いの一種」

<> と <#> は Mermaid の記法ではありません。 アスキーで菱形の塗りを表すために、この記事で決めた書き方です。 本物の UML では、白い菱形と黒い菱形で描き分けます。

同じものを Mermaid で書く

~/cslab/uml/class.md に貼ります。GitHub や VS Code では、これが図になります。

classDiagram
    class User {
        +int id
        +string name
        +string email
    }
    class Post {
        +int id
        +string title
        +publish()
    }
    class Order
    class OrderLine
    class Team
    class Member
    class Payment
    class CardPayment
    class BankTransfer

    User "1" --> "*" Post : 関連
    Team "1" o-- "*" Member : 集約
    Order "1" *-- "1..*" OrderLine : コンポジション
    Payment <|-- CardPayment
    Payment <|-- BankTransfer

記号の対応はこうです。

Mermaid意味
--> または --関連
o--集約(白い菱形)
*--コンポジション(黒い菱形)
<|--継承(白い三角)

"1" --> "*" の引用符の中が多重度です。 ここを書かない図をよく見ますが、一番の情報を捨てています。

全部のクラスを描いてはいけない

ここが本題です。上の図には8個のクラスが出てきました。実際のアプリには何十個もあります。

全部描くと、線が交差して読めなくなります。 そして2週間で嘘になります。

描くのは、自分が迷ったところだけです。 具体的には、次のどれかに当てはまるところです。

  1. 多重度が思い出せない(1対多だったか、多対多だったか)
  2. 消したときにどうなるか決めていない(親を消したら子はどうなる)
  3. 同じような名前のクラスが3つ以上ある(User / Account / Profile など)

逆に、1本道の関係は描かなくてよいです。Controller → Service → Repository のような、 毎回同じ形になるところを図にしても、読み返しません。

📸 スクリーンショット①: ~/cslab/uml/class.md を VS Code で開いて、Mermaid のプレビューが右に出ている画面。 左のテキストと右の図が並んでいるところを撮る。「テキストを直すと図が直る」が一目で分かる並びにする。


④ シーケンス図 — 誰が誰を、どの順で呼ぶか

2番目によく使う

シーケンス図は「誰が誰を、どの順番で呼ぶか」の図です。縦が時間です。上から下へ流れます。

非同期の処理を説明するとき、これ以上のものがありません。

「リクエストを返したあとにメールを送っている」「片方の返事を待たずに次を呼んでいる」—— こういう話は、文章で書くと必ず誤解されます。縦の線で描くと、一発で伝わります。

ログイン処理を描く

ログインを例にします。ブラウザ・APIサーバー・データベース・セッションストアの4者が出てきます。

 ブラウザ        APIサーバー        DB          セッション置き場
   |                 |               |                |
   |  POST /login    |               |                |
   |---------------->|               |                |
   |                 |  利用者を検索  |                |
   |                 |-------------->|                |
   |                 |               |                |
   |                 |  行 or 無し    |                |
   |                 |<--------------|                |
   |                 |                                |
   |                 | [無い or 不一致]               |
   |   401 を返す     |                                |
   |<----------------|                                |
   |                 |                                |
   |                 | [一致した]                     |
   |                 |  セッションIDを保存             |
   |                 |------------------------------->|
   |                 |                                |
   |                 |  OK                            |
   |                 |<-------------------------------|
   |  200 + Cookie   |                                |
   |<----------------|                                |
   |                 |                                |
   |                 |- - ->  ログイン通知メール(非同期)
   |                 |        返事を待たない
   |                 |

この図から読み取れることが3つあります。

  1. パスワードの照合は DB では行わず、APIサーバーの中でやっている(DB は行を返しているだけ)
  2. セッションIDの保存が成功してから 200 を返している(先に返していない)
  3. メールは返事を待っていない(点線の矢印。ここが非同期)

3番目が、文章では絶対に伝わらない部分です。 「メールも送ります」と書くと、読んだ人は「メールの送信が失敗したらログインも失敗する」と思います。 この図なら、そうではないと分かります。

パスワードとセッションの中身は パスワードは保存しない — セッションとJWT にあります。

同じものを Mermaid で

sequenceDiagram
    participant B as ブラウザ
    participant A as APIサーバー
    participant D as DB
    participant S as セッション置き場

    B->>A: POST /login
    A->>D: 利用者を検索
    D-->>A: 行 or 無し
    alt 見つからない or 不一致
        A-->>B: 401
    else 一致した
        A->>S: セッションIDを保存
        S-->>A: OK
        A-->>B: 200 + Set-Cookie
        A->>A: ログイン通知メールを予約
        Note right of A: 返事を待たない(非同期)
    end

記号はこれだけ覚えれば書けます。

Mermaid意味
->>呼び出し(実線の矢印)
-->>返り値(点線の矢印)
alt / else / end分岐
loop / end繰り返し
Note right of X注釈

描くときのコツ

私が失敗して学んだことです。

  • 登場人物は5つまで。 6つ目が出たら、図を2枚に割る。横に広がると読めなくなる
  • クラス名ではなく、役割で書く。 UserServiceImpl ではなく APIサーバー。実装を変えても図が生きる
  • 正常系だけ描かない。 401 のような失敗の分岐を1本は入れる。そこが一番忘れるところ
  • 返り値の矢印を省かない。 「呼んだ」だけ描くと、待っているのか待っていないのかが消える

⑤ ER図 — DBを設計するなら必須

クラス図のデータベース版

ER図は「どんな表があって、表どうしがどう繋がっているか」の図です。 クラス図と似ていますが、メソッドが無く、外部キーがあるのが違いです。

データベースを作るなら、これは省けません。 理由は、多対多の関係は、表2つでは表せないからです。ここを図で確認しないと、必ず作り直しになります。

4テーブルで描く

「利用者」「投稿」「タグ」「コメント」で描きます。

   +----------------+
   |     users      |
   |----------------|
   | id (PK)        |
   | name           |
   | email (UNIQUE) |
   +----------------+
        |1        |1
        |         |
        |*        |
        |     +---------------------+
        |     |     comments        |
        |     |---------------------|
        |     | id (PK)             |
        |     | post_id (FK)        |
        |     | user_id (FK)        |
        |     | body                |
        |     +---------------------+
        |                |*
        |*               |
   +----------------+    |1
   |     posts      |----+
   |----------------|
   | id (PK)        |
   | user_id (FK)   |
   | title          |
   | body           |
   +----------------+
        |1
        |
        |*
   +----------------------+
   |     post_tags        |   ← 中間テーブル
   |----------------------|
   | post_id (PK, FK)     |
   | tag_id  (PK, FK)     |
   +----------------------+
        |*
        |
        |1
   +----------------+
   |     tags       |
   |----------------|
   | id (PK)        |
   | name (UNIQUE)  |
   +----------------+

読み方はこうです。

関係多重度意味
users — posts1 対 多1人が複数の投稿を書く。1つの投稿は1人のもの
users — comments1 対 多1人が複数のコメントを書く
posts — comments1 対 多1つの投稿に複数のコメントが付く
posts — tags多 対 多1つの投稿に複数のタグ。1つのタグは複数の投稿に付く

最後の行だけが「多対多」です。ここに中間テーブルが要ります。

なぜ多対多に中間テーブルが要るのか

posts に tag_id を1本持たせれば済む、と思うかもしれません。タグが1個しか付けられません。

では tag_id1, tag_id2, tag_id3 と3本持たせる。4個目のタグが付いた瞬間に破綻します。 そして「タグAが付いた投稿を全部出す」というSQLが、3本ぜんぶを OR で見る形になります。

1つのセルに複数の値を入れられない、これがリレーショナルモデルの前提です。 だから多対多は、行を増やす方向でしか表せません。それが中間テーブルです。

正規化の話は 1つの表に全部入れると壊れる — テーブル設計と正規化 にあります。

中間テーブルの中身を、実際の行で見るとこうです。

posts                    post_tags                  tags
+----+----------+        +---------+--------+       +----+--------+
| id | title    |        | post_id | tag_id |       | id | name   |
+----+----------+        +---------+--------+       +----+--------+
|  1 | Linux入門 |        |    1    |   10   |       | 10 | linux  |
|  2 | SQL入門   |        |    1    |   11   |       | 11 | 初心者  |
+----+----------+        |    2    |   11   |       | 12 | docker |
                         |    2    |   12   |       +----+--------+
                         +---------+--------+

投稿1 には linux と 初心者 の2つ
投稿2 には 初心者 と docker の2つ
タグ「初心者」は投稿1と投稿2の両方に付いている

行が4行あります。「投稿2つ × タグの付き方」がそのまま行数になっています。

Mermaid の ER図記法

erDiagram
    users {
        int id PK
        string name
        string email UK
    }
    posts {
        int id PK
        int user_id FK
        string title
        text body
    }
    comments {
        int id PK
        int post_id FK
        int user_id FK
        text body
    }
    tags {
        int id PK
        string name UK
    }
    post_tags {
        int post_id PK "FK"
        int tag_id PK "FK"
    }

    users ||--o{ posts : "書く"
    users ||--o{ comments : "書く"
    posts ||--o{ comments : "付く"
    posts ||--o{ post_tags : ""
    tags  ||--o{ post_tags : ""

記号(カラスの足記法)はこうです。

Mermaid意味
||ちょうど1
o|0個か1個
}o0個以上
}|1個以上

users ||--o{ posts は「利用者ちょうど1人に対して、投稿は0個以上」と読みます。

CREATE TABLE を書いて、図と突き合わせる

ここから手を動かします。 図を SQL に落とします。

bash
$ cd ~/cslab/uml

schema.sql を作ります。

CREATE TABLE users (
  id       INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name     VARCHAR(50)  NOT NULL,
  email    VARCHAR(255) NOT NULL UNIQUE
);

CREATE TABLE posts (
  id        INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  user_id   INT UNSIGNED NOT NULL,
  title     VARCHAR(120) NOT NULL,
  body      TEXT         NOT NULL,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE TABLE comments (
  id       INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  post_id  INT UNSIGNED NOT NULL,
  user_id  INT UNSIGNED NOT NULL,
  body     TEXT         NOT NULL,
  FOREIGN KEY (post_id) REFERENCES posts(id),
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE TABLE tags (
  id   INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(40) NOT NULL UNIQUE
);

CREATE TABLE post_tags (
  post_id INT UNSIGNED NOT NULL,
  tag_id  INT UNSIGNED NOT NULL,
  PRIMARY KEY (post_id, tag_id),
  FOREIGN KEY (post_id) REFERENCES posts(id),
  FOREIGN KEY (tag_id)  REFERENCES tags(id)
);

post_tags に id がありません。 主キーが (post_id, tag_id) の2列です。 こうすると「同じ投稿に同じタグを2回付ける」がデータベース側で弾かれます。図の「多対多」がそのまま制約になっています。

MySQL があれば、そのまま流せます。入っていなければ次に進んで構いません(次のステップは DB 無しで動きます)。

bash
$ mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS uml_demo;"
$ mysql -u root -p uml_demo < schema.sql

MySQL の入れ方は プロセスを止めても消えない場所 — MySQLとSQLの基本 にあります。

SQL から関係を機械で出す

DB が無くてもできることがあります。 CREATE TABLE を読んで、関係を抜き出します。

er-from-sql.mjs を作ります。

import { readFileSync } from 'node:fs';
const sql = readFileSync('schema.sql', 'utf8');

const tables = [...sql.matchAll(/CREATE TABLE (\w+)\s*\(([\s\S]*?)\n\);/g)]
  .map(([, name, body]) => ({ name, body }));

const FK = /FOREIGN KEY \((\w+)\)\s+REFERENCES (\w+)\((\w+)\)/g;
const edges = [];
for (const t of tables) {
  for (const m of t.body.matchAll(FK)) {
    edges.push({ from: t.name, col: m[1], to: m[2] });
  }
}

console.log('テーブル:', tables.map((t) => t.name).join(', '));
console.log('');
for (const e of edges) console.log(`  ${e.from}.${e.col}  ->  ${e.to}.id   (多 -> 1)`);
console.log('');

// 中間テーブル = 主キーが「2本の外部キーだけ」でできている表
for (const t of tables) {
  const pk = t.body.match(/PRIMARY KEY \(([^)]+)\)/);
  const cols = pk ? pk[1].split(',').map((s) => s.trim()) : [];
  const fks = edges.filter((e) => e.from === t.name).map((e) => e.col);
  if (cols.length === 2 && cols.every((c) => fks.includes(c))) {
    const [a, b] = cols.map((c) => edges.find((e) => e.from === t.name && e.col === c).to);
    console.log(`中間テーブル: ${t.name}  =>  ${a} 多対多 ${b}`);
  }
}

走らせます。

bash
$ node er-from-sql.mjs
テーブル: users, posts, comments, tags, post_tags

  posts.user_id  ->  users.id   (多 -> 1)
  comments.post_id  ->  posts.id   (多 -> 1)
  comments.user_id  ->  users.id   (多 -> 1)
  post_tags.post_id  ->  posts.id   (多 -> 1)
  post_tags.tag_id  ->  tags.id   (多 -> 1)

中間テーブル: post_tags  =>  posts 多対多 tags

5本の1対多と、1本の多対多が出ました。 手で描いたER図と一致しています。

ここが大事です。 この出力は schema.sql から作られています。 SQL を変えれば出力が変わります。 つまり、図が SQL に追従します。

逆はできません。 図を変えても SQL は変わりません。だから、 正は SQL 側に置いて、図はそこから作る——これが「腐らせない」ための基本の向きです。

📸 スクリーンショット②: node er-from-sql.mjs の出力全体。 中間テーブル: post_tags => posts 多対多 tags の行が見えているところを撮る。 上のアスキーER図と並べて「図が機械で確かめられた」と分かる形にする。


⑥ 残りの3つは「読めればよい」

ここまでの3つ(クラス図・シーケンス図・ER図)が、実際に描く図です。 残りは、人が描いたものを読めれば足ります。 1つずつ、小さな例だけ見ます。

ユースケース図 — 企画の初期だけ

「誰が、何をできるか」の図です。棒人間と楕円で描きます。

        システム: ブログ
   +--------------------------------+
   |                                |
   |    ( 記事を読む )               |
   |         ^        ^             |
   |         |        |             |
   |    ( 記事を書く ) |             |
   |         ^        |             |
   |         |        |             |
   |    ( 記事を消す ) |             |
   |         ^        |             |
   +---------|--------|-------------+
             |        |
            _|_      _|_
             O        O
            /|\      /|\      <- 棒人間(アクター)
            / \      / \
          筆者      読者

読み方: 読者は「読む」だけ。筆者は「読む・書く・消す」ができる。

これが役に立つのは、企画の初期だけです。

「誰が使うのか」「その人は何をするのか」を洗い出す段階では、驚くほど効きます。 書き出してみると「管理者」を忘れていることに気づいたりします。

一方、実装に入ってからは使いません。この図は権限の設計には足りないからです。 「自分の記事だけ消せる」のような条件が、この図には書けません。

アクティビティ図 — 分岐が多い業務ロジック

フローチャートです。分岐が3つ以上ある処理を整理するときに使います。

        (開始)
          |
          v
   [ 注文を受け取る ]
          |
          v
       <在庫あり?>
        /       \
     いいえ     はい
      /            \
     v              v
[ 取り寄せる ]   [ 引き当てる ]
     |              |
     +------>+<-----+
             |
             v
        <金額 >= 5000?>
          /       \
       はい      いいえ
        /           \
       v             v
[ 送料無料 ]    [ 送料500円 ]
       |             |
       +----->+<-----+
              |
              v
        [ 請求額を確定 ]
              |
              v
           (終了)

これはコードで書いたほうが早いことが多いです。 使いどころは、まだコードにしていない業務ルールを、人と確認するときです。 「5000円ちょうどはどっち?」のような境界の質問が、この図を見せると出てきます。

私の経験では、境界値の抜けは、図を見せた瞬間に見つかります。 コードレビューでは見つかりません。

ステートマシン図 — 注文の状態遷移が一番の実例

「ものが取りうる状態」と「状態から状態への移り方」の図です。

この記事で一番大事な図です。 ⑦でコードに落とします。

②で出した図を、もう一度置きます。

              [開始]
                |
                v
           +----------+
           | pending  |  受付済み
           +----------+
             |      |
     支払い  |      |  キャンセル
             v      v
        +--------+  +-----------+
        |  paid  |  | cancelled | [終わり]
        +--------+  +-----------+
          |    |
    発送  |    |  返金
          v    v
   +---------+ +----------+
   | shipped | | refunded | [終わり]
   +---------+ +----------+
        |
  配達  |
        v
  +-----------+
  | delivered | [終わり]
  +-----------+

この図が答えている質問は、たとえばこれです。

「支払い済みからキャンセルへ行けるか?」

行けません。 図に線がないからです。支払い済みのあとに取り消したいなら、返金(refunded)を通します。

これは技術の話ではなく、業務の話です。 「支払い済みをキャンセルにしてしまうと、返金の記録が残らない」——だから分けています。 その判断を、この1枚が持っています。 コードのどこにも書けません。

そして⑦でやりますが、この図はそのままコードにできます。 そこが他の図と決定的に違うところです。


⑦ 描いた図を、コードと突き合わせる

図を「表」に落とす

ステートマシン図は、「今の状態 → 行ってよい次の状態」の表そのものです。 だから、そのまま JavaScript のオブジェクトになります。

~/cslab/uml/order-state.mjs を作ります。

// 図(ステートマシン図)を、そのまま表にしたもの。
// キーが「今の状態」、値が「行ってよい次の状態」。
export const TRANSITIONS = {
  pending:   ['paid', 'cancelled'],
  paid:      ['shipped', 'refunded'],
  shipped:   ['delivered'],
  delivered: [],
  cancelled: [],
  refunded:  [],
};

export const STATES = Object.keys(TRANSITIONS);

export function canTransit(from, to) {
  const next = TRANSITIONS[from];
  if (!next) throw new Error(`未知の状態: ${from}`);
  return next.includes(to);
}

export function transit(from, to) {
  if (!canTransit(from, to)) {
    throw new Error(`${from} から ${to} へは行けません`);
  }
  return to;
}

export function terminalStates() {
  return STATES.filter((s) => TRANSITIONS[s].length === 0);
}

TRANSITIONS の中身と、⑥のアスキー図の矢印は、1本ずつ対応しています。 数えてください。

  • pending から2本(paid / cancelled)
  • paid から2本(shipped / refunded)
  • shipped から1本(delivered)
  • 残り3つは0本(終わりの状態)

合計5本。図の矢印も5本です。

表を目で見えるようにする

table.mjs を作ります。

import { STATES, TRANSITIONS, canTransit } from './order-state.mjs';
const w = Math.max(...STATES.map((s) => s.length), 9);
const pad = (s) => s.padEnd(w, ' ');
console.log(pad('from / to') + ' | ' + STATES.map(pad).join(' | '));
console.log('-'.repeat(w) + '-+-' + STATES.map(() => '-'.repeat(w)).join('-+-'));
for (const from of STATES) {
  const cells = STATES.map((to) => pad(canTransit(from, to) ? 'OK' : '.'));
  console.log(pad(from) + ' | ' + cells.join(' | '));
}
console.log('');
console.log('矢印の数:', Object.values(TRANSITIONS).flat().length);
console.log('組み合わせの数:', STATES.length * STATES.length);
console.log('終わりの状態:', STATES.filter((s) => TRANSITIONS[s].length === 0).join(', '));

走らせます。

bash
$ node table.mjs
from / to | pending   | paid      | shipped   | delivered | cancelled | refunded
----------+-----------+-----------+-----------+-----------+-----------+----------
pending   | .         | OK        | .         | .         | OK        | .
paid      | .         | .         | OK        | .         | .         | OK
shipped   | .         | .         | .         | OK        | .         | .
delivered | .         | .         | .         | .         | .         | .
cancelled | .         | .         | .         | .         | .         | .
refunded  | .         | .         | .         | .         | .         | .

矢印の数: 5
組み合わせの数: 36
終わりの状態: delivered, cancelled, refunded

36通りのうち、通れるのは5通りだけです。 残りの31通りは全部エラーにならなければいけません。

この「31通り」を人手で確かめるのは無理です。だからテストにします。

図から Mermaid を生成する

表があるので、図のほうを機械で作れます。 gen-diagram.mjs を作ります。

import { TRANSITIONS, STATES } from './order-state.mjs';

const LABEL = {
  paid: '支払い', shipped: '発送', delivered: '配達完了',
  cancelled: 'キャンセル', refunded: '返金',
};

console.log('stateDiagram-v2');
console.log('    [*] --> pending');
for (const [from, tos] of Object.entries(TRANSITIONS)) {
  for (const to of tos) console.log(`    ${from} --> ${to}: ${LABEL[to]}`);
}
for (const s of STATES) {
  if (TRANSITIONS[s].length === 0) console.log(`    ${s} --> [*]`);
}
bash
$ node gen-diagram.mjs
stateDiagram-v2
    [*] --> pending
    pending --> paid: 支払い
    pending --> cancelled: キャンセル
    paid --> shipped: 発送
    paid --> refunded: 返金
    shipped --> delivered: 配達完了
    delivered --> [*]
    cancelled --> [*]
    refunded --> [*]

この出力を README.md の mermaid 指定のブロックに貼れば、図とコードが絶対にずれません。 図を人が描くのをやめて、コードから作る——これが「腐らない図」の一番強い形です。

生成した図をファイルに残すには、こうします。

bash
$ node gen-diagram.mjs > order-state.mmd
$ cat order-state.mmd

テストを書く — 図がそのままテストになる

order-state.test.mjs を作ります。Node.js に組み込みのテスト機能を使うので、何も入れません。

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { TRANSITIONS, STATES, canTransit, transit, terminalStates } from './order-state.mjs';

test('図に描いた矢印は、全部通れる', () => {
  for (const [from, tos] of Object.entries(TRANSITIONS)) {
    for (const to of tos) {
      assert.equal(transit(from, to), to, `${from} -> ${to}`);
    }
  }
});

test('図に描いていない矢印は、1本も通れない', () => {
  for (const from of STATES) {
    for (const to of STATES) {
      if (TRANSITIONS[from].includes(to)) continue;
      assert.throws(() => transit(from, to), /行けません/, `${from} -> ${to}`);
    }
  }
});

test('支払い済みからキャンセルへは行けない(返金を通す)', () => {
  assert.equal(canTransit('paid', 'cancelled'), false);
  assert.equal(canTransit('paid', 'refunded'), true);
});

test('終わりの状態からは、どこへも行けない', () => {
  for (const s of terminalStates()) {
    for (const to of STATES) {
      assert.equal(canTransit(s, to), false);
    }
  }
});

test('全部の状態に、最初の状態から到達できる', () => {
  const seen = new Set(['pending']);
  const queue = ['pending'];
  while (queue.length) {
    const cur = queue.shift();
    for (const to of TRANSITIONS[cur]) {
      if (!seen.has(to)) { seen.add(to); queue.push(to); }
    }
  }
  assert.deepEqual([...seen].sort(), [...STATES].sort());
});

test('知らない状態を渡したら、黙って false にしない', () => {
  assert.throws(() => canTransit('paidd', 'shipped'), /未知の状態/);
});

走らせます。

bash
$ node --test
1..6
# tests 6
# suites 0
# pass 6
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 118.9587

6本とも通りました。

5番目のテストに注目してください。「全部の状態に、最初の状態から到達できる」。

これは図の書き間違いを見つけるテストです。状態を1つ足して矢印を引き忘れると、その状態に誰も来られません。 図を目で見ても気づきませんが、これなら落ちます。 やっていることは幅優先探索です。pending から辿れる状態を全部集めて、STATES と一致するかを見ています。

既存の実装と、図を突き合わせる

ここが山場です。すでに書いてしまったコードが、図と合っているかを調べます。

私が実際にやってしまった形の実装を用意します。legacy.mjs を作ります。

// 図を見ずに、その場その場で if を足していった実装(よくある形)
export function legacyTransit(order, action) {
  if (action === 'pay') {
    if (order.status === 'pending') { order.status = 'paid'; return order; }
  }
  if (action === 'ship') {
    if (order.status === 'paid') { order.status = 'shipped'; return order; }
  }
  if (action === 'deliver') {
    if (order.status === 'shipped') { order.status = 'delivered'; return order; }
  }
  if (action === 'cancel') {
    // 「キャンセルはいつでもできるようにして」と言われて足した1行
    order.status = 'cancelled';
    return order;
  }
  throw new Error(`できません: ${order.status} / ${action}`);
}

この cancel の中に if がありません。 どんな状態からでもキャンセルになります。 書いたときは正しいと思っていました。

図と突き合わせるテストを書きます。legacy.test.mjs です。

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { STATES, canTransit } from './order-state.mjs';
import { legacyTransit } from './legacy.mjs';

const ACTION_TO_STATE = {
  pay: 'paid', ship: 'shipped', deliver: 'delivered',
  cancel: 'cancelled', refund: 'refunded',
};

test('既存の実装が、図と一致しているか', () => {
  const diffs = [];
  for (const from of STATES) {
    for (const [action, to] of Object.entries(ACTION_TO_STATE)) {
      const allowedByDiagram = canTransit(from, to);
      let allowedByCode = false;
      try {
        const order = { status: from };
        legacyTransit(order, action);
        allowedByCode = order.status === to;
      } catch { allowedByCode = false; }
      if (allowedByDiagram !== allowedByCode) {
        diffs.push(`${from} -> ${to} : 図=${allowedByDiagram} コード=${allowedByCode}`);
      }
    }
  }
  assert.deepEqual(diffs, [], '\n' + diffs.join('\n'));
});

走らせます。

bash
$ node --test legacy.test.mjs
TAP version 13
# Subtest: 既存の実装が、図と一致しているか
not ok 1 - 既存の実装が、図と一致しているか
  ---
  duration_ms: 3.6185
  failureType: 'testCodeFailure'
  error: |-

    paid -> cancelled : 図=false コード=true
    paid -> refunded : 図=true コード=false
    shipped -> cancelled : 図=false コード=true
    delivered -> cancelled : 図=false コード=true
    cancelled -> cancelled : 図=false コード=true
    refunded -> cancelled : 図=false コード=true

6箇所のずれが、名指しで出ました。

読み解くと、こうです。

出た行意味どれくらいまずいか
paid -> cancelled : 図=false コード=true支払い済みをキャンセルできてしまう返金の記録が残らない。金の話
paid -> refunded : 図=true コード=false返金がそもそも実装されていない機能の抜け
shipped -> cancelled発送済みなのにキャンセルできる商品が出ているのに注文が消える
delivered -> cancelled配達完了をキャンセルできる同上
cancelled -> cancelled既にキャンセルなのに、また通る二重処理の入口
refunded -> cancelled返金済みをキャンセルにできる状態が上書きされる

私が3週間気づかなかったのは、この1行目です。 そして、図を PNG で持っていたときは、このテストが書けませんでした。

直す

legacy.mjs を捨てて、order-state.mjs の transit を使う形に書き直します。

// legacy2.mjs — 図(表)を正として書き直したもの
import { transit } from './order-state.mjs';

const ACTION_TO_STATE = {
  pay: 'paid', ship: 'shipped', deliver: 'delivered',
  cancel: 'cancelled', refund: 'refunded',
};

export function apply(order, action) {
  const to = ACTION_TO_STATE[action];
  if (!to) throw new Error(`知らない操作: ${action}`);
  order.status = transit(order.status, to);
  return order;
}

if が1つも要らなくなりました。 状態の判断は全部 TRANSITIONS が持っています。

そして、業務ルールを変えるときに直す場所が1箇所になりました。 「やっぱり発送済みからもキャンセルできるようにする」なら、TRANSITIONS の shipped に 'cancelled' を足すだけです。 表を直せば、コードも図(gen-diagram.mjs の出力)も、両方が同時に変わります。

確かめます。

bash
$ node -e "
  import('./legacy2.mjs').then(({ apply }) => {
    const o = { status: 'pending' };
    apply(o, 'pay');
    console.log('pay ->', o.status);
    try { apply(o, 'cancel'); } catch (e) { console.log('cancel ->', e.message); }
    apply(o, 'refund');
    console.log('refund ->', o.status);
  });
  "
pay -> paid
cancel -> paid から cancelled へは行けません
refund -> refunded

図に描いていない矢印が、実行時に止まりました。

📸 スクリーンショット③: node --test legacy.test.mjs の失敗出力で、 paid -> cancelled : 図=false コード=true の行が見えている画面。 できれば直後に node --test の # pass 6 / # fail 0 も並べて撮る。 「図とコードのずれが機械で出て、直ると緑になる」が1枚で分かる形にする。


⑧ どの場面でどの図を描くか — 判断表

ここまでで6種類を見ました。全部を同じように使うわけではありません。

図描く頻度描く場面描かない場面
クラス図高データの形が頭に入らないとき。多重度を決めるとき全クラスを網羅しようとするとき
シーケンス図高呼ぶ順番が分からなくなるとき。非同期を説明するとき1本道の呼び出し
ER図高データベースを設計するとき。多対多があるとき表が2〜3個で自明なとき
ユースケース図低企画の最初。誰が使うかを洗い出すとき実装が始まってから
アクティビティ図低分岐が3つ以上ある業務ルールを人と確認するときコードで書いたほうが早いとき
ステートマシン図中状態を持つもの(注文・申請・記事の公開状態)状態が2つしかないとき

結論はこうです。

クラス図・シーケンス図・ER図の3つで9割です。 ステートマシン図は数は少ないが、当たれば一番効きます(そのままコードとテストになるから)。 残りの2つは、人が描いたものを読めれば十分です。

そして何より、描くのは「自分が迷ったところだけ」です。

「どこに置くか」も決めておく

図をどこに置くかで、読まれるかどうかが決まります。私が落ち着いた形です。

リポジトリ/
├── README.md          <- 全体像を1枚。ここに Mermaid で1〜2図
├── docs/
│   ├── er.md          <- ER図(schema.sql から作る)
│   └── flows.md       <- シーケンス図
├── src/
│   └── order-state.mjs  <- ステートマシン図は「表」としてコードの中
└── test/
    └── order-state.test.mjs

ステートマシン図だけ、置き場所が違います。 これは「図」ではなく「コード」だからです。図はそこから生成します。

docs/ に置いた図が腐るのを完全には防げません。 防げるのは、コードに落とした分だけです。 だから、「図に書いたことを、できるだけコードに落とす」が最終的な方針になります。

  • 多重度 → 外部キーと NOT NULL(DBが守る)
  • 「一意」 → UNIQUE 制約(DBが守る)
  • 状態遷移 → 遷移表とテスト(テストが守る)
  • 呼ぶ順番 → 守らせる手段が無い。ここだけは図で持つしかない

シーケンス図が一番腐りやすい理由がこれです。機械で守れません。 だから短くして、 「非同期かどうか」など、腐っても致命的でない情報を中心に描くようにしました。


つまずいたところ

1. Mermaid のコードブロックが、GitHub では図になるのにサイトでは出なかった

同じ Markdown なのに、GitHub では図で、投稿すると文字のままでした。 Mermaid は Markdown の仕様ではなく、表示する側の機能です。 GitHub と VS Code は持っていて、WordPress は持っていません。 だからこの記事では、アスキー図を必ず併記しています。 「Markdown に書いたから図になる」ではありません。

2. アスキー図がブラウザで崩れた

+----+ で描いた枠が、本文にそのまま貼るとガタガタになりました。 等幅フォントでないと、文字ごとに幅が違うからです。 コードブロック(バッククォート3つで囲む)に入れると直りました。 そして日本語と英数字は幅が違うので、枠の中に日本語を入れると、そこだけ揃いません。 枠の中は英数字、説明は枠の外にすると崩れにくいです。

3. er-from-sql.mjs が、外部キーを1本だけ見落とした

最初の出力で post_tags.tag_id が出ませんでした。中間テーブルの判定も動きませんでした。 原因は SQL の書き方でした。

FOREIGN KEY (tag_id)  REFERENCES tags(id)

) と REFERENCES の間に空白が2つあって、正規表現の \) REFERENCES(空白ちょうど1つ)に一致していませんでした。 \)\s+REFERENCES に直したら出ました。 「4本しか出ていない」に気づけたのは、手でER図を描いて本数を数えていたからです。 図が検算になりました。

4. PRIMARY KEY (post_id, tag_id) を id に変えて、多対多が壊れた

post_tags にも id を付けたほうが素直かと思って、主キーを id にしました。 同じ投稿に同じタグを2回付けられるようになりました。 多対多の「同じ組み合わせは1つだけ」は、複合主キーが守っていました。 id を付けるなら、別に UNIQUE (post_id, tag_id) を足す必要があります。

5. ステートマシンのテストで、assert.throws が通らなかった

assert.throws(() => transit(from, to)) と書いたのに落ちました。 from に存在しない状態を入れたとき、canTransit の中で先に 未知の状態 が投げられていて、 期待していた 行けません とは別のエラーだったからです。 assert.throws の第2引数に正規表現を渡さないと、「何かが投げられた」で通ってしまいます。 エラーの中身まで確かめないと、テストが嘘をつきます。

6. legacy.test.mjs を書いたとき、最初はずれが1件しか出なかった

ACTION_TO_STATE に refund を書き忘れていました。書き忘れた分は、そもそも比較されません。 突き合わせのテストは、「比べる対象を漏らす」と静かに通ります。 今回は「6件出るはず」と先に見積もっていたので気づけました。 先に答えを見積もってから走らせるのが、この種のテストでは要ります。

7. 「全部の状態に到達できる」テストの意味が、最初は分からなかった

書いたときは形だけ真似ました。あとで TRANSITIONS に on_hold: [] を足してみたら、そこだけで落ちました。 状態を足して、そこへ行く矢印を引き忘れる。 これは図を目で見ても気づきません。 「誰も来られない状態」はコードの死骸になります。 このテストはそれを見つけます。

8. 図を描いたあと、コードに落とさずに満足してしまった

order-state.mjs を書いた時点で「終わった」と思いました。テストを書くまでは、何も守られていませんでした。 実際、legacy.mjs との突き合わせを書くまで、支払い済みからキャンセルできるバグは1件も見つかりませんでした。 図をコードにしただけでは腐ります。テストが「ずれたら落ちる」を作ります。 ここまでやって初めて完成です。


後片づけ

この記事で作ったものは全部 ~/cslab/uml の中です。そのまま消せます。

bash
$ ls ~/cslab/uml
README.md          class.md          er-from-sql.mjs   gen-diagram.mjs
legacy.mjs         legacy.test.mjs   legacy2.mjs       order-state.mjs
order-state.mmd    order-state.test.mjs                schema.sql
table.mjs
bash
$ cd ~
$ rm -rf ~/cslab/uml
$ ls ~/cslab

インストールしたものは1つもありません。 作図ツールも、npm のパッケージも入れていません。 使ったのは Node.js とテキストエディタだけです。

~/cslab ごと消しても構いません。

bash
$ rm -rf ~/cslab

MySQL に schema.sql を流していた場合は、そちらも消します。

bash
$ mysql -u root -p -e "DROP DATABASE IF EXISTS uml_demo;"

DROP DATABASE は戻せません。 データベース名を必ず確認してから打ってください。 別の名前で作っていた場合は、その名前に読み替えます。 先に SHOW DATABASES; で一覧を見て、消してよい名前かを目で確かめてから打つのが安全です。


まとめ — 理解できたこと

  • コードには「どうやるか」しか書けない。「なぜそうしたか」と「全体の形」は、コードの外にしか置けない
  • 1人開発でも図は要る。3か月後の自分は他人で、しかも「分かっているはず」と思い込む分だけ他人より危ない
  • 画像で描いた図は必ず腐る。 git diff に「バイナリが変わりました」としか出ないので、ずれても誰も気づかない
  • 対策は1つ。テキストで書いて、コードと同じリポジトリに置いて、Gitで差分を見る。 5行の差分で「支払い済みのキャンセルをやめた」が伝わる
  • Mermaid は GitHub と VS Code がそのまま図にする。 何も入れなくてよい。ただし表示する側の機能で、Markdown の仕様ではない
  • UMLは13種類あるが、実際に描くのは3つで9割(クラス図・シーケンス図・ER図)。残りは読めれば足りる
  • クラス図で一番の情報は多重度。 線が白菱形か黒菱形かより、1..* か * かのほうが実装を変える
  • 集約とコンポジションの見分けは1つ。「親を消したら子はどうなるか」。 それは ON DELETE CASCADE を付けるかどうかそのもの
  • 全クラスを描くと線が交差して読めなくなり、2週間で嘘になる。 描くのは自分が迷ったところだけ
  • シーケンス図は縦が時間。 登場人物は5つまで、役割名で書く、失敗の分岐を1本は入れる
  • 非同期を説明する手段として、シーケンス図に代わるものが無い。 「返事を待たない」を文章で書くと必ず誤解される
  • 多対多は表2つでは表せない。 1つのセルに複数の値を入れられないので、行を増やす方向=中間テーブルしかない
  • post_tags の主キーは (post_id, tag_id) の複合。 これが「同じ組み合わせは1つだけ」を守っている。id を付けると壊れる
  • 図は SQL から作れるが、逆はできない。 だから正は SQL 側に置き、図はそこから生成する
  • ステートマシン図は、そのまま状態遷移表としてコードになる。 6状態で36通りのうち通れるのは5通りだけ
  • 31通りの「通ってはいけない」を人手では確かめられない。 だからテストにする
  • 「全部の状態に最初の状態から到達できる」テストは、図の書き間違いを見つける。 誰も来られない状態はコードの死骸になる
  • 図と既存実装の突き合わせテストで、6箇所のずれが名指しで出た。 うち1つが「支払い済みをキャンセルできる」=金の話
  • 遷移表を正にすると if が1つも要らなくなる。 業務ルールを変えるとき、直す場所が1箇所になる
  • 図をコードにしただけでは腐る。「ずれたら落ちる」テストまで書いて完成。 私はここを飛ばして3週間気づかなかった
  • 機械で守れるものと守れないものがある。 多重度は外部キー、一意は UNIQUE、状態遷移はテスト。呼ぶ順番だけは図で持つしかない

参考リンク


次に読む

この記事は 【深掘り】コンピュータ科学 の 20 / 25 本目です。

記事
← 前の記事デザインパターンとDI — テストが書けないのは設計のせい
→ 次の記事トランザクションとACID — ROLLBACKしたのに戻らない

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

›CS — UML & ER Diagrams
  • テキストで書いてGitに置く
  • 図をそのままテストにする

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次