T-CREATOR

Mermaid 図面の命名規約：ノード ID・エッジ記法・クラス名の統一ガイド

Mermaid 図面の命名規約：ノード ID・エッジ記法・クラス名の統一ガイド

Mermaid を使った図面作成では、ノード ID やエッジの記法、クラス名の命名規約を統一することで、コードの可読性や保守性が格段に向上します。しかし、実際のプロジェクトでは「どのような命名ルールを採用すべきか」「予約語との衝突をどう避けるか」といった課題に直面することも少なくありません。

本記事では、Mermaid 図面における命名規約のベストプラクティスを、具体例を交えながら詳しく解説します。チーム開発でも個人開発でも、統一されたルールがあれば図面の品質を一定に保つことができるでしょう。

背景

Mermaid における命名の重要性

Mermaid はテキストベースで図を描くため、命名規約が整っていないと以下のような問題が発生します。

  • ノード ID が重複して意図しない接続が生じる
  • 予約語との衝突でエラーが発生する
  • 図が複雑になったときに、どのノードが何を表すのか理解しにくい
  • チームメンバー間で記法がバラバラになり、レビューや修正に時間がかかる

これらの問題を未然に防 � ぐためには、プロジェクト開始時点で命名規約を定めることが効果的です。

Mermaid の基本構文と命名要素

Mermaid 図面では、主に以下の要素に名前を付けます。

#要素説明例
1ノード ID図中の各要素を識別する IDuserNode, api01
2ノードラベル実際に図に表示されるテキスト"ユーザー", "API サーバー"
3エッジ記法ノード間の接続方法-->, -.->, ==>
4クラス名スタイル適用のためのクラス名highlight, errorStyle

これらの要素に対して、一貫性のある命名ルールを設定することで、図面の品質が向上します。

次の図は、Mermaid 図面の基本要素を示したものです。

mermaidflowchart LR
  userNode["ユーザー<br/>(ノードラベル)"] -->|エッジ記法| apiNode["API サーバー"]
  apiNode -.->|非同期| dbNode[("データベース")]

  class userNode highlight
  class apiNode highlight

図で理解できる要点:

  • ノード ID はコード内で要素を識別するための名前
  • ノードラベルは図に表示される日本語のテキスト
  • エッジ記法は矢印の種類（実線、破線など）を制御

課題

予約語との衝突問題

Mermaid には、構文として予約されているキーワードが多数存在します。これらを誤ってノード ID に使用すると、構文エラーが発生してしまいます。

代表的な予約語

#予約語用途衝突例
1graphフローチャートの開始宣言graph -->|接続| next
2subgraphサブグラフの定義subgraph["処理A"]
3endサブグラフや条件の終了start --> end
4classクラス定義class -->|継承| parent
5styleスタイル定義style -->|適用| node
6clickクリックイベント定義click -->|遷移| page

これらの予約語を避けるためには、明示的な命名規約が必要です。

命名規約の不統一による混乱

チーム開発では、メンバーごとに異なる命名スタイルを使うことで以下の問題が生じます。

mermaidflowchart TD
  member1["メンバー1の図"] --> inconsistent1["node1, node2, node3<br/>（連番スタイル）"]
  member2["メンバー2の図"] --> inconsistent2["userAction, apiCall<br/>（キャメルケース）"]
  member3["メンバー3の図"] --> inconsistent3["start_process, end_process<br/>（スネークケース）"]

  inconsistent1 --> confusion["混乱・可読性低下"]
  inconsistent2 --> confusion
  inconsistent3 --> confusion

図で理解できる要点:

  • メンバーごとに異なる命名スタイルが存在
  • 統一されていないと、図の理解に時間がかかる
  • レビューや修正のコストが増大

長いラベルと可読性の問題

日本語のラベルが長くなると、図が見づらくなったり、レイアウトが崩れたりします。改行を適切に挿入するルールも必要です。

解決策

ノード ID の命名規約

ノード ID には、以下のルールを適用することを推奨します。

基本ルール

#ルール理由例
1英数字とアンダースコアのみ使用予約語との衝突を避けるuser_node, api01
2小文字スネークケースまたはキャメルケース可読性と一貫性user_action または userAction
3接頭辞で種類を明示ノードの役割を即座に理解page_, api_, db_
4予約語は suffix で回避予約語を使いたい場合endNode, graphNode

推奨する接頭辞パターン

javascript// ノード種別ごとの接頭辞例
const nodePrefix = {
  page: 'page_', // ページ・画面
  api: 'api_', // API エンドポイント
  db: 'db_', // データベース
  service: 'svc_', // サービス層
  component: 'cmp_', // コンポーネント
  process: 'proc_', // プロセス・処理
  state: 'st_', // 状態
  event: 'evt_', // イベント
};

このルールを適用したコード例です。

mermaidflowchart LR
  page_login["ログインページ"] -->|認証リクエスト| api_auth["認証 API"]
  api_auth -->|クエリ| db_users[("ユーザーDB")]
  api_auth -->|トークン発行| page_dashboard["ダッシュボード"]

適用のメリット:

  • page_、api_、db_ の接頭辞でノードの役割が明確
  • 予約語との衝突を完全に回避
  • コードレビュー時に理解しやすい

ノードラベルの命名規約

ノードラベルは実際に図に表示される部分なので、読みやすさを最優先します。

ラベルの記述ルール

typescript// ラベル記述のベストプラクティス
interface LabelRule {
  // 1. 日本語で簡潔に（10文字以内を推奨）
  shortLabel: string;

  // 2. 長い場合は <br/> で改行
  longLabel: string;

  // 3. 記号を含む場合は ["..."] で囲む
  withSymbol: string;
}

具体的な記述例です。

mermaidflowchart TD
  node01["ユーザー登録"] --> node02["入力検証<br/>バリデーション"]
  node02 --> node03["DB保存<br/>(トランザクション)"]
  node03 --> node04["メール送信"]

ラベル記述のポイント:

  • 1 行が長い場合は <br​/​> で改行（改行文字 \n は使わない）
  • 括弧や記号を含む場合は ["..."] で囲む
  • 動詞で始めると処理の流れが分かりやすい

エッジ記法の統一ルール

エッジ（矢印）の記法も、用途に応じて統一することで図の意味が明確になります。

エッジ記法の使い分け

#記法意味使用例
1-->通常のフロー・処理の流れA --> B
2-.->非同期・オプションの流れA -.-> B
3==>強調・重要な経路A ==> B
4--xエラー・失敗の経路A --x B
5--o循環・ループA --o B

エッジ記法を統一した図の例です。

mermaidflowchart TD
  user["ユーザー"] -->|正常| auth["認証処理"]
  auth -->|成功| dashboard["ダッシュボード"]
  auth --x|失敗| error["エラー画面"]
  dashboard -.->|非同期| notification["通知取得"]

図で理解できる要点:

  • 実線 --> は通常の処理フロー
  • 破線 -.-> は非同期処理やオプション
  • --x はエラー経路を明示

クラス名の命名規約

スタイルを適用するためのクラス名も、役割が分かる名前にします。

クラス名のパターン

typescript// クラス名の命名例
const styleClasses = {
  // 状態を表すクラス
  active: 'activeState',
  inactive: 'inactiveState',
  error: 'errorState',

  // 強調を表すクラス
  highlight: 'highlightBox',
  important: 'importantNode',

  // 種別を表すクラス
  database: 'dbStyle',
  api: 'apiStyle',
  frontend: 'frontStyle',
};

クラスを適用した例です。

mermaidflowchart LR
  input["入力フォーム"] --> validate["バリデーション"]
  validate -->|OK| save["保存処理"]
  validate --x|NG| errorMsg["エラー表示"]

  class save highlightBox
  class errorMsg errorState

  classDef highlightBox fill:#d4edda,stroke:#28a745,stroke-width:2px
  classDef errorState fill:#f8d7da,stroke:#dc3545,stroke-width:2px

クラス適用のポイント:

  • クラス名は役割を明確に（highlightBox、errorState など）
  • classDef でスタイルを定義し、class で適用
  • 色やスタイルの意味を統一（緑 = 成功、赤 = エラーなど）

具体例

ケーススタディ 1: ユーザー認証フロー

実際のプロジェクトを想定した、ユーザー認証フローの図を作成します。

設計方針

#要素規約
1ノード IDpage_、api_、db_ の接頭辞を使用
2ラベル日本語・簡潔・必要に応じて改行
3エッジ成功は -->、失敗は --x
4クラス成功経路は緑、エラー経路は赤

実装コード

mermaidflowchart TD
  page_login["ログインページ"] -->|認証情報送信| api_auth["認証 API"]

  api_auth -->|検証| db_users[("ユーザーDB")]

  api_auth -->|成功| api_token["トークン発行"]
  api_auth --x|失敗| page_error["エラーページ"]

  api_token --> page_dashboard["ダッシュボード"]

  page_dashboard -.->|非同期| api_profile["プロフィール取得 API"]
  api_profile -.-> db_profiles[("プロフィールDB")]

  class api_token successPath
  class page_error errorPath

  classDef successPath fill:#d4edda,stroke:#28a745,stroke-width:2px
  classDef errorPath fill:#f8d7da,stroke:#dc3545,stroke-width:2px

図で理解できる要点:

  • 接頭辞でノードの種類が一目瞭然
  • 成功経路とエラー経路が色分けされている
  • 非同期処理は破線で表現

コードの解説

上記の図では、以下の命名規約を適用しています。

javascript// ノード ID の命名規則
const nodeIds = {
  pages: ['page_login', 'page_error', 'page_dashboard'],
  apis: ['api_auth', 'api_token', 'api_profile'],
  databases: ['db_users', 'db_profiles'],
};

// 各 ID は役割が明確で、予約語と衝突しない
console.log(nodeIds.pages); // ページ系のノード
console.log(nodeIds.apis); // API 系のノード
console.log(nodeIds.databases); // DB 系のノード

エッジ記法の使い分けも明確です。

