最小限の有効なUML：ソフトウェアシステムのモデリングのための実践的ガイド

UMLは、コミュニケーションと意思決定を改善する際に最も有用であり、単なるドキュメント作成の練習になる際にはそうではありません。チームがすべてのUML図のタイプを必要とするのは稀です。ほとんどのプロジェクトでは、7つの図のタイプが堅固な基盤を提供します：

1. ユースケース図

2. アクティビティ図

3. シーケンス図

4. クラス図

5. コンポーネント図

6. デプロイメント図

7. 状態機械図

これら図は、補完的な視点からシステムを記述します：

• 目標： ユーザーと外部システムが必要とするもの

• 振る舞い： 作業がシステム内をどのように流れるか

• 相互作用： オブジェクトとサービスがどのように協力するか

• 構造： どのようなエンティティと関係が存在するか

• アーキテクチャ： 主要なソフトウェア部品がどのように組織化されているか

• 運用： システムがどこで実行されるか

• ライフサイクル： 重要なオブジェクトが時間とともにどのように変化するか

目標は、考えられるすべての懸念に対して1つの図を作成することではありません。目標は、ステークホルダーが実際に持っている質問に答える、最小限の整合性のあるモデルセットを作成することです。

1. 「最小限の有効なUML」とは何か

最小限の有効なUMLは、4つの原則に基づくモデリング戦略です：

• 意思決定のためのモデリング：要件、設計の選択、リスク、または実装の詳細を明確にするために図を作成する。

• 最も単純で十分な表記法を使用する：不要の記号、装飾、詳細は避けてください。

• トレーサビリティを維持する：必要に応じて、要件を振る舞い、構造、コード、テスト、デプロイメントに接続してください。

• 図は理解しやすく保つ：すべてを含んだ図は、しばしば何も伝えない。

有用なモデルは、以下のような質問に答える手助けをするべきです：

• 誰がシステムと相互作用しますか？

• システムが提供する必要がある機能は何ですか？

• ビジネスプロセスを構成するステップは何ですか？

• 各アクションの責任を持つオブジェクトまたはサービスはどれですか？

• 表現しなければならないデータとドメインの概念は何ですか？

• サブシステムはどのように分割されますか？

• アプリケーション、データベース、外部サービスはどこにデプロイされますか？

• 重要なエンティティはライフサイクルをどのように通過しますか？

図がこれらの質問のいずれかに答えるのを助けない場合、それは不要である可能性があります。

2. 7 つの図の核心

これらの図は独立していません。それらは連鎖を形成します：

状態機械図は、意味のある状態を持つオブジェクトのライフサイクルを記述することで、この連鎖全体にわたって横断します。

例えば、オンライン注文は以下のように表すことができます：

• ユースケース：注文を行う

• アクティビティ：カートの検証、支払いの承認、在庫の確保、注文の確認

• シーケンス：顧客インターフェースが注文サービス、支払いサービス、在庫サービスを呼び出す

• クラス： 注文, 注文行, 支払い、および製品

• コンポーネント：Web アプリケーション、注文サービス、支払いアダプター、在庫サービス

• デプロイ：ブラウザ、アプリケーションクラスタ、データベース、支払いプロバイダー

• 状態機械：下書き → 支払い待ち → 支払い済み → 出荷済み → 配達済み

3. ユースケース図：システムの目標の定義

ユースケース図は、システムを外部から提示します。これは、システムと相互作用するアクターと、それらが追求する目標を特定します。

3.1 ユースケース図が含むもの

主な要素は次の通りです：

• システム境界：モデル化されているシステム内のものを定義する

• アクター:人、組織、デバイス、または外部システム

• ユースケース:システムが提供する目標またはサービス

• 関連:アクターとユースケース間の接続

• 包含関係:他のユースケースによって必要とされる再利用可能な振る舞い

• 拡張関係:オプションまたは条件付きの振る舞い

例:

@startuml
左から右の方向

actor Customer
actor "支払いプロバイダー" as PaymentProvider
actor "倉庫システム" as Warehouse

rectangle "オンラインストア" {
  usecase "製品を閲覧" as UC1
  usecase "注文を提出" as UC2
  usecase "支払い承認" as UC3
  usecase "注文履行" as UC4
}

Customer --> UC1
Customer --> UC2
UC2 ..> UC3 : <<include>>
PaymentProvider --> UC3
Warehouse --> UC4
@enduml

3.2 アクターを正しく特定する

アクターは必ずしも人間の役割ではありません。システムと相互作用する外部のあらゆるものです。

考えられるアクターには以下が含まれます:

• 顧客

• サポート担当者

• 管理者

• 支払いゲートウェイ

• IDプロバイダー

• 倉庫管理システム

• スケジュールされたジョブ

• モバイルアプリケーション

• IoTデバイス

アクターに内部実装の詳細に基づいて名前を付けないでください。「RESTコントローラー」は通常アクターではありません。「パートナーアプリケーション」はアクターである可能性があります。

3.3 ユースケースを目標として命名する

良いユースケース名は結果を記述します:

• 経費精算書を提出する

• 購入依頼を承認する

• 新規患者を登録する

• 請求書を生成する

• パスワードをリセットする

弱体な名称は実装メカニズムを記述している：

• API を呼び出す

• SQL クエリを実行する

• フォームを開く

• コントローラーを呼び出す

ユースケースは次の点を答えるべきである：

アクターはシステムを使ってどのような意味のある結果を達成したいと考えているか？

3.4 include と extend を使用するタイミング

使用：<<include>>ある振る舞いが別の振る舞いの一部として常に必要である場合。

例：

• 「注文を確定する」は「合計金額を計算する」を含む

• 「アカウントを登録する」は「メールを検証する」を含む

