開発ドキュメントなどを書いているときに、ものごとをシーケンス図で表現したいことがあるかもしれません。
シーケンス図を書けるようになることで、開発ドキュメントやブログなどにおいて、読み手にものごとをより分かりやすく伝えられるようになります。また、設計をするときなどシーケンス図を書くことで、頭の中が整理されるという効果もあります。
この記事では、まずシーケンス図やPlantUMLとは何か？について解説し、続いてシーケンス図の書き方を説明していきます。シーケンス図の書き方は覚えなくても、この記事を見ながら書ければ十分だと思います。チートシートのような形でご利用ください。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
シーケンス図とは
まず、シーケンス図について説明します。シーケンス図は、システムの処理の流れを表現したりするときに用いられる図です。ユーザーとサーバーの関係のような、システムの構成要素同士のやりとりを、時間軸にそって表現します。
例えば、開発ドキュメントを書く場合について考えてみます。とあるシステムについて説明するとき、文章だけだと伝わりづらいかもしれません。このとき、「システム内でどういうやりとりがされるか」という図がひとつでもあると、読者の理解を助けることができます。
このシーケンス図は、UMLという言語で記述することができます。
シーケンス図の例
ここで、シーケンス図の具体例を見てみます。以下の図は、「アクセストークンを用いてリソースを取得する流れ」を表した図になります。このような図をシーケンス図といいます。
シーケンス図における登場人物としては、大きく分けると次の4つがあります。このような登場人物を組み合わせて、シーケンス図を書いていくことになります。
| 登場人物 | 意味 | 図における例 |
|---|---|---|
| 分類子 | システムの構成要素 | ユーザーやクライアントなど |
| ライフライン | 分類子の時間軸 | 各分類子がもつ縦のライン |
| メッセージ | やりとりの内容 | 矢印 |
| ノート | 補足情報 | 黄色いメモ |
PlantUMLとは
次に、PlantUMLについて簡単に説明します。PlantUMLは、テキストベースでシーケンス図を書くことのできる、UMLの一種です。シーケンス図を書く方法はいくつかありますが、この記事ではPlantUMLでシーケンス図を書く方法を解説していきます。
前提条件
この記事では、すでにPlantUMLが動作する環境がある前提で解説していきます。もしまだ環境を構築していない場合は、インターネットで「PlantUML 環境構築」などで検索して準備してください。
あるいは、次のようなオンライン上でPlantUMLを実行できるサービスもあります。こちらを利用しても問題ありません。
メッセージ
メッセージは、システムの構成要素（分類子）同士のやりとりを表現します。シーケンス図は、このメッセージを送り合うことで書いていきます。
メッセージの基本的な書き方は次の通りです。これを表示すると、上の図のようになります。
User -> Client : アクセスする User <- Client : 認可用URLを提示する Client -> Client : 何らかの処理をする User <-> Server : ユーザー認証・同意する
このように、分類子同士を矢印、ここでいう->でつなげます。その後にコロンを書き、続けてメッセージの内容を書きます。これによって分類子同士のやりとりを表現できます。
この矢印は、左右どちらの向きにも書けます。また自分から自分に矢印をつなげることで、自分自身へのメッセージも表現できます。<->のように、双方向のメッセージも表現できます。
メッセージの種類
メッセージは分類子同士を矢印でつなげたものですが、この矢印にはいくつかの種類があります。例えば上の図は、次のようなコードで表現します。
User ->o Client : アクセスする User x<- Client : 認可用URLを提示する Client --> Client : 何らかの処理をする
このように、矢印の先頭にoをつけると、丸が表示されます。同じようにxをつけるとバツが表示されます。また、矢印を-->のようにハイフンを2つつなげると、破線になります。
メッセージの色
メッセージを書くときに、矢印の色を変更できます。例えば上の図は、次のようなコードで表現します。
User -[#red]> Client : アクセスする User <[#0000ff]- Client : 認可用URLを提示する
このように、矢印の色を変えるには、矢印の記号の間にカッコを書きます。その中に#を書き、続けて色を指定します。
色の指定については、redのような色の名前か、あるいは0000ffのような16進数のカラーコードで行います。色の名前やカラーコードについて詳しくは、HTML Color Namesというページが役に立ちます。
メッセージの番号
メッセージには、上から順に番号をつけることができます。これは、文章で図を解説するときなどに役立ちます。
この番号をつけるには、autonumberというキーワードを使います。これで、メッセージごとにひとつずつ番号が増えていきます。例えば上の図は、次のようなコードで表現できます。
autonumber User -> Client : アクセスする User <- Client : 認可用URLを提示する User -> Server : 認可を要求する autonumber 10 User <-> Server : ユーザー認証・同意する autonumber stop Client <- Server : 認可コードを発行する autonumber resume Client -> Server : アクセストークンを要求する
番号を指定したいときは、autonumberの後に番号を書きます。また、途中でカウントアップを中止したいときはstopを、再開したいときはresumeを付け加えます。
メッセージのグループ化
上の図のように、いくつかのメッセージをグループでまとめたいときがあります。このときはaltなどのキーワードを使います。例えば、上の図は次のコードで表現できます。
User -> Client : アクセスする alt 認証が不要なページ User <- Client : ページを表示する else 認証が必要なページ User <- Client : 認可用URLを提示する end
このコードの例では、ユーザーの認証状況によって、クライアントからのレスポンスが変わることを表現しています。このelseはいくつでもつなげることができます。
上の例ではaltですが、これ以外にも次のようなキーワードがあります。
- opt
- loop
- par
- break
- critical
- group 任意のラベル名
例えばloopはループの回数を表すときに役立ちます。他にもgroupは任意のラベルでメッセージをグループ化することができます。
分類子
シーケンス図において、システムの構成要素を分類子といいます。例えばこの記事に出てくる図のユーザーやクライアント、サーバーなどが分類子にあたります。システムの構成要素の数だけ、分類子を書くことになります。
分類子の種類
この分類子には、次に示す8つの種類があります。表現したい構成要素に合わせて分類子を使い分けていきます。ちなみに、分類子の種類を指定しなかった場合はparticipantになります。
participant MyParticipant actor MyActor boundary MyBoundary control MyControl entity MyEntity database MyDatabase collections MyCollections queue MyQueue
分類子の名前
分類子には名前をつけることができます。例えば分類子をユーザー、クライアントと日本語で表記するケースを考えてみます。このとき、次のように日本語で表記すると、図を書くのが面倒になります。
ユーザー -> クライアント : アクセスする
これについて、asキーワードを使うことで、分類子に名前をつけることができます。
actor ユーザー as User participant クライアント as Client User -> Client : アクセスする
分類子の背景色
分類子の背景色は変更することもできます。やり方は、分類子を定義するときに、色も合わせて指定します。
actor ユーザー as User participant クライアント as Client participant 悪意のあるアプリ as App #ffaaaa
上の図のように、例えば背景を赤くすることで、「この分類子は危険な要素である」ということを表現できます。
分類子のグループ化
分類子を、まとまりごとにグループ化することができます。グループ化は、分類子を定義するときにboxキーワードで囲います。
box Internal Service #eeeeee actor User participant Client end box participant App
boxキーワードの後ろの文字は、タイトルを表します。また色を指定することで、背景色を変更することもできます。
ノートとリファレンス
PlantUMLでは、シーケンス図の中に補足情報を表示できます。これがノートとリファレンスです。
ノートの書き方
ノートは、メッセージの近くにメモを表示できる機能です。noteキーワードでノートを表示することができます。あわせて、noteに続けてleftまたはrightでノートの表示位置を指定します。
User -> Client : アクセスする note left : note left User <- Client : 認可用URLを提示する note right note right end note note over User : note over User User <- Server : ログイン画面を表示 note over User, Client : note over User, Client note across : note across
overキーワードで、分類子を基準とした位置にノートを表示できます。このoverキーワードのときに指定する分類子は、複数を指定することが可能です。
acrossキーワードを指定すると、すべての分類子をまたぐノートを表示することができます。またend noteキーワードを用いれば、複数行のノートも表示できます。
ノートの背景色
ノートも背景色を変更することができます。これはnoteキーワードの後ろに色を指定します。
User -> Client : アクセスする note left User #aqua : note left
リファレンスの書き方
シーケンス図の中に、リファレンスとして補足情報を表示できます。これはref overキーワードを用います。ref overの後ろに、対象となる分類子を指定します。
User -> Client : アクセスする ref over User : ユーザーの上に表示する User <- Client : 認可用URLを提示する ref over User, Client ユーザー・クライアントに またがって表示する end ref
分類子を指定するときは、カンマでつなげることで、複数の分類子にまたがってリファレンスを表示できます。またend refキーワードを用いれば、複数行のリファレンスを表示できます。
ライフライン
ライフラインは分類子の下にある縦の線のことで、分類子の時間軸を表しています。activateというキーワードを用いると、このライフラインがアクティブな状態であることを表現することができます。アクティブな状態は、白い長方形のようなもので表現されます。
また、アクティブな状態を解除するにはdeactivateキーワードを用います。例えば上の図を表現するには、次のようなコードになります。
actor ユーザー as User
participant クライアント as Client
database 認可サーバー as Server
User -> Client : アクセスする
activate Client
User <- Client : 認可用URLを提示する
User -> Server : 認可を要求する
activate Server #ffaaaa
User <-> Server : ユーザー認証・同意する
Client <- Server : 認可コードを発行する
Client -> Server : アクセストークンを要求する
Client <-- Server : アクセストークンを返却する
destroy Server
User <- Client : 画面を表示する
deactivate Client
destroyキーワードは、アクティブな状態が途中で終わったことを意味します。またactivateの後ろに色を指定することで、背景色を設定することもできます。
ショートカット
前のセクションではライフラインのアクティブ化にactivateとdeactivateを用いましたが、次のようなショートカットもあります。
++: 対象となる分類子をアクティブにする--: 起点となる分類子を非アクティブにする
例えば、上の図は次のようなコードで表現できます。
actor ユーザー as User participant クライアント as Client database 認可サーバー as Server User -> Client ++ : アクセスする User <- Client : 認可用URLを提示する User -> Server ++ : 認可を要求する User <-> Server : ユーザー認証・同意する Client <- Server : 認可コードを発行する Client -> Server : アクセストークンを要求する Client <- Server -- : アクセストークンを返却する User <- Client -- : 画面を表示する
ショートカットはライフラインの状態を表すのに便利ですが、一方でショートカットではうまく表現しきれないときがあります。そのときはactivateキーワードを用いるといいです。
その他の表現
ここまでで解説した内容が、PlantUMLの基本になります。他にも、役に立つ表現がいくつかあるので補足します。
区切り線
メッセージのやりとりを、ステップごとに分けることができます。これは== タイトル ==という形式で書きます。
User -> Client : アクセスする == 区切り線 == User <- Client : 認可用URLを提示する
遅延
メッセージのやりとりの途中で発生する遅延を表現することができます。これは...と書きます。遅延にコメントをつけるときは... コメント ...のように記述します。
User -> Client : アクセスする ... User <- Client : 認可用URLを提示する ... 5 minutes later ... User -> Server : 認可を要求する
文字の装飾
ノートやメッセージのように文字を表示できるところでは、文字の太さや色を変えるといった装飾が行えます。これはWikiのための記法であるCreoleというフォーマットで装飾できます。
User -> Client : アクセスする note left User === 文字の装飾 * **太字** * __下線__ * <color #red>色の変更</color> end note
Creoleフォーマットについては、次のページが役に立ちます。
改行
メッセージやノートなどの文字を書くところでは、文字を改行することができます。これは\nという記号で行えます。
User -> Client : アクセス\nする
