シーケンス図の書き方｜記号・alt/loop等と実務3パターン

シーケンス図とは、システムの登場人物（利用者、画面、API、データベースなど）が、どの順番でどんなメッセージをやり取りするかを、時間の流れに沿って表すUMLの図です。 上から下へ時間が進み、横に並んだ登場人物の間を矢印でつないで表します。

記号の紹介だけなら多くの解説がありますが、実務で迷うのは「タイムアウトや再試行はどう描くか」「非同期処理の矢印はどれか」「どこまで細かく描くか」といった点です。この記事では、記号と複合フラグメント（alt、loopなどの枠）7種類の意味を表で整理したうえで、ログイン／外部API呼び出し＋タイムアウト／非同期ジョブの実務3パターンをMermaidで示します。掲載したMermaidはすべて mermaid-cli 12.0.0 で描画できることを確認済みです。PlantUML版、詳細度の判断基準、NG例の修正、コードから起こすコツ、AIに描かせるときの指示例もまとめました。

シーケンス図の書き方の早見表

シーケンス図の記号一覧

※Mermaid では、非同期メッセージを -)、×付きの矢印を -x で描きます。->> と -) は矢じりの形が違うだけなので、同期か非同期かを凡例やノートで補うと読み違いが減ります。

複合フラグメント（alt・opt・loop など）の意味

複合フラグメントとは、メッセージのまとまりを枠で囲み、左上の演算子で「分岐」「繰り返し」などの意味を与える記法です。 枠の中の条件は [ ] に書きます（ガード条件）。

UML 2.5 の仕様では、このほかに neg（起きてはいけない）、assert（必ずこうなる）、strict、seq、ignore、consider も定義されています。業務システムの設計書では、上の表の7種類でほとんどの場面を表せます。

altとoptの使い分けは「else側で何かするか」です。else側で何もしないならopt、何かするならaltにします。また、Mermaid の critical には option で別の状況を書き足す独自の書き方がありますが、UMLの critical は枠を1つだけ持つ演算子なので、分岐は中に alt を入れて表すと、UMLに慣れた読み手にも伝わりやすくなります。

実務パターン1：ログイン（alt）

架空の「会員制の予約サイト」のログインです。正常系と、パスワード不一致をaltで分けます。

sequenceDiagram
    autonumber
    actor U as 会員
    participant B as ブラウザ
    participant A as 認証API
    participant D as 会員DB

    U->>B: ID・パスワードを入力
    B->>+A: POST /login
    A->>+D: 会員を検索（ID）
    D-->>-A: 会員レコード
    alt パスワード一致
        A->>A: セッションを発行
        A-->>B: 200 OK（Cookie）
        B-->>U: マイページを表示
    else 不一致
        A->>D: 失敗回数を+1
        A-->>B: 401 Unauthorized
        B-->>U: エラーを表示
    end
    deactivate A

※WordPressでMermaidの図を表示するには、Mermaid対応のプラグインが必要です。

ポイント

• autonumber でメッセージに通し番号が付き、レビューで「5番の矢印ですが」と指摘しやすくなります
• B->>+A の + で活性区間を開始し、最後に deactivate A で閉じています
• 戻りメッセージにはHTTPステータスなど「何が返るか」を書くと、API設計との対応が明確になります

同じ図をPlantUMLで書く

PlantUMLは、Javaで動くテキスト作図ツールです。データベースを円柱で描ける、ref over が使えるなど、UMLの記法に近い表現ができます。

@startuml
autonumber
actor 会員 as U
participant ブラウザ as B
participant 認証API as A
database 会員DB as D

U -> B : ID・パスワードを入力
B -> A : POST /login
activate A
A -> D : 会員を検索（ID）
activate D
D --> A : 会員レコード
deactivate D
alt パスワード一致
  A -> A : セッションを発行
  A --> B : 200 OK（Cookie）
  B --> U : マイページを表示
else 不一致
  A -> D : 失敗回数を+1
  A --> B : 401 Unauthorized
  B --> U : エラーを表示
end
deactivate A
@enduml

このコードは、PlantUML（1.2019.06、Java 21で実行）でPNGに描画できることを確認しました。

MermaidとPlantUMLでは、->> の意味が逆（Mermaidは同期、PlantUMLは非同期）なので、書き換えるときは注意しましょう。