使用：<<extend>>振る舞いがオプションまたは条件付きである場合。

例：

• 「注文を確定する」は「プロモーション割引を適用する」によって拡張される可能性がある

• 「サインイン」は「多要素認証を完了する」によって拡張される可能性がある

単に図をより洗練された見せかけにするためにこれらの関係を使用しないでください。多くの場合、短い文章によるシナリオやアクティビティ図の方が明確です。

3.5 ユースケース図が示さないもの

ユースケース図は次のものを記述することを意図していません：

• 詳細なユーザーインターフェースのレイアウト

• 正確な実装クラス

• データベーステーブル

• メッセージの順序

• アルゴリズムの論理

• インフラストラクチャのトポロジ

これらは範囲と目標を定義します。他の図は詳細を提供します。

4. アクティビティ図：ワークフローとプロセスのモデリング

アクティビティ図は、作業がどのように進行するかを示します。これらは、ビジネスプロセス、ワークフロー、分岐ロジック、並列作業、および例外処理に特に効果的です。

4.1 核心要素

アクティビティ図では一般的に以下を使用します：

• 初期ノード

• アクション

• 分岐ノード

• 結合ノード

• フォークとジョイン

• スイムレーン

• 最終ノード

• ガード（例：[承認済み] または [却下済み]

例：

@startuml
|顧客|
start
:注文を送信;

|注文サービス|
:注文を検証;

if (注文は有効？) then (はい)
  :合計を計算;

  fork
    |支払いサービス|
    :支払いを承認;
  fork again
    |在庫サービス|
    :在庫を予約;
  end fork

  |注文サービス|
  :注文を確認;
  stop
else (いいえ)
  :検証エラーを返す;
  stop
endif
@enduml

4.2 スイムレーンを使用して責任を示す

スイムレーンは、各アクションをどの役割、システム、またはコンポーネントが実行するかを明確にします。

有用なレーンは以下を表す場合があります：

• 顧客

• カスタマーサービス担当者

• 注文サービス

• 決済プロバイダー

• 倉庫

• 自動スケジューラー

スイムレーンは、プロセスが組織間またはシステム間の境界をまたぐ場合に特に価値があります。

4.3 意思決定を明示的にモデル化する

意思決定には意味のあるガード条件が必要です：

[決済承認]
[決済拒否]

曖昧なラベルは避けてください。例：

[はい]
[いいえ]

ただし、意思決定の質問が直ちに明白な場合は除きます。

4.4 並行性が重要である場合に表示する

フォークとジョインは、アクティビティが並行して発生する場合に役立ちます。例えば、注文が検証された後：

• 決済の承認が行われる可能性があります

• 在庫が予約される可能性があります

• 不正チェックが実行される可能性があります

ただし、タイミング、整合性、障害処理、またはシステム設計に影響を与える場合のみ、並行性をモデル化してください。図をより複雑に見せるためだけに並行ブランチを使用しないでください。

4.5 アクティビティ図と要件

アクティビティ図は、欠落している要件を明らかにすることができます。例えば、承認プロセスをモデル化している間、チームは未回答の質問を発見する可能性があります：

• 承認者が利用できない場合どうなりますか？

• リクエストは拒否されてから再提出できますか？

• エスカレーションまでの時間はどれくらいですか？

• 2 人が同時に承認することはできますか？

• 下流システムが利用できない場合どうなりますか？

これにより、実装が始まる前にアクティビティ図が有用になります。

5. シーケンス図：時間経過に伴う協力の説明

シーケンス図は、参加者が時間順の相互作用の中でメッセージをどのように交換するかを示します。これらは重要なシナリオを詳細に記述するのに理想的です。

5.1 主要な要素

シーケンス図には通常、以下が含まれます：

• アクター

• オブジェクトまたはサービス

• ライフライン

• メッセージ

• 応答メッセージ

• アクティベーションバー

• 条件

• ループ

• 代替パス

• 非同期メッセージ

例:

@startuml
actor Customer
boundary "Web App" as Web
control "Order Service" as Order
control "Payment Service" as Payment
database "Order DB" as DB

Customer -> Web : 注文を送信
Web -> Order : createOrder(cart)

Order -> DB : save(order)
DB --> Order : orderId

Order -> Payment : authorize(amount)

alt 支払い承認
  Payment --> Order : 承認
  Order -> DB : updateStatus(PAID)
  Order --> Web : 確認
  Web --> Customer : 確認を表示
else 支払い拒否
  Payment --> Order : 拒否
  Order -> DB : updateStatus(PAYMENT_FAILED)
  Order --> Web : 支払いエラー
  Web --> Customer : エラーを表示
end
@enduml

5.2 シナリオを戦略的に選択する

すべてのユースケースに対してシーケンス図を作成しないでください。以下のシナリオから始めましょう:

• ビジネス上重要

• 技術的にリスクが高い

• 統合が複雑

• セキュリティが重要

• トランザクション処理

• 理解が難しい

• アーキテクチャ上の問題を露呈しやすい

典型的な例には以下が含まれます:

• ユーザー認証

• 支払い処理

• ファイルアップロード

• 注文送信

• パスワードリセット

• イベント公開

• 障害回復

• バックグラウンドジョブの実行

5.3 同期および非同期の相互作用を区別する

同期呼び出しとは、送信側が応答を待つことを意味します。非同期メッセージでは、送信側は処理を継続できます。

この区別は以下に影響を与えます:

• ユーザーエクスペリエンス

• トランザクションの境界

• エラー処理

• スケーラビリティ

• リトライ動作

• 観測可能性

異なる記法を一貫して使用し、重要な非同期の動作については注釈または付随するテキストで説明してください。

5.4 障害パスのモデル化

