私は 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 が落ちるから
- 全部のクラスを描くのは間違い。 描くのは自分が迷ったところだけ
この記事でやること
- 作業場所
~/cslab/umlを作り、図を1つも画像にしないと決める - クラス図を、アスキー図と Mermaid 記法の両方で書く。関連・集約・コンポジション・継承の線を見分ける
- シーケンス図で、ログイン処理の「誰が誰を、どの順で呼ぶか」を縦に描く
- ER図を4テーブルで書き、
CREATE TABLEを Node.js に読ませて関係と中間テーブルを機械で出す - ユースケース図・アクティビティ図・ステートマシン図を、1つずつ小さな例で描いて「読める」ようにする
- 山場: ステートマシン図を状態遷移表としてコードに落とし、
node --testで図と実装を突き合わせる - わざと図とずれた実装を用意し、テストが6箇所のずれを名指しで出すところまで確かめる
- どの場面でどの図を描くかの判断表を作り、作業場所を消す
先に知る言葉
基本的な言葉は用語集にもまとめてあります。
| 言葉 | 1〜2行の意味 |
|---|---|
| UML | Unified 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つある
まず作業場所を作ります。
/home/ユーザー名/cslab/uml
Node.js のバージョンを確かめておきます。⑦で node --test を使うので、18以上が要ります。
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つです。
- GitHub の Markdown が、そのまま図として表示する(何も入れなくてよい)
- VS Code もプレビューで表示する
- 記法が短い。 覚えることが少ない
試してみます。~/cslab/uml/README.md を、エディタで作ります。
ここだけは cat のヒアドキュメントで作りません。 中にバッククォート3つのコードブロックが入るので、シェルに貼ると途中で切れるからです。 VS Code から VM のファイルを開く方法は nanoで書き続けるのは無理 — VS CodeからVMを直接編集する にあります。
README.md の中身は、こうします。
- 1行目に
# 設計メモ - 次に
## 注文の状態 - その下に、バッククォート3つ +
mermaidで始まり、バッククォート3つで終わるブロックを作る - そのブロックの中に、次の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..1 | 0個か1個 | 利用者にプロフィール画像は無いかもしれない |
1..* | 1個以上 | 注文には明細が最低1行は要る |
* または 0..* | 0個以上 | 投稿にコメントは0個でもよい |
2..5 | 2個以上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対多だったか、多対多だったか)
- 消したときにどうなるか決めていない(親を消したら子はどうなる)
- 同じような名前のクラスが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つあります。
- パスワードの照合は DB では行わず、APIサーバーの中でやっている(DB は行を返しているだけ)
- セッションIDの保存が成功してから 200 を返している(先に返していない)
- メールは返事を待っていない(点線の矢印。ここが非同期)
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 — posts | 1 対 多 | 1人が複数の投稿を書く。1つの投稿は1人のもの |
| users — comments | 1 対 多 | 1人が複数のコメントを書く |
| posts — comments | 1 対 多 | 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個 |
}o | 0個以上 |
}| | 1個以上 |
users ||--o{ posts は「利用者ちょうど1人に対して、投稿は0個以上」と読みます。
CREATE TABLE を書いて、図と突き合わせる
ここから手を動かします。 図を SQL に落とします。
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 無しで動きます)。
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}`);
}
}
走らせます。
テーブル: 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(', '));
走らせます。
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} --> [*]`);
}
stateDiagram-v2
[*] --> pending
pending --> paid: 支払い
pending --> cancelled: キャンセル
paid --> shipped: 発送
paid --> refunded: 返金
shipped --> delivered: 配達完了
delivered --> [*]
cancelled --> [*]
refunded --> [*]
この出力を README.md の mermaid 指定のブロックに貼れば、図とコードが絶対にずれません。 図を人が描くのをやめて、コードから作る——これが「腐らない図」の一番強い形です。
生成した図をファイルに残すには、こうします。
テストを書く — 図がそのままテストになる
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'), /未知の状態/);
});
走らせます。
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'));
});
走らせます。
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 の出力)も、両方が同時に変わります。
確かめます。
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 の中です。そのまま消せます。
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
インストールしたものは1つもありません。 作図ツールも、npm のパッケージも入れていません。 使ったのは Node.js とテキストエディタだけです。
~/cslab ごと消しても構いません。
MySQL に schema.sql を流していた場合は、そちらも消します。
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、状態遷移はテスト。呼ぶ順番だけは図で持つしかない
参考リンク
- roadmap.sh — Computer Science
- Mermaid 公式ドキュメント
- Mermaid — クラス図
- Mermaid — シーケンス図
- Mermaid — ER図
- Mermaid — ステートマシン図
- GitHub Docs — Markdown で図を作成する
- MySQL 公式 — FOREIGN KEY 制約
- MySQL 公式 — CREATE TABLE
- Node.js 公式 — テストランナー
- Node.js 公式 — assert
次に読む
この記事は 【深掘り】コンピュータ科学 の 20 / 25 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- テキストで書いてGitに置く
- 図をそのままテストにする
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント