コードとしての図：PlantUMLとVPasCodeによるUMLシーケンス図

AUML シーケンス図は、参加者が時間とともにどのように相互作用するかを示します。これは、ユースケース、APIフロー、ビジネスプロセス、またはシステムシナリオを文書化するのに役立ちます。時間は通常上から下へ移動し、水平配置は誰が参加するかを示し、経過時間の正確な測定ではありません。

PlantUMLは、図をテキストとして記述することを可能にします。Visual ParadigmのVPasCodeエディタは、コードエディタをライブプレビューとAI支援と組み合わせて、図コードの生成、変更、修正を行います。良いワークフローは、AIを使って最初のドラフトを作成し、その後PlantUMLを自分で検査して洗練させることです。

1. 基本構造

APlantUMLシーケンス図は@startumlで始まり、@endumlで終わります。参加者は通常、メッセージの前にリストされるため、名前と順序を制御できます。

@startuml
actor 顧客
participant ブラウザ
participant "注文API" as API
database "注文DB" as DB

顧客 -> ブラウザ: 注文する
ブラウザ -> API: POST /orders
API -> DB: 注文を保存
DB --> API: 注文ID
API --> ブラウザ: 201 Created
ブラウザ -> 顧客: 確認を表示
@enduml

参加者の表示ラベルは引用符で囲むことができ、としてメッセージで使用するための短いエイリアスを提供します。一般的な参加者のキーワードにはactor, participant, boundary, control, entity, database、およびコレクション参加者の役割を最も適切に伝えるキーワードを使用してください。特定のアーキテクチャを強制するものではありません。

2. メッセージと時間の読み取り

各メッセージは、送信者、矢印、受信者、およびラベルとして記述されます。メッセージ行の順序は、図におけるそれらの縦の順序を決定します。

• ->は実線のメッセージ矢印で、リクエストや呼び出しによく使用されます。

• -->は点線の矢印で、応答や戻り値によく使用されます。

• ->>および-->>一般的なPlantUMLスタイルでは、開いた矢印頭部を使用します。

• : テキストはメッセージラベルを追加します。

呼び出しと応答に対して一貫した規約を選択してください。UML図は相互作用を伝達するものであり、実装が描かれたプロトコルに従うことを自動的に保証するものではありません。

3. アクティベーションと参加者のライフタイム

アクティベーションは、参加者が作業を行っている時期を示すことができます。activateおよび非アクティブ化、または省略形++および--メッセージ矢印上。

@startuml
actor ユーザー
participant "ログイン API" を API
database ユーザー

ユーザー -> API: 認証情報を送信
API をアクティブ化
API -> ユーザー: アカウントを検索
ユーザーをアクティブ化
ユーザー --> API: アカウントレコード
ユーザーを非アクティブ化
API --> ユーザー: ログイン結果
API を非アクティブ化
@enduml

アクティベーションは、ネストされた呼び出しや責任を明確にする場合に最も役立ちます。図を読みづらくする場合は、機械的にすべてのメッセージに追加しないようにしてください。

4. 条件、代替、および反復

制御フローを示すために結合フラグメントを使用します。fragment キーワードでブロックを開始し、elseは、適用可能な場合に代替項目を分離し、endで閉じます。ガード条件は角括弧内に記述します。

代替パス：altおよびelse

@startuml
actor ユーザー
participant "ログイン API" as API
database ユーザー

ユーザー -> API: ユーザー名とパスワードを送信
API -> ユーザー: 認証情報を確認
ユーザー --> API: 一致結果

alt [認証情報有効]
  API --> ユーザー: セッショントークンを返す
else [認証情報無効]
  API --> ユーザー: 認証エラーを返す
end
@enduml

altは、パスが排他的である場合に適切です。条件が明確になるようなラベルを使用してください。

オプションの動作：opt

@startuml
actor 顧客
participant 購入処理
participant "メールサービス" as Email

顧客 -> 購入処理: 購入を完了
購入処理 --> 顧客: 注文確認

opt [顧客がメールを受け取ることに同意]
  購入処理 -> Email: 領収書を送信
  Email --> 購入処理: 受け入れ
end
@enduml

繰り返し：loop

@startuml
participant "バッチジョブ" as Job
participant "支払いAPI" as API

loop [保留中の支払いごとに]
  Job -> API: 支払いを送信
  API --> Job: 支払い結果
end
@enduml

繰り返しアクションをフラグメント内に配置し、ループの条件またはスコープを明確に記述してください。

5. 並行およびグループ化された相互作用

使用par相互作用が並行して発生する場合、または順序が重要でない場合に使用します。group特定の制御フロー構造を暗示せずに、メッセージのセットにラベルを付けるために使用します。

@startuml
participant "Order Service" as Orders
participant "Inventory Service" as Inventory
participant "Notification Service" as Notify

Orders -> Orders: Order accepted

par 在庫の確保
  Orders -> Inventory: 商品の確保
  Inventory --> Orders: 予約結果
else 顧客への通知
  Orders -> Notify: 注文更新を送信
  Notify --> Orders: 承認
end
@enduml

使用 par 並行処理が意味を持つ場合のみ使用してください。あるアクションが別のアクションの開始前に完了する必要がある場合は、代わりにメッセージを順次表示してください。

6. 注釈、参照、および視覚的なグループ化

注釈は、前提条件、制約、または意思決定を明確にすることができます。ref フラグメントは、読者を別の図または別々に文書化されたインタラクションに案内することができます。

@startuml
actor Customer
participant "Checkout UI" as UI
participant "Payment Service" as Pay
participant "Fraud Check" as Fraud

Customer -> UI: 注文の支払い
UI -> Pay: 支払いの承認
Pay -> Fraud: 取引の評価

note right of Fraud
  リスクルールはこのインタラクションの外で管理されます。
end note

Fraud --> Pay: リスク結果
Pay --> UI: 承認結果
UI --> Customer: 結果を表示
@enduml

注釈はメッセージラベルを繰り返すのではなく、文脈を追加するべきです。図が混雑する場合は、焦点を絞ったシナリオに分割し、参照やドキュメントリンクを使用してそれらを接続してください。

7. VPasCode での図の作成と洗練

VPasCodeは、ライブレンダリングを備えた PlantUML 編集機能と、AI 支援による図の生成、コードの修正、および構文の修正をサポートします。正確なインターフェースや機能の利用可否は変更される場合がありますが、一般的なワークフローは以下の通りです。

1. VPasCode を開き、PlantUML を選択するか入力します。

2. 相互作用を記述するか、PlantUML のドラフトをエディタに貼り付けます。

3. ソースを洗練させる際に、レンダリングされたプレビューを確認します。

4. AI に特定の変更を依頼します。例えば、「alt.”

5. 生成されたコードと図を、構文とシステムの両方の観点から検証します。

6. エディタで利用可能なオプションを使用して、完成した図をエクスポートまたは共有します。

効果的なプロンプトでは、AI に図の種類、アクター、システム境界、主要な成功パス、重要な代替パス、および詳細レベルを伝えます。例えば：

Web アプリへの顧客ログインのための PlantUML シーケンス図を作成してください。Browser、Login API、Identity Provider、User DB を含めてください。成功したログインパスと、無効なパスワードの代替パスを示してください。簡潔なラベルを使用し、これら以外のサービスを考案しないでください。

生成されたコードはドラフトとして扱ってください。参加者、矢印、条件、エラーパスが、単に plausible な流れではなく、実際のシステムを反映しているか確認してください。

8. より詳細な例：支払い失敗を伴うチェックアウト

この例では、参加者のエイリアス、アクティベーション、および代替パスを組み合わせています。

@startuml
title 購入と支払い承認

actor 顧客
boundary "購入 UI" as UI
control "注文サービス" as Orders
participant "支払いゲートウェイ" as Pay
database "注文 DB" as DB

顧客 -> UI: 購入を送信
UI -> Orders: 保留中の注文を作成
activate Orders

Orders -> DB: 保留中の注文を保存
DB --> Orders: 注文 ID

Orders -> Pay: 支払いを承認
activate Pay

alt [支払い承認]
  Pay --> Orders: 承認コード
  deactivate Pay

  Orders -> DB: 注文を確認済みとしてマーク
  DB --> Orders: 更新完了
  Orders --> UI: 注文確認
  UI --> 顧客: 確認を表示
else [支払い拒否]
  Pay --> Orders: 拒否理由
  deactivate Pay

  Orders -> DB: 注文失敗としてマーク
  DB --> Orders: 更新完了
  Orders --> UI: 支払い拒否
  UI --> 顧客: 再試行オプションを表示
end

deactivate Orders
@enduml

図の順序が実際の動作と一致しているか確認してください。例えば、システムが承認に成功した後にのみ注文を永続化する場合、データベースのメッセージをその設計に合わせて移動してください。

9. 実践的なモデリングのガイドライン

• 図は焦点を絞って作成してください。1 つのシナリオ、または密接に関連する一連のパスを示してください。主要な相互作用から注意をそらす詳細な内容は分割してください。

• 参加者は責任に基づいて名前を付けてください。「注文サービス」や「支払いゲートウェイ」のような具体的なラベルを、「システム.

• 」のような曖昧なラベルを避けてください。意味のある境界を示してください。ユーザー、クライアント、内部サービス、データベース、外部システムを区別し、それが責任の理解を助ける場合に使用してください。

• 明確なメッセージラベルを使用してください。操作、イベント、または重要な結果を含め、「プロセス」という言葉だけのラベルは避けてください。

• 重要な障害経路をモデル化してください。タイムアウト、拒否、リトライ、またはバリデーション失敗など、シナリオに影響を与える場合はそれらを含めてください。

• フラグメントを正確に使用してください。 altは代替経路を意味し、optはオプションの動作を意味し、loopは反復を意味し、parは並列動作を意味します。

• 実装のノイズを避けてください。聴衆が必要としない限り、すべてのゲッター、内部メソッド、または低レベルの詳細を図示しないでください。

• ソースを保守可能に保ってください。長い名前にはエイリアスを使用し、一貫した命名規則を適用し、重要な前提条件については短いコメントまたは注記を追加してください。

10. 一般的なエラーとレビューチェックリスト

図がレンダリングされない場合は、@startumlおよび@endumlが存在する場合、フラグメントブロックは対応するend文、エイリアスが一貫して使用されており、すべてのメッセージエンドポイントが定義された参加者を参照していることを確認してください。また、PlantUML ソースに誤って貼り付けられた他の図記法言語の構文がないかも確認してください。

共有する前に、2 つの点を確認してください：

• 構文：正しくレンダリングされますか？フラグメントは閉じられていますか？参加者とエイリアスは整合していますか？

• 意味：参加者とメッセージの方向は正しいですか？重要なエラーパスは含まれていますか？外部システムとデータストアは正確に表現されていますか？

最も強力なコードとしての図のワークフローは、読みやすいソースコード、迅速な視覚的フィードバック、およびドメインレビューを組み合わせます。PlantUML は相互作用の表記法に対する明示的な制御を提供しますが、VPasCodeはドラフト作成と反復を高速化できますが、図の正確性に関する最終的な権威は、依然としてその図が記述すべきシステム動作です。