成功パスのみを示すシーケンス図は、重大な設計リスクを隠す可能性があります。「alt, opt」、および「loop」フラグメントを使用して、以下を示してください:

• バリデーションの失敗

• 認証の失敗

• タイムアウト

• リトライ

• 部分的な失敗

• 重複リクエスト

• サービスの利用不可

• 補償またはロールバック

例:

@startuml
クライアント -> API : リクエスト送信

API -> サービス : リクエスト処理

alt サービスが応答
  サービス --> API : 結果
  API --> クライアント : 成功
else タイムアウト
  API -> サービス : リクエスト再試行
  alt 再試行成功
    サービス --> API : 結果
    API --> クライアント : 成功
  else 再試行失敗
    API --> クライアント : 一時的な失敗
  end
end
@enduml

5.5 過度に詳細なシーケンス図を避ける

すべての内部メソッド呼び出しを含めると、シーケンス図は保守が困難になります。意味のある責任と境界に焦点を当ててください:

• ユーザーインターフェース

• アプリケーションサービス

• ドメインオブジェクト

• リポジトリ

• 外部サービス

• メッセージブローカー

• データベース

詳細な実装図はデバッグ中に有用である場合がありますが、主要なアーキテクチャドキュメントとなるべきではありません。

6. クラス図: 構造とドメイン概念の記述

クラス図は静的構造を示します。これらは以下のいずれかを記述できます:

• 概念的なドメインモデル

• 設計レベルのオブジェクトモデル

• 実装指向のクラス構造

これらは異なる抽象化のレベルであり、安易に混同すべきではありません。

6.1 概念的クラス図と実装クラス図

概念的モデルには以下が含まれる可能性があります:

• 顧客

• 注文

• 製品

• 支払い

実装モデルには以下が含まれる可能性があります:

• 注文コントローラー

• 注文アプリケーションサービス

• 注文リポジトリ

• 支払いゲートウェイアダプター

どちらも有効ですが、異なる問いに答えるものです。

6.2 中核的な関係

一般的な関係には以下が含まれます：

• 関連

• 集約

• 合成

• 一般化

• 依存

• 実現

関係は慎重に使用してください。多くの場合、集約と合成の複雑な区別よりも、単純な関連の方が明確です。

例：

@startuml
class Customer {
  +id: CustomerId
  +name: String
  +email: EmailAddress
}

class Order {
  +id: OrderId
  +status: OrderStatus
  +total(): Money
  +submit()
}

class OrderLine {
  +quantity: int
  +unitPrice: Money
  +lineTotal(): Money
}

class Product {
  +sku: String
  +name: String
}

Customer "1" -- "0..*" Order : places
Order "1" *-- "1..*" OrderLine : contains
OrderLine "*" --> "1" Product : refers to
@enduml

6.3 多重性は重要である

多重性は制約を表します：

• 1 — ちょうど1つ

• 0..1 — オプション（任意）

• * — 多数

• 1..* — 1つ以上

例えば：

Customer "1" -- "0..*" Order

これは、各注文は1人の顧客に属することを意味しますが、顧客は0件以上の注文を持つ可能性があります。

6.4 データフィールドだけでなく、責任をモデル化する

クラス図は、振る舞いがどこに属するかを説明するのに役立つべきです。意味のある操作を持つドメインオブジェクトは、単なるゲッターとセッターを含むクラスセットよりも、多くの場合、より情報量が多いです。

例えば：

Order.submit()
Order.cancel()
Order.calculateTotal()
Payment.authorize()

具体的な操作は設計アプローチに依存しますが、原則は一定です：

重要な業務責任は、それらを所有する概念の近くに配置してください。

6.5 クラス図をデータベーススキーマに変換しない

クラス図は自動的にリレーショナルスキーマではありません。永続化設計が特定の目的でない限り、すべてのデータベース列を追加しないでください。

有用な区別は次の通りです：

• ドメインモデル：ビジネス概念とルール

• 設計モデル：ソフトウェアクラスと責任

• データモデル：テーブル、キー、インデックス、および制約

これらは関連しているかもしれませんが、混同すべきではありません。

7. コンポーネント図：アーキテクチャ境界の表示

コンポーネント図は、システムの主要な交換可能またはデプロイ可能な部分と、それらが相互作用するインターフェースを記述します。

これらは、以下の問いに答えるのに役立ちます：

• 主要なサブシステムは何ですか？

• どのコンポーネントが責任を所有していますか？

• 各コンポーネントは何を提供しますか？

• 各コンポーネントは何を必要としますか？

• 統合境界はどこにありますか？

• どの依存関係が安定しているか、またはリスクがありますか？

例：

@startuml
component "Web Application" as Web
component "Order Service" as Order
component "Payment Adapter" as Payment
component "Inventory Service" as Inventory
database "Order Database" as DB
cloud "External Payment Provider" as Provider

Web --> Order : REST API
Order --> Payment : Payment interface
Order --> Inventory : Inventory API
Order --> DB : Persistence
Payment --> Provider : Provider API
@enduml

7.1 コンポーネント図はパッケージ図ではありません

パッケージ図はモデル要素をグループ化し、通常は整理のために行われます。コンポーネント図は、機能を提供および消費するアーキテクチャユニットを記述します。

コンポーネントは次のようなものになり得ます：

• デプロイ可能なサービス

• Webアプリケーション

• モバイルアプリケーション

• ライブラリ

• メッセージブローカー

• 外部プラットフォーム

• データベース

• サードパーティ製統合

適切なレベルはアーキテクチャに依存します。

7.2 契約を明確にする場合にインターフェースを表示する

インターフェースは依存関係をより明確にします：

@startuml
interface PaymentGateway

component "Order Service" as Order
component "Payment Adapter" as Adapter

Order ..> PaymentGateway
Adapter - PaymentGateway
@enduml