実務パターン2：外部API呼び出し＋タイムアウト（alt・loop・break）

「ECの注文」で、外部の在庫サービスに在庫数を問い合わせる場面です。タイムアウト、再試行、打ち切りを1枚で表します。

sequenceDiagram
    participant C as 画面
    participant O as 注文API
    participant S as 在庫サービス（外部）
    participant L as ログ基盤

    C->>+O: 注文内容を確認
    O->>S: GET /stock/{sku}（タイムアウト3秒）
    alt 3秒以内に応答
        S-->>O: 200 在庫数
        O-->>C: 在庫あり・注文可能
    else タイムアウト
        Note over O: 3秒経過で待つのをやめる
        loop 最大2回（1秒・2秒あけて再試行）
            O->>S: GET /stock/{sku}
        end
        break 再試行でも応答なし
            O-)L: 警告ログを送信
            O-->>C: 503（時間をおいて再操作を案内）
        end
    end
    deactivate O

ポイント

• タイムアウトは「相手からの応答」ではないので、戻り矢印ではなく、呼び出し側のノートで表します
• 再試行の回数と間隔（1秒・2秒）はガード条件に数字で書きます。「数回」では実装とテストの基準になりません
• break は「条件を満たしたら、この枠を実行して外側の残りを打ち切る」という意味です。再試行で応答が得られたときは、枠を抜けて「在庫あり」と同じ流れになることを、ノートで補足しておくと親切です
• ログ送信は結果を待たないので、非同期メッセージ（-)）にしています

実務パターン3：非同期ジョブ（非同期メッセージ・par・生成と破棄）

時間のかかるCSV出力を、ジョブキューで裏側に回す場面です。利用者はすぐに応答を受け取り、完了はメールで知らせます。

sequenceDiagram
    actor U as 利用者
    participant W as Webアプリ
    participant Q as ジョブキュー
    participant J as ワーカー
    participant M as メール送信

    U->>+W: CSV出力を依頼
    W-)Q: ジョブ登録（job_id）
    W-->>-U: 202 Accepted（job_id）
    Q-)J: ジョブを取り出す
    activate J
    create participant F as 一時ファイル
    J->>F: CSVを書き出す
    par 通知
        J-)M: 完了メールを依頼
    and 状態更新
        J->>Q: 状態=完了
    end
    destroy F
    J-xF: DL用の領域へ移したら削除
    deactivate J
    opt 画面を開いたまま
        U->>W: GET /jobs/{job_id}
        W-->>U: 状態=完了・DLリンク
    end

ポイント

• Webアプリはジョブを登録したらすぐ202を返すので、W-)Q は非同期、W-->>-U で活性区間が終わります
• create participant で途中から登場し、destroy で消える一時ファイルを表しています。生成と破棄を描くと、後片付け漏れのレビューがしやすくなります
• par は「順序を問わない」という意味です。通知と状態更新のどちらが先でも問題ない、という設計判断を図で伝えられます
• 状態確認は画面を開いているときだけなので opt にしています

補足：critical（割り込ませない処理）

「会員制の予約サイト」で、同じ枠に2件の予約が入らないようにする場面です。

sequenceDiagram
    participant A as 予約API
    participant D as 予約DB
    critical 同じ枠への予約を割り込ませない
        A->>D: SELECT ... FOR UPDATE（枠をロック）
        alt 空きあり
            A->>D: INSERT 予約
        else 満席
            A->>A: 409 Conflict を返す準備
        end
        A->>D: COMMIT（ロック解放）
    end

critical の範囲＝ロックを持っている範囲として描くと、トランザクションの境界がレビューで確認しやすくなります。

詳細度の判断基準：基本設計用とレビュー用

シーケンス図は、目的によって「ちょうどよい細かさ」が変わります。

迷ったら「この矢印を消すと、読み手の判断が変わるか」で残すかどうかを決めます。変わらない矢印は、ノートにまとめるか削除します。

NG例と修正

NG：内部の処理を全部描いて、分岐が見えない

sequenceDiagram
    participant C as LoginController
    participant S as AuthService
    participant R as MemberRepository
    participant H as PasswordHasher
    C->>S: login(id, pw)
    S->>S: validate(id)
    S->>S: trim(id)
    S->>R: findById(id)
    R->>R: buildQuery()
    R-->>S: member
    S->>S: getHash()
    S->>H: matches(pw, hash)
    H-->>S: true
    S-->>C: token

