メルマード図 クリックなしでマーカードにドキュメントアーキテクチャ

あなたがそのアーキテクチャ図を描いたとき、それは3つのスプリント前のことでした。今では共有されているGoogleスライドに存在し、そのサービスを構築したエンジニアはチームを移動しています。これは似ていますか？

メルマード図はこの問題を逆に取り上げます。ドラッグ＆ドロップ可能なキャンバスがコードベースの外にあるのではなく、あなたはテキストとして図を書きます——シンプルなマークダウン形式の構文がREADMEに存在し、コードとともにバージョン管理され、マークダウンがレンダリングされる場所でレンダリングされます。アーキテクチャが変更されたとき、1つのテキストファイルを変更します。差分はそのすべての物語を語ります。

メルマードとは何か（そして図をコードとして扱う理由）

メルマードはオープンソースの図示言語で、テキストから図をレンダリングします。あなたはコードブロックにフロー図を書きます；レンダラー（またはメルマードを認識する閲覧器）がそれをSVG図に変換します。アカウントは必要なく、エクスポートステップも必要なく、「このマシンでは図のフォーマットがサポートされていません」という問題もありません。

「図をコードとして扱う」というアプローチは、いくつかの具体的な方法でその価値を発揮します：

• バージョン管理 — 図はGitに存在します。差分を取ったり、元に戻したりでき、コードを説明するPRに一緒に添付できます。
• ベンダーのロックインなし — テキストは移植可能。レンダラーを切り替え、リポジトリをフォーク、Confluenceにエクスポート——ソースは常に読み取り可能になります。
• コードに近い位置にある — そのサービスを説明するコードと同じリポジトリにある図は、共有スライドに存在する図よりもずっと正確に保たれます。
• 自動化に適している — あなたはコード（データベーススキーマ、API仕様、CIパイプライン）からメルマード構文をスクリプトまたはLLMを使って生成できます。

図の種類に進む前に、いつでもインスタントにメルマード構文をプレビューできます——ローカルのセットアップは不要——以下の メルマード図レンダラー iotools.cloudに貼り付け、結果を確認し、反復します。このガイドと一緒に使用して、すべての例をリアルタイムで実行できます。

フロー図：主要なツール

フロー図は最も一般的なメルマード図のタイプであり、その理由は、単純な決定木から複雑なマルチサービスフローまでを処理できるからです。以下の構文が90%の実際の使用ケースをカバーしています：

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

フロー図構文についていくつか知っておくべき点があります：

• 方向: TD (上から下) LR (左から右) BT (下から上) RL (右から左)
• ノードの形状: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• エッジラベル: -- label --> または -->|label|
• サブグラフ: 関連するノードを視覚的にグループ化する

サブグラフはサービスの境界を示すために特に有用です：

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

シーケンス図：API呼び出しの流れを示す

シーケンス図は、システム間の相互作用の順序を示すときに適しています——API呼び出し連鎖、認証フロー、ウェブ훅シーケンス。フロー図では示せない、タイミングと責任を明確にします。

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

固体の矢印（->>）は要求；点線の矢印（-->>）は応答です。 participant 宣言は、図の上部にボックスが表示される順序を制御します。あなたはまた actor を人間の参加者に使用できます, activate/deactivate 処理時間の表示に使用できます、および loop または alt ブロックは条件付きフローを示します。

エンティティ・リレーションシップ図：データベーススキーマをドキュメントに含める

ER図は、データベーススキーマを持つすべてのサービスのREADMEに含まれるべきです。メルマードのER構文はシンプルで、カーディナリティを標準でカバーしています：

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