これは、注文サービスが特定の提供者ではなく抽象化に依存していることを示しています。

7.3 構造的決定を支援するためにコンポーネント図を使用する

コンポーネント図は、短い設計ノートと組み合わせることでより価値が高まります：

• なぜこの境界が存在するのか？

• データを所有するのは誰か？

• 相互作用は同期型か非同期型か？

• 依存関係が失敗した場合、何が起こるか？

• コンポーネントは独立してデプロイ可能か？

• どのようなセキュリティ境界を表しているか？

• どのような整合性の保証が存在するか？

図はすべての答えを含める必要はありませんが、重要な答えに注意を向けるべきです。

8. デプロイメント図：ソフトウェアとインフラストラクチャの接続

デプロイメント図は、ソフトウェアアーティファクトが実行される物理的または仮想環境を示します。

これらは以下の問いに答えるのに役立ちます：

• 各アプリケーションはどこで実行されますか？

• どのノードが通信しますか？

• データベースはどこに配置されていますか？

• どのサービスが外部からアクセス可能ですか？

• どのようなネットワーク境界が存在しますか？

• システムはどのように分散されていますか？

• どのインフラストラクチャの選択が信頼性やパフォーマンスに影響しますか？

例：

@startuml
node "ユーザーデバイス" as Device {
  artifact "ブラウザ" as Browser
}

node "クラウドリージョン" as Cloud {
  node "Web 層" as WebTier {
    artifact "Web アプリケーション" as WebApp
  }

  node "アプリケーション層" as AppTier {
    artifact "注文サービス" as OrderSvc
    artifact "支払いアダプター" as PaymentSvc
  }

  database "注文データベース" as DB
}

cloud "支払いプロバイダー" as Provider

Browser --> WebApp : HTTPS
WebApp --> OrderSvc : HTTPS
OrderSvc --> DB : TLS
OrderSvc --> PaymentSvc
PaymentSvc --> Provider : HTTPS
@enduml

8.1 ノード、アーティファクト、および環境を区別する

• 「ノードは、サーバー、コンテナ、デバイス、仮想マシン、または管理プラットフォームなどの実行環境です。

• 「アーティファクトは、バイナリ、コンテナイメージ、パッケージ、またはアプリケーションなどのデプロイ可能なソフトウェアユニットです。

• 「環境は、開発、テスト、ステージング、または本番などを表す場合があります。

8.2 運用上重要な詳細を含める

目的に応じて、デプロイメント図は以下を示す場合があります：

• ロードバランサー

• ファイアウォール

• ネットワークゾーン

• コンテナクラスター

• 可用性ゾーン

• データベースおよびレプリカ

• キャッシュ

• メッセージブローカー

• オブジェクトストレージ

• 外部サービス

• 監視およびログシステム

文書化されている意思決定に影響を与えないインフラの詳細は追加しないでください。

8.3 リスク分析にはデプロイメント図を使用する

デプロイメントモデリングは以下を明らかにできます：

• 単一障害点

• 露出したデータベース

• 欠落したネットワーク境界

• 過度なリージョン間トラフィック

• フェイルオーバー戦略のない依存関係

• 環境間の不十分な分離

• 暗号化されていない接続

• 非現実的なスケーリングの仮定

9. 状態機械図：ライフサイクルのモデリング

状態機械図は、エンティティが状態間を移動することでイベントにどのように応答するかを記述します。

オブジェクトの動作が現在の状態に強く依存する場合、これらは非常に有用です。

一般的な例には以下が含まれます：

• 注文

• 支払い

• 出荷

• サポートチケット

• ユーザーアカウント

• ワークフローリクエスト

• サブスクリプション

• ドキュメント

• デバイス

• ジョブ実行

例：

@startuml
[*] --> 下書き

下書き --> 支払い待ち : 送信
支払い待ち --> 支払い完了 : 支払い承認
支払い待ち --> 支払い失敗 : 支払い拒否
支払い失敗 --> 支払い待ち : 支払い再試行
支払い完了 --> 処理中 : 履行開始
処理中 --> 発送済み : 発送
発送済み --> 配達完了 : 配達確認
支払い完了 --> キャンセル : キャンセル
処理中 --> キャンセル : 許可されている場合キャンセル
配達完了 --> [*]
キャンセル --> [*]
@enduml

9.1 状態を慎重に定義する

状態は単なるアクションではなく、意味のある条件を表すべきです。

良い状態の例：

• 承認待ち

• 承認済み

• 却下済み

• 支払い失敗

• 発送済み

弱い状態の例：

• ボタンをクリック中

• サービス呼び出し中

• メソッド実行中

アクションはイベントまたは遷移です。状態は持続する条件です。

9.2 遷移ルールを含める

遷移には以下が含まれる場合があります：

• イベント

• ガード条件

• アクション

例：

承認待ち -- 承認 [マネージャー承認] / 承認記録 --> 承認済み

これにより、ビジネスルールが可視化され、テスト可能になります。

9.3 状態機械を使用してテストを導出する

各遷移はテストケースを示唆します：

• 有効な遷移

• 無効な遷移

• ガードの失敗

• 繰り返しイベント

• タイムアウト

• 再試行

• キャンセル

• 回復

注文ライフサイクルにおいて、テストは以下を確認する可能性があります:

• 下書き注文は送信できる

• 配送済みの注文はキャンセルできない

• 支払いの失敗は再試行を許可する

• キャンセルされた注文は支払い済みステータスに戻れない

10. 7つのダイアグラムがどのように連携するか

これらのダイアグラムは、7つの無関係な図ではなく、一貫したモデルを形成すべきである。

「経費報告書の提出」機能について考えてみましょう。

ユースケース

• 従業員が経費報告書を提出する