修正後：クラス間のやり取りと分岐に絞る

sequenceDiagram
    participant C as LoginController
    participant S as AuthService
    participant R as MemberRepository
    participant H as PasswordHasher
    C->>+S: login(id, pw)
    S->>+R: findById(id)
    R-->>-S: member（なければ空）
    S->>+H: matches(pw, hash)
    H-->>-S: 一致 / 不一致
    alt 会員あり かつ 一致
        S-->>C: token
    else それ以外
        S-->>C: 認証エラー（どちらが違うかは返さない）
    end
    deactivate S

クラスの境界をまたぐメッセージだけを残し、異常系をaltで足しただけで、レビューで確認すべき点（エラー時に何を返すか）が見えるようになりました。

その他のよくあるNG

コードからシーケンス図を起こすときのコツ

既存システムの調査や、実装後の設計書更新で、コードから図を起こすこともよくあります。

AIにシーケンス図を描かせるときの指示例

生成AIは、Mermaid や PlantUML のコードを書くのが得意です。登場人物・シナリオ・異常系・詳細度を指定すると、手直しの少ない図になります。

次の処理のシーケンス図を Mermaid の sequenceDiagram で書いてください。

# 対象
- 会員制の予約サイトの「予約確定」API（POST /reservations）

# 登場人物（左から順に）
- 会員(actor)、ブラウザ、予約API、予約DB、メール送信

# 描くこと
- 正常系：空き確認 → 予約登録 → 確認メールの依頼（メールは非同期）
- 異常系：満席なら409、DBエラーなら500（altで分ける）
- 同期は ->>、非同期は -)、戻りは -->> を使う
- 活性区間を付け、autonumber を使う

# 詳細度
- 基本設計用。クラス名やメソッド名は出さない
- 矢印は15本程度まで

# 最後に
- 図からは読み取れない前提（タイムアウト値など）を箇条書きで挙げてください

AIの出力は、必ず描画して確認します。Mermaid はバージョンによって使える構文（create participant など）が違うため、表示に使う環境（プラグインやmermaid-cli）で実際に描画できるかを見ます。そのうえで、ガード条件の具体性（数字が入っているか）と、同期・非同期の矢印の使い分けを人が確認しましょう。

よくある質問

Q. シーケンス図とアクティビティ図（フローチャート）はどう使い分けますか？ A. 「誰と誰がやり取りするか」を見せたいならシーケンス図、「処理の手順と分岐」を見せたいならアクティビティ図です。複数のシステムやサービスの間の連携を説明するときは、シーケンス図が向いています。

Q. 戻りメッセージは必ず描く必要がありますか？ A. UMLでは省略できます。ただし、何が返るか（ステータス、データ）がレビューの対象になる設計書では描くのがおすすめです。省略する場合は、エラーの戻りだけは描いておくと、異常系の確認漏れを防げます。

Q. 1枚のシーケンス図にどこまで入れてよいですか？ A. 目安は1シナリオ、ライフライン4〜6個、矢印15本前後です。これを超える場合は、共通部分を別の図に切り出し、PlantUML なら ref、Mermaid ならノートで参照先を示します。

Q. MermaidとPlantUMLのどちらを使えばよいですか？ A. GitHubやMarkdownの設計書で手軽に表示したいならMermaid、ref などUMLの表現を細かく使いたいならPlantUMLが便利です。チームの設計書の置き場所（表示できる環境）で選ぶのが確実です。

まとめ

• シーケンス図は、登場人物間のメッセージのやり取りを時間順に表すUMLの図です
• 矢印は同期（待つ）・非同期（待たない）・戻りを使い分け、活性区間で処理中の期間を示します
• 複合フラグメントはalt・opt・loop・par・break・critical・refの7種類でほとんどの場面を表せます
• タイムアウトは戻り矢印ではなく呼び出し側のノートで、再試行の回数と間隔は数字で書きます
• 1枚1シナリオにし、基本設計用とレビュー用で詳細度を変えます
• コードから起こすときは入口から1シナリオ、境界をまたぐ呼び出しだけを追います
• AIに描かせたら、使う環境で描画して確認し、条件と矢印の種類を人が見直します

株式会社RJCでは、シーケンス図で処理の流れを見える形にし、設計の意図を仲間と共有しながら開発を進めています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。