カーディナリティ記法： || は正確に1つです, o| は0または1つです, o{ は0または複数です, |{ は1または複数です。関係ラベル（「場所」、「含む」）は最終に引用記号で入力されます。

状態図：ワークフローと状態マシンをモデル化する

エンティティが異なる状態を移動する場合——注文、サブスクリプション、CIジョブ——状態図はフロー図よりも正確です。メルマードの状態図構文は、コードで状態マシンを定義する方法と直接対応しています：

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] は開始および終了状態をマークします。遷移はそれらをトリガーするイベントを運びます。複合状態をネストし、 note ブロックを使用して遷移に追加のコンテキストを注釈できます。

クラス図：OOP構造をオンボーディングドキュメントに使用する

クラス図は、エンジニアにオブジェクト指向コードベースを導入する場合や、ドメインモデルを記述する場合に特に有用です。メルマードは継承、インターフェース、構成、メソッド署名をカバーしています：

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

可視性修飾子はUMLの慣例に従っています： + public, - private, # protected。関係矢印は関連（-->）、継承（<|--）、構成（*--）、および集積（o--).

をカバーします。

メルマードがネイティブにサポートされる場所

• GitHub メルマードの本質的な強みは、開発者がすでに使用しているツールとのネイティブ対応です：```mermaid— メルマードのコードブロック（
• GitLab ）は2022年以降、README、イシュー、プルリクエストの説明、Wikiにネイティブにレンダリングされます。
• — マークダウンファイルおよびWikiページでのネイティブメルマードサポート。 — メルマードコードブロックをコードブロックに貼り付け、"メルマード"に設定すると、その場でレンダリングされます。
• はい（組み込み） — マークダウンプレビューのメルマードサポート拡張機能は、ビルトインプレビュー画面で図をレンダリングします。
• Obsidian — メルマードは、プラグインなしでネイティブにレンダリングされます。
• Docusaurus, MkDocs, Astro — メルマードプラグインはすべての主要な静的サイトジェネレーターに存在します。
• Confluence — メルマード図のConfluenceアプリ経由で。

GitHubまたはGitLabにドキュメントを書く場合、メルマード図はゼロ設定でそのまま機能します。

課題と他のツールを使うべき場合

メルマードはすべての状況に最適ではありません。いくつかの注意点があります：

• 複雑なレイアウト — メルマードの自動レイアウトアルゴリズムは、大きなグラフでは常にきれいな結果を生み出しません。50以上のノードと多くの交差エッジがある場合、図を再構成または手動で分割する必要があるかもしれません。
• Confluenceでのレンダリング — ネイティブなConfluenceはメルマードをサポートしていません。有料アプリが必要です。チームがConfluenceにいる場合、この費用を予算化するか、draw.ioを使用します。
• 非標準の図のタイプ — ネットワーク図、デプロイメント図、C4アーキテクチャ図は、ワークアラウンドまたは十分にサポートされていません。
• スタイル制御 — メルマードのテーマオプションは限られています。ブランド化された図でカスタムカラーとフォントを使用する場合、レンダラーと戦う時間がかかります。

重要な代替案は次の通りです：

• PlantUML — 高い構文、より豊かなUMLサポート、そしてConfluenceとの良好な統合。Javaをローカルに必要とするか、サーバー側レンダラーが必要です。
• D2 — 新しい図をコードとして扱うツールで、レイアウト制御がより洗練されており、大きな図をより良好に扱えます。メルマードに比べてエコシステムの採用はまだ少ないが、急速に成長しています。
• draw.io / Excalidraw — ビジュアル制御が必要な場合、そして図がバージョン管理の外に存在することを気にしない場合にGUIツールです。

開発者ドキュメント——サービスREADME、APIフロー、オンボーディングガイド——において、メルマードは使用ケースをよくカバーしており、GitHubでのネイティブサポートだけでも学習曲線は価値があります。

インストールなしでメルマードをプレビューする

構文を実験したり、ローカルレンダラーをセットアップしていない人に図を共有したい場合、以下の メルマード図レンダラー iotools.cloud はサインアップ、インストール、設定なしでライブプレビューを提供します。メルマードコードを貼り付け、レンダリングされた図を確認し、出力コピーできます。

コードをコミットする前に構文をチェックする、Slackメッセージにレンダリングされたバージョンを共有する、または後にREADMEに貼り付けるプロトタイプを作成するのに役立ちます。

フロー図から始める

メルマード図を初めて書く場合、フロー図から始めます。コードベースにあるプロセスを書くことを考えていた場合——リクエストライフサイクル、バックグラウンドジョブ、デプロイパイプライン——をメルマード構文で10分以内に書きます。READMEに ```mermaid ブロックに貼り付け、プッシュします。GitHubは自動的にそれをレンダリングします。

その1つの図、バージョン管理され、コードを説明する場所に存在するため、信頼されないスライドデッキよりも価値があります。

あなたも好きかもしれません