• 管理者が経費報告書を承認する

• 財務担当者が払い戻し処理を行う

アクティビティ

• 経費を入力する

• 領収書を添付する

• データを検証する

• 報告書を提出する

• 管理者にルーティングする

• 承認または拒否する

• 財務へ送信する

シーケンス

• 従業員インターフェースが経費サービスに呼び出しを行う

• 経費サービスが報告書を検証する

• 領収書サービスが添付ファイルを保存する

• ワークフローサービスがマネージャーを割り当てる

• 通知サービスがアラートを送信する

クラス

• 従業員

• 経費精算報告書

• 経費項目

• 領収書

• 承認

• 立替払い

コンポーネント

• ウェブアプリケーション

• 経費サービス

• 領収書保管

• ワークフローサービス

• 通知サービス

• 財務統合

デプロイ

• ブラウザ

• ウェブ層

• アプリケーションクラスター

• オブジェクトストレージ

• リレーショナルデータベース

• 財務プラットフォーム

状態機械

下書き → 送信済み → 審査中 → 承認済み → 立替払い完了
                         ↓
                      却下

各図は、他の図をすべて重複させることなく、異なる視点を追加します。

11. 作成する図の選択

実用的な選択プロセスは、チームがどのような不確実性を持っているかを尋ねることです。

すべての機能にすべての図が必要であるわけではありません。

軽量な意思決定ルール

以下のいずれかが真である場合に図を作成してください：

• 複数の利害関係者が要件を異なるように解釈している。

• プロセスには重要な分岐または並列動作がある。

• シナリオは複数のシステム境界を横断する。

• ドメインオブジェクトには非自明なルールがある。

• アーキテクチャの決定を伝達する必要がある。

• デプロイメントトポロジは信頼性、セキュリティ、またはパフォーマンスに影響を与える。

• ライフサイクルルールは文章で説明するのが難しい。

• この図は実装、レビュー、テスト、または運用で再利用される。

テンプレートで図が期待されているからといって、単に図を作成することを避けてください。

12. 詳細レベル

強力なモデリングプラクティスは、複数の抽象化レベルを使用します。

コンテキストレベル

システムと主要な外部アクターまたはシステムを示します。

用途：

• 範囲

• 利害関係者とのコミュニケーション

• システムの境界

コンテナまたはサブシステムレベル

アプリケーション、サービス、データベース、および主要な統合を示します。

用途：

• アーキテクチャ

• 所有権

• デプロイメント計画

コンポーネントレベル

内部のアーキテクチャ部品とインターフェースを示します。

用途：

• 詳細設計

• 依存関係のレビュー

• チームの境界

コードレベル

クラス、メソッド、および実装の依存関係を示します。

用途：

• 開発者の作業

• リファクタリング

• デバッグ

すべてのレベルを1つの図に配置しないでください。コンテキスト図にはすべてのクラスを含めるべきではなく、クラス図は生産ネットワーク全体を表現しようとすべきではありません。

13. Visual Paradigm UML

Visual Paradigmは、グラフィカルなモデリングと統合ドキュメントを好むチームに適しています。

用途は以下の通りです：

• UML図を対話的に作成する

• モデルリポジトリの維持

• 図と要件をリンクする

• トレーサビリティ関係の作成

• ドキュメントの作成

• 共有モデリング環境を通じた共同作業

• 選択した成果物の生成またはリバースエンジニアリング

• ナビゲーションおよび整理機能を用いた大規模モデルの管理

13.1 強み

グラフィカルなUMLツールは特に以下の場合に役立ちます：

• アナリストや非開発者が図を編集する必要がある場合

• 利害関係者が視覚的な操作を好む場合

• プロジェクトで正式なモデルの整理が必要な場合

• トレーサビリティが重要である場合

• チームが中央リポジトリを維持している場合

• ドキュメントを一貫して生成する必要がある場合

13.2 推奨される使用方法

以下の利点があるモデルビューにはVisual Paradigmを使用してください：

• インタラクティブなレイアウト

• 詳細な注釈

• 図間ナビゲーション

• 正式なリポジトリ管理

• トレーサビリティ

• 利害関係者向けワークショップ

ツールにモデリング戦略を決定させないでください。まず決定してください：

• その図がどの意思決定を支援するか

• 誰がそれを読むか

• どの程度の詳細さが適切か

• どのように維持されるか

• モデルが要件またはコードと連携する必要があるかどうか

13.3 リポジトリの規律

共有モデルリポジトリは、ソースコード管理と同じプラクティスから恩恵を受けます：

• 命名規則を確立する

• 主要なモデル領域の所有権を割り当てる

• 重要な変更を確認する

• 不要な重複した図を避ける

• 古くなったビューをアーカイブする

• 重要な図の目的を記録する

• モデル要素の一貫した命名を維持する

14. VPasCodeとテキストベースモデリング

VPasCodeは、Visual Paradigmエコシステム内でテキスト指向のモデリングアプローチをサポートします。このスタイルは、図をソースアーティファクトのように振る舞わせたいチームに役立ちます。

テキストベースの図は以下を提供できます：

• バージョン管理との互換性

• コードレビュー

• ブランチ作成とマージ

• 自動生成

• 再現可能なビルド

• バッチ更新の容易さ

• ソースコードおよびドキュメントへの近接性

テキストベースのモデルは次のように見えるかもしれません：

actor Customer
usecase "Place Order" as PlaceOrder
Customer --> PlaceOrder

正確な構文はツールとワークフローに依存しますが、より広い利点は、図がグラフィカルファイルだけでなく編集可能なテキストとして表現されることです。

14.1 テキストベースモデリングがうまく機能する状況

以下の状況でテキストベースの図を使用してください：

• 開発者がモデルを維持する