javascript// エッジ記法の用途
const edgeTypes = {
  normal: '-->', // 通常の処理フロー
  error: '--x', // エラー経路
  async: '-.->', // 非同期処理
};

// 使用例
// api_auth -->|成功| api_token   （通常フロー）
// api_auth --x|失敗| page_error  （エラー）
// page_dashboard -.->|非同期| api_profile  （非同期）

ケーススタディ 2: シーケンス図の命名規約

シーケンス図でも、参加者（Participant）の命名規約を統一します。

参加者の命名ルール

typescript// シーケンス図の参加者命名
interface ParticipantNaming {
  // ID: 英数字・スネークケース
  id: string;

  // 表示名: 日本語で簡潔
  displayName: string;

  // 種別接頭辞
  prefix: 'user_' | 'frontend_' | 'backend_' | 'db_';
}

実装例です。

mermaidsequenceDiagram
  participant user_client as クライアント
  participant frontend_app as フロントエンド
  participant backend_api as バックエンド API
  participant db_main as メインDB

  user_client->>frontend_app: ログイン要求
  frontend_app->>backend_api: 認証リクエスト
  backend_api->>db_main: ユーザー検証
  db_main-->>backend_api: 検証結果
  backend_api-->>frontend_app: トークン
  frontend_app-->>user_client: ログイン完了

図で理解できる要点:

  • 参加者 ID は接頭辞で役割が明確
  • 表示名（as 以降）は日本語で分かりやすく
  • 矢印の種類で応答の方向が明確

ケーススタディ 3: 状態遷移図の命名規約

状態遷移図では、状態名とイベント名の命名が重要です。

状態とイベントの命名ルール

#要素規約例
1状態 IDst_ + スネークケースst_idle, st_processing
2状態ラベル日本語・体言止め"待機中", "処理中"
3イベント動詞で開始"開始", "完了", "エラー発生"

実装例です。

mermaidstateDiagram-v2
  [*] --> st_idle
  st_idle --> st_processing: 処理開始
  st_processing --> st_success: 成功
  st_processing --> st_error: エラー発生
  st_success --> st_idle: リセット
  st_error --> st_idle: リトライ
  st_success --> [*]

  state st_idle {
    [*] --> waiting
    waiting --> ready: 準備完了
  }

図で理解できる要点:

  • 状態 ID は st_ 接頭辞で統一
  • イベントは動詞で開始し、何が起きるかを明示
  • サブステートも同じ規約で記述

ケーススタディ 4: クラス図の命名規約

クラス図では、クラス名やメソッド名の命名規約を適用します。

クラス図の命名ルール

typescript// クラス図の命名例
class NamingConvention {
  // クラス名: パスカルケース
  className: string;

  // プロパティ: キャメルケース
  propertyName: string;

  // メソッド: キャメルケース + 動詞
  methodName(): void;
}

実装例です。

mermaidclassDiagram
  class UserModel {
    +String userId
    +String userName
    +String email
    +authenticate() Boolean
    +updateProfile() void
  }

  class AuthService {
    +login(credentials) Token
    +logout() void
    +validateToken(token) Boolean
  }

  class DatabaseRepository {
    +findUserById(id) User
    +saveUser(user) void
    +deleteUser(id) void
  }

  UserModel --> AuthService: uses
  AuthService --> DatabaseRepository: uses

図で理解できる要点:

  • クラス名はパスカルケース
  • メソッド名は動詞で開始
  • 関係性も明確に記述

まとめ

Mermaid 図面における命名規約を統一することで、以下のメリットが得られます。

命名規約のメリット

#メリット効果
1可読性の向上コードレビューや修正が容易
2予約語との衝突回避構文エラーを未然に防ぐ
3チーム開発での統一性メンバー間の認識齟齬を削減
4保守性の向上長期プロジェクトでも品質を維持

推奨する命名規約まとめ

以下の規約を基本として、プロジェクトの特性に応じてカスタマイズしてください。

typescript// ノード ID: 接頭辞 + スネークケース
const nodeIdPattern =
  /^(page|api|db|svc|cmp|proc|st|evt)_[a-z0-9_]+$/;

// ノードラベル: 日本語・簡潔・改行は <br/>
const labelRules = {
  maxLength: 10, // 1行あたりの推奨文字数
  lineBreak: '<br/>', // 改行記号
  quote: '["..."]', // 記号を含む場合
};

// エッジ記法: 用途別に統一
const edgePatterns = {
  normal: '-->', // 通常フロー
  async: '-.->', // 非同期
  error: '--x', // エラー
  important: '==>', // 強調
};

// クラス名: 役割を明確に
const classNamePattern = /^[a-z]+[A-Z][a-zA-Z]*$/; // キャメルケース

Mermaid を使った図面作成は、命名規約を整えることで劇的に品質が向上します。本記事で紹介したルールを参考に、チームや個人のプロジェクトで最適な規約を策定してみてください。

統一されたルールがあれば、図面は「コミュニケーションツール」として最大限の力を発揮するはずです。

関連リンク

Mermaidの記事Mermaid

もっと見る

記事Article

もっと見る

ブログBlog

もっと見る

書籍レビューReview

もっと見る