• 図が頻繁に変更される

• チームがGitまたは他のバージョン管理システムを使用している

• レビュー担当者がテキスト変更を検査したい

• 図がドキュメントの一部として生成される

• 複数のブランチが独立して進化する必要がある

14.2 潜在的な制限

以下の状況では、テキストベースモデリングはあまり便利でない場合があります：

• ビジネス関係者が図を直接編集する必要がある

• レイアウトを手動で最適化する必要がある

• モデルには豊富な視覚的注釈が含まれています

• チームは図の構文に慣れていません

• リポジトリには洗練された視覚的ナビゲーションが必要です

ハイブリッドアプローチはしばしば効果的です：コード指向のアーキテクチャにはテキストベースの図を、利害関係者向けの分析にはグラフィカルツールを使用します。

15. PlantUML

PlantUMLは、プレーンテキストからUMLおよび関連するアーキテクチャ図を生成できる人気のあるテキストベースの図描画アプローチです。

例：

@startuml
actor User
participant "Web App" as Web
participant "Application Service" as App
database Database

User -> Web : リクエスト
Web -> App : 操作を実行
App -> Database : データの読み書き
Database --> App : 結果
App --> Web : 応答
Web --> User : 結果を表示
@enduml

15.1 利点

PlantUMLは価値があります。なぜなら図は以下のようにできるからです：

• ソースコードの隣に保存できる

• プルリクエストでレビューできる

• 自動的に生成できる

• 単純なテキスト編集で更新できる

• Markdownやドキュメントパイプラインに含められる

• 環境間で一貫して生成される

15.2 PlantUMLファイルの整理

実用的なリポジトリ構造は以下のようになるかもしれません：

docs/
  architecture/
    system-context.puml
    components.puml
    deployment.puml
  workflows/
    place-order.puml
    refund-payment.puml
  domain/
    order-model.puml
    order-lifecycle.puml

説明的な名前を使用し、ツールではなく目的に基づいて図を整理してください。

15.3 生成された画像を真実のソースから除外する

可能であれば：

• 保存する.pumlファイルを権威あるソースとして保存する

• ドキュメントビルド時にPNG、SVG、またはPDFファイルを生成する

• 生成された画像を手動で編集しない

• 自動化環境で図が正常にレンダリングされることを検証する

15.4 一貫したスタイルを使用する

小さな視覚的語彙を定義する:

• 外部システムには1色を使用する

• 内部サービスには1色を使用する

• データベースには1色を使用する

• 非同期メッセージングには1つの記法を使用する

• インターフェースには1つの命名規則を使用する

• セキュリティ境界を表す方法は1つに統一する

装飾よりも一貫性の方が価値がある。

16. AI支援によるUMLモデリング

AIはモデリングを加速できるが、権威としてではなくモデリングの補助ツールとして扱うべきである。

AIは以下の用途に有用である:

• 要件を候補となるユースケースに変換する

• アクターと目標を抽出する

• アクティビティフローを提案する

• PlantUMLを生成する

• シーケンスの参加者を提案する

• ドメインエンティティを特定する

• 欠落している代替パスを検出する

• 図の一貫性をレビューする

• 図からドキュメントを生成する

• グラフィカル表現とテキスト表現の間で変換する

• 状態遷移からテストのアイデアを生成する

16.1 生産的なAIワークフロー

信頼できるワークフローは以下の通りである:

1. 要件、制約、およびシステムコンテキストを提供する。

2. AIに前提条件と曖昧さを特定させる。

3. 候補となる図を生成する。

4. 図を実際の要件に対してレビューする。

5. 実装とインフラストラクチャと比較してください。

6. 不正確または捏造された詳細を修正してください。

7. 結果をレンダリングし、視覚的に確認してください。

8. 関連するステークホルダーからのレビューを取得してください。

9. 承認されたモデルをプロジェクトリポジトリに保存してください。

10. システムが変更された際に更新してください。

16.2制約付きでAIにプロンプトを入力する

弱いプロンプト：

注文システムのUML図を作成してください。

より強力なプロンプト：

注文の送信に関するPlantUMLシーケンス図を作成してください。

参加者:
- 顧客
- ウェブアプリケーション
- 注文サービス
- 決済プロバイダー
- 在庫サービス
- 注文データベース

制約:
- 注文が確定する前に決済の承認が行われる必要があります。
- 在庫の予約は、決済承認と並行して発生する可能性があります。
- 決済が拒否された場合、注文は「決済失敗」状態のままにする必要があります。
- タイムアウトは1回だけ再試行する必要があります。
- 成功、拒否、タイムアウトの各パスを示してください。
- ここに記載されていないサービスを捏造しないでください。

制約が明確に記述されるほど、出力にサポートされていないアーキテクチャが含まれる可能性は低くなります。

16.3生成だけでなく、AIに批判を求めてください

有用なレビュー用のプロンプトには以下が含まれます:

• どの要件が表現されていませんか？

• どの分岐が欠落していますか？

• このシーケンス図は状態機械と矛盾していますか？

• 説明されていない依存関係はありますか？

• 責任が誤ったコンポーネントに割り当てられていますか？

• デプロイメントモデルは可用性要件をサポートしていますか？

• どの遷移がテストケースになるべきですか？

• どの仮定の確認が必要です？

16.4一般的なAIモデリングの失敗

AIが生成したモデルは以下の可能性があります:

• アクターやサービスを捏造する

• ビジネスロールと技術コンポーネントを混同する

• サポートされていないデータベーステーブルを追加する

• 同期通信を前提とする

• 失敗パスを省略する

• 所有権を誤って表現する

• UML 関係性を誤って使用する

• 構文上は正しいが意味論的に誤った図を作成する

• 抽象化レベルを混在させる

• 推測を要件として扱う

重要な原則は次の通りです：

AI は素早くドラフトを作成できますが、ドメインおよび技術的なレビューのみが、そのドラフトが真実かどうかを確定できます。

17. UML の現実との整合性検証

図はシステムと整合性が保たれている場合にのみ価値があります。

17.1 要件との整合性検証

確認事項：

• すべての重要な要件が1つ以上のモデルに表れていますか？

• アクターと目標は正しいですか？

• ビジネスルールは表現されていますか？

• 例外は含まれていますか？

• 関連する箇所に非機能要件は反映されていますか？

17.2 実装との整合性検証

確認事項：

• コンポーネントの境界はコードと一致していますか？

• シーケンスの参加者は存在しますか？

• インターフェースとメッセージは正確ですか？

• クラスの責任は現実的ですか？

• 非同期操作は正しく示されていますか？

• 状態遷移は実装によって強制されていますか？

17.3 運用との整合性検証

確認事項：

• デプロイメント図は実際にデプロイできますか？

• ネットワーク接続は現実的ですか？

• 外部システムは表現されていますか？

• 重要箇所にデータベース、キュー、キャッシュ、ストレージは含まれていますか？

• 障害とスケーリングの仮定は妥当ですか？

17.4 ダイアグラム間での検証

以下のような矛盾がないか確認する：

• ユースケースで、システムコンテキストに含まれていないアクターが名前付けられている

• シーケンスダイアグラムが、アーキテクチャに示されていないコンポーネントを呼び出している

• 状態マシンが、ビジネスルールでサポートされていない遷移を許可している

• クラス図が 1 対多を示しているのに対し、データベースは 1 対 1 を強制している

• デプロイメントダイアグラムが、シーケンスダイアグラムで必要とされているサービスを省略している

• アクティビティダイアグラムが並列操作を示しているのに対し、実装は厳密に逐次的である

ダイアグラム間の整合性は、個々のダイアグラムの芸術的品質よりもしばしば重要である。

18. 追跡可能性

追跡可能性は、モデルを要件、コード、テスト、運用アーティファクトに結びつける。

単純な追跡可能性チェーンは以下のようになる可能性がある：

要件
  → ユースケース
    → アクティビティフロー
      → シーケンスシナリオ
        → コンポーネント
          → 実装
            → 自動テスト

状態を持つドメインオブジェクトの場合：

ビジネスルール
  → 状態遷移
    → ガード条件
      → テストケース

追跡可能性は、すべての要素を他のすべての要素に接続することを必須とするものではない。高価値な関係に焦点を当てる：

• 安全性クリティカルな動作

• 規制要件

• セキュリティ制御

• 重要な統合

• 複雑なビジネスルール

• 高リスクのアーキテクチャ判断

19. バージョン管理とモデル保守

ダイアグラムはドキュメントであり、ドキュメントは保守されなければ信頼性を失う。

19.1 モデルは、それらが記述する作業の近くに保存する

考えられるアプローチには以下が含まれる：

• ソースリポジトリ内の UML ファイル

• アーキテクチャドキュメントリポジトリ

• 共有モデリングリポジトリ

• 技術ドキュメントと共に公開される生成されたダイアグラム

• 要件とモデル要素間のリンク

19.2 コードと併せて図を検証する

アーキテクチャまたは動作の変更については、実務上可能な限り、関連する図の更新を実装と同じ変更セットに含めてください。

レビュー担当者はその後、以下を評価できます：

• 実装が意図された設計と一致しているかどうか

• 設計変更が完了しているかどうか

• 依存関係が変更されたかどうか

• 新たな障害経路が存在するかどうか

• 展開への影響が考慮されたかどうか

19.3 権威ある図は少なくする

複数の矛盾する図は、1 つの不完全な図よりも悪影響です。各懸念事項について、どの図が権威あるものかを明確にしてください。

例：

• コンポーネント図：主要なサービス境界について権威あるもの

• 展開図：本番環境のトポロジーについて権威あるもの

• 状態機械：注文のライフサイクルについて権威あるもの

• クラス図：ドメイン間の関係について権威あるもの

20. 一般的なモデリングの誤り

すべてをモデル化する

図を増やすことが自動的に理解を深めるわけではありません。重要となるリスクと意思決定をモデル化してください。

抽象度のレベルを混在させる

ビジネスロール、プログラミングクラス、クラウドインフラ、およびデータベース列を、区別のない1つの図に配置しないでください。

曖昧な名称を使用する

「データを処理する」や「リクエストを処理する」などの名称は意図を隠します。目標、責任、または意味のあるイベントを特定する名称を優先してください。

障害動作を省略する

成功のみをモデル化すると、非現実的な期待を生みます。重要な例外、リトライ、タイムアウト、および拒否状態を含めてください。

図を恒久的なものと扱う

アーキテクチャは進化します。図には所有者と維持の期待を持つ必要があります。

UML関係の過剰使用

単純な関連付けは、技術的には正確だが混乱を招く一連の関係タイプよりも、しばしば優れています。

図を読み難くする

巨大な図 1 つではなく、複数の焦点を絞ったビューを使用してください。大規模なモデルは、シナリオ、サブシステム、ライフサイクル、またはデプロイメント境界に基づいて分割してください。

ツールが設計を主導することを許可する

ツールは図を描きやすくすることはできますが、何をモデル化するべきか、あるいはモデルが正しいかどうかを決定することはできません。

21. 実践的なモデリングワークフロー

チームは、機能またはシステムに対して以下のワークフローを採用できます。

ステップ 1: スコープを確立する

軽量なコンテキストビューを作成し、以下のものを特定してください：

• システム境界

• 主要なユーザー

• 外部システム

• 主要な目標

ステップ 2: ユースケースを特定する

ユースケースはアクターの目標として記述してください。関連する機能をグループ化し、最も重要なシナリオを特定してください。

ステップ 3: メインワークフローをモデル化する

アクティビティ図を使用して、以下のものを示してください：

• 通常のフロー

• 意思決定

• 責任

• 並行作業

• 例外

ステップ 4: 重要なシナリオを選択する

重要、複雑、リスクが高い、または統合が重いインタラクションに対してシーケンス図を作成してください。

ステップ 5: ドメイン構造を定義する

それらのシナリオに関与する概念に対して、概念的または設計レベルのクラス図を作成してください。

ステップ 6: アーキテクチャ境界を確立する

コンポーネント図を使用して、以下のものを示してください：

• 主要なモジュールまたはサービス

• インターフェース

• 依存関係

• 所有権

• 統合ポイント

ステップ 7：モデルのデプロイ

インフラ、セキュリティ、スケーラビリティ、可用性、または運用が重要な懸念事項である場合、デプロイメント図を作成してください。

ステップ 8：モデルのライフサイクル

ステータスまたは許可された遷移に依存して動作するエンティティに対して、状態機械図を作成してください。

ステップ 9：検証

モデルを以下と比較してください：

• 要件

• 既存のコード

• テスト

• データ構造

• インフラ

• 運用上の制約

ステップ 10：保守

動作、インターフェース、所有権、またはデプロイメントが変更された場合、関連する図を更新してください。

22. 典型的なシステムのための最小限の納品物

中規模のアプリケーションの場合、実用的な基準は以下のようになるかもしれません：

• システムコンテキストまたはユースケースビュー 1 つ

• 重要なビジネスプロセスのためのアクティビティ図 2〜5 枚

• クリティカルなシナリオのためのシーケンス図 2〜5 枚

• ドメインクラス図 1 枚

• コンポーネント図 1 枚

• 本番環境デプロイメント図 1 枚

• 主要なライフサイクルエンティティのための状態機械図

これは必須の数量ではありません。システムによっては図が少なくてもよい場合もあれば、より多く必要な場合もあります。適切な数は、複雑さ、リスク、チーム規模、規制、および誤解のコストによって異なります。

23. ツール選択戦略

異なるツールは、異なるモデリングニーズに対応します。

チームはあらゆる状況に対して1つのツールを選択する必要はありません。真実の源とメンテナンスの責任が明確であれば、混合アプローチはうまく機能します。

結論

実用的な UML 戦略は、すべての図タイプを使用することではありません。それは、システムを理解可能にする最小限のビューセットを選択することです。

7 つの図の核は広範なカバレッジを提供します：

• ユースケース図は目標と範囲を説明します。

• アクティビティ図はワークフローと責任を説明します。

• シーケンス図はコラボレーションとタイミングを説明します。

• クラス図は構造とドメイン概念を説明します。

• コンポーネント図はアーキテクチャの境界を説明します。

• デプロイメント図はランタイム配置とインフラストラクチャを説明します。

• 状態機械図はライフサイクルルールを説明します。

Visual Paradigm は、グラフィカルモデリング、トレーサビリティ、リポジトリベースのコラボレーションをサポートできます。VPasCode と PlantUML は、図をソースコードと連携してバージョン管理、レビュー、生成、保守しやすくします。AI はドラフト作成、変換、レビューを加速できますが、その出力は実際の要件、実装、運用制約に対して検証されなければなりません。

最も強力なモデリングプラクティスは、網羅的であることよりも規律あることです：

1. 重要となる意思決定、リスク、および振る舞いをモデル化します。

2. 質問に最もよく答える図タイプを選択してください。

3. 各図は1つの抽象化レベルに焦点を当ててください。

4. 一貫した名称とトレーサビリティを通じて、関連する図を接続してください。

5. モデルを要件、コード、テスト、およびデプロイメントに対して検証してください。

6. 図を保守可能なプロジェクト成果物として保存し、レビューしてください。

7. もはや価値を提供しない図は削除してください。

効果的なUMLは、生成された図の数によって測定されるものではありません。それは、モデルが人々がシステムを構築、テスト、運用、変更する際の信頼性を高めるかどうかによって測定されます。

参照

1. VPasCode: PlantUML、Mermaid、Graphvizを活用したAI支援の図-as-コード: VPasCodeのテキストから図へのエンジン、構文のベストプラクティス、およびAI支援の修正ワークフローを網羅した公式ガイド。
2. 「描画の雑務」から「表現」へ：AIチャットボットの概要: Visual ParadigmのAIチャットボットが自然言語を規格準拠のUMLおよび他の図に変換する方法を説明します。
3. NotesKeepナレッジベースでVisual Paradigm AIチャットボットを強化する: AI駆動の図生成および要件合成のための知識源としてNotesKeepリポジトリを接続する方法を示します。
4. Visual ParadigmでMacのUMLモデリングを革新する: macOSにおけるVisual ParadigmのUML 2.xサポート、コードエンジニアリング、およびモデルトレーサビリティの概要。
5. Visual Paradigm 18.1にAI VPPチャットボットを導入: 自然言語を通じて.vppプロジェクトファイルを照会できるAI VPPチャットボットのリリース発表。
6. VPasCodeプランと価格: VPasCodeの無料tierの価格と機能比較、およびVisual Paradigm Online/デスクトップ版との統合について。
7. Visual Paradigm VPasCodeへようこそ：図-as-コードへの転換: 図-as-コードのワークフローと、PlantUML、Mermaid、Graphvizのための統一レンダリング環境を紹介します。
8. Visual Paradigm VPasCodeにおけるネイティブAI図生成: エディタ内で直接PlantUML/Mermaid/Graphviz図を生成および修正するVPasCodeの組み込みAIの詳細。