統合モデル化言語（UML）の深淵に潜入するとき、クラス図やシーケンス図に次いで、最も混乱を招く図は複合構造図。クラス図やシーケンス図の普及により、しばしばその存在が影に隠れがちだが、この視覚的記法はシステムの内部構造を理解する上で重要な力を発揮する。しかし、その有用性や適用方法について、長く根強い誤解が存在する。シニアソリューションアーキテクトは、チームがこのモデリングステップを飛ばすケースを頻繁に目にするが、その結果、脆弱なコードベースや明確でないコンポーネント境界が生じる。

このガイドでは、複合構造図に関する一般的な誤解を解き明かす。表面的な理解を越え、内部構造モデリングの技術的現実に迫る。この読解を終える頃には、これらの図をいつ適用すべきか、そして複雑なシステムアーキテクチャを無駄な負荷を加えずに明確にする方法を理解できるだろう。

🧩 複合構造図とは何か？

誤解を解く前に、明確な定義を設ける必要がある。複合構造図は、分類子の内部構造を示す。クラス図がクラスとその属性を示すのに対し、複合構造図はクラスのブラックボックス内部に何が含まれているかを明らかにする。

注目するポイントは：

• 部品： 分類子内部の構成要素となるコンポーネント。
• 接続子： 部品をつなぐ経路。
• インターフェース： 部品が提供または要求するサービス。
• ポート： 分類子とその環境との相互作用のポイント。

クラス図を車の外観と仕様の図面に例えるなら、複合構造図は車体の断面図であり、エンジン、トランスミッション、配線ハーネスなどがシャシー内部にどのように配置されているかを示す。この図は、「この部品は実際に内部でどのように動作しているのか？」という問いに答える。

🚫 ミスコンセプト1：これは単に強化されたクラス図にすぎない

最も一般的で根本的な誤りは、複合構造図をクラス図の重複版と見なすことである。チームはしばしば、「クラス図があるのなら、なぜもう一つ必要なのか？」と問う。

現実：

• 範囲の違い： クラス図はクラスレベルでのシステムの静的構造をモデル化する。一方、複合構造図は特定の分類子内の部品の内部配置をモデル化する。
• 可視性： クラス図は公開インターフェースや属性を示す。一方、複合構造図は、標準的なクラス表示では隠されている内部の接続や依存関係を明らかにする。
• 粒度： 複雑なシステムでは、1つのクラスがマイクロサービス、ハードウェアモジュール、あるいは複雑なアルゴリズムをカプセル化している場合がある。クラス図はそのカプセル化の内部トポロジーを示すことができない。

内部構造モデリングにクラス図を使用すると、すべての依存関係が同じ平面上に描かれ、『スパゲッティクラス』のような視覚的混乱が生じる。複合構造図は、内部ネットワークと外部インターフェースを視覚的に分離するコンテナ階層を導入する。

🚫 ミスコンセプト2：これらの図は余計な負荷をかける

多くのアーキテクトは、詳細な内部構造モデルを作成することはアジャイル開発プロセス中にあまりにも時間がかかると主張する。彼らはドキュメントを明確さのためのツールではなく、ボトルネックと見なしている。

現実：

• 変更のコスト：デバッグやリファクタリングで節約できる時間は、モデリングに費やす時間よりも多いことが多い。システムが故障した際、図を用いて部品間のデータフローを理解するほうが、コードを追跡するよりも速い。
• オンボーディング：新しいチームメンバーはレガシーシステムを理解することに苦労する。複合構造図は内部アーキテクチャの地図を提供し、開発者の習得時間を短縮する。
• 対象的な使用法：すべてのクラスをモデリングする必要はない。この図は高複雑度のコンポーネントに限定して使用する。クラスが単純な場合はクラス図で十分である。サブシステムであれば、複合構造図が必要となる。

ドキュメント化とはアーティファクトを作成することではなく、意図を伝えることである。内部の複雑性が高い場合、モデリングの負担は安定性への投資となる。

🚫 ミスコンセプション3：これらはハードウェアや組み込みシステムにのみ適用される

歴史的に、これらの図は物理的な部品がどのように組み合わさるかを示すためにハードウェア工学で人気があった。その結果、ソフトウェアチームはこれらを純粋なソフトウェアアーキテクチャには関係ないと軽視しがちである。

現実：

• マイクロサービス：分散アーキテクチャでは、「部品」はサービスインスタンスになり得る。この図は、論理的な境界内でサービスがどのように内部的に接続されているかをマッピングする。
• ライブラリとフレームワーク：再利用可能なライブラリを構築する際、内部コンポーネントとそれらの連携方法を示すことは、APIデザイナーにとって不可欠である。
• ソフトウェアとハードウェアの統合：ソフトウェア内でも境界は存在する。ドライバーやカーネルモジュール、コンテナ化された環境は、特定のポートとインターフェースを持つ「部品」として機能する。

「構造」という概念は、ハードウェアと同様にソフトウェアにも適用される。これは、定義された境界内のデータフローと制御フローのトポロジーを定義する。

🚫 ミスコンセプション4：内部モデリングではインターフェースはオプションである

チームはしばしば、インターフェース（提供されるか要求されるか）を明示的に定義せずに部品と接続を描く。接続の意味はコードの実装によって明確になると仮定している。

現実：

• 契約の明確化：インターフェースは契約を定義する。それがないと、接続はただの線にすぎない。インターフェースは利用可能なメソッドや信号を指定する。
• 結合の緩和：部品は具体的な実装に依存するのではなく、インターフェースに依存すべきである。これにより、システムを壊すことなく内部コンポーネントを交換できる。
• ポートの定義：ポートは分類子上の接続ポイントである。設計段階での型安全性を確保するために、インターフェースで型付けされなければならない。

図でインターフェースをスキップすると、コード内で強い結合が生じる。インターフェースをモデリングしないと、実装段階で関心の分離を強制する可能性が低い。

🚫 ミスコンセプション5：これらはシーケンス図を置き換える

一部の人は、構造を示せば動作を示す必要がないと考える。構造図がシステムの動作を示していると仮定している。

現実：

• 静的 vs. 動的：複合構造図は静的です。存在するものを示します。シーケンス図は動的です。時間の経過とともに起こることを示します。
• 協働： 構造図は、部品Aが部品Bに接続されていることを示しています。シーケンス図は、部品AがT1の時点で部品Bにメッセージを送信していることを示しています。
• 検証： シーケンス図を使って動作を検証し、複合構造図を使ってアーキテクチャがその動作をサポートしているかを検証します。

片方をもう片方の代わりに使うと、盲点が生じます。複雑なシステムをナビゲートするには、地図（構造）と旅（シーケンス）の両方が必要です。

📊 比較：クラス vs. コンポーネント vs. 複合構造

違いを明確にするために、構造に頻繁に使用されるUML図の以下の比較を検討してください。

図の種類	主な焦点	主要な要素	最適な使用ケース
クラス図	静的システム構造	クラス、属性、操作	一般的なドメインモデリングおよびデータベーススキーマ設計
コンポーネント図	高レベルなアーキテクチャ	コンポーネント、インターフェース、依存関係	システム統合および展開計画
複合構造図	内部分類子の構成	部品、役割、ポート、接続子	複雑な内部論理、ライブラリ設計、サブシステム

粒度の変化に注目してください。クラス図が基盤です。コンポーネント図は構成要素を対象とします。複合構造図は構成要素の内部を観察します。

🛠️ 主な要素の説明

これらの図を効果的に使うには、特定のUML表記を理解する必要があります。図に現れる主要な要素についての説明です。

🔹 部品

部品とは、別の分類子の構成要素となる分類子です。図では、分類子ボックスの内部にボックスとして表示されます。これは内部のパズルの一部を表しています。

🔹 ロール

ロールは、部品がどのように使用されるかを説明します。同じ部品タイプが複数のロールを果たすこともあります。たとえば、データベースインスタンスは、ある文脈では「リーダー」として、別の文脈では「ライター」として機能する可能性があります。ロールは、接続線の末端に表示されることが多いです。

🔹 コネクタ

コネクタは、部品間の経路を定義します。データフローまたは制御フローを表します。ボックスを単に結ぶだけでなく、特定のロールを結びます。これにより、相互作用が正しく型付けされることを保証します。

🔹 ポート

ポートは、分類子の境界上の相互作用ポイントです。外部接続が行われる「プラグ」です。分類子は複数のポートを持つことができ、それぞれが異なるインターフェースを提供します。

🔹 インターフェース

インターフェースは、実装を伴わない振る舞いを定義します。複合構造図では、内部部品間および分類子と外部世界との間の契約を定義するために不可欠です。

🔍 複合構造図を使うべきタイミング

すべてのプロジェクトでこのレベルの詳細が必要というわけではありません。無差別に適用するとノイズが発生します。以下の状況でこの図を使用してください：

• 複雑なカプセル化： クラスまたはコンポーネントが、複数のサブコンポーネントを必要とする複雑な内部状態機械を管理している。
• サードパーティとの統合： ライブラリやサービスをラップしており、その内部モジュールが自分のコードとどのように相互作用するかを示す必要がある。
• パフォーマンスが重要な経路： 特定のコンポーネント内のデータフローのボトルネックを可視化する必要がある。
• マルチティアアーキテクチャ： プレゼンテーション層、ロジック層、データ層が、単一の論理単位内でどのように相互作用するかを示す必要がある。

システムが単純すぎて、1つのクラスがすべてのロジックを処理できる場合は、この図を使用しないでください。これは複雑さを管理するためのツールです。

🧠 アーキテクチャのベストプラクティス

これらの図から最大の価値を得るためには、以下のアーキテクチャ原則に従ってください。

1. インターフェースを明示的にする

暗黙の知識に頼ってはいけません。部品間のすべての接続は、インターフェースによって型付けされるべきです。これにより、開発チームが契約を遵守するよう強制されます。

2. コネクタの複雑さを最小限に抑える

コネクタが分類子の境界を越える場合、それはポートになります。境界を通過する内部接続を描いてはいけません。内部トポロジーを外部公開から明確に分離してください。

3. 「なぜ」を文書化する

特定の内部構造が選ばれた理由を説明するために、ノートや注釈を使用してください。パフォーマンスのためか？セキュリティのためか？テスト性のためか？図は構造を示すが、ノートがその理由を説明する。

4. コードと整合させる

図はコードとともに進化しなければなりません。内部部品が変更されたら、図も更新しなければなりません。古くなった図は、何も描かれていない図よりも悪いです。

🚧 避けるべき一般的な落とし穴

良い意図を持っていても、チームはこれらのモデルを作成する際にしばしばつまずきます。注意すべき一般的な誤りを以下に示します。

• 過剰なモデル化：すべての変数を部品として描画すること。部品は個々の変数ではなく、重要なコンポーネントを表すべきである。
• ライフサイクルの無視：部品がどのように生成または破棄されるかを示さないこと。UMLにはここでの制限があるものの、コメントにライフサイクルを記載しておくことは役立つ。
• 関心の混同：振る舞いの詳細（メソッド）を構造図内に記述すること。振る舞いはシーケンス図または状態図に保持する。構造は構成に関するものである。
• ポートの無視：ポートを定義せずに、接続線を分類子の境界に直接描画すること。これはカプセル化の原則に違反する。

💡 実際のシナリオ：決済ゲートウェイ

決済ゲートウェイコンポーネントを検討してください。クラス図はクラスを示しますPaymentGateway に、次のようなメソッドがありますprocessPayment() およびvalidateCard().

複合構造図は内部アーキテクチャを明らかにします：

• 部品1： ValidationService（必須インターフェース：CardValidator)
• 部品2： TransactionLogger（提供インターフェース：LogEntry)
• 部品3： EncryptionModule （提供インターフェース： 暗号化装置)
• コネクタ： リンク 暗号化モジュール へ トランザクションログ記録装置 安全なログ記録用。

このビューは、検証ロジックがトランザクションロジックとは別であることを強調しています。また、暗号化は独立した課題であることも示しています。暗号化アルゴリズムが変更された場合、インターフェースが安定している限り、暗号化モジュール の更新が必要です。この分離はクラス図では見えませんが、保守性にとって極めて重要です。

🔗 他のモデルとの統合

複合構造図は、空洞の中で存在するものではありません。広範なモデル化エコシステムと統合されています。

• クラス図との連携： 複合構造図内の分類子は、クラス図で定義されています。部品は、他の場所で定義されたクラスまたはコンポーネントです。
• コンポーネント図との連携： コンポーネント図では、決済ゲートウェイ を単一のブロックとして表示するかもしれません。複合構造図はそのブロックを開き、内部構造を明らかにします。
• 配置図との連携： 部品をどこに配置すべきかを判断するのに役立ちます。一部の部品はローカルマシン上で実行される一方、他の部品はクラウド上で実行される可能性があります。

この統合により一貫性が保たれます。クラス図が変更された場合、複合構造図の妥当性を確認する必要があります。配置図が変更された場合、複合構造図内の内部通信経路の調整が必要になる可能性があります。

📝 アーキテクチャ的洞察の要約

複合構造図は、深いアーキテクチャ的理解を目的とした専門的なツールです。抽象的なクラス定義と具体的な実装詳細の間のギャップを埋めます。内部境界を明確にすることで、意図しない結合のリスクを低減します。

シニアアーキテクトは、この図をすべてのプロジェクトに必須の成果物として使うのではなく、複雑なシステム向けの精密なツールとして活用することを推奨しています。適切に使用すれば、コミュニケーションを向上させ、技術的負債を削減し、内部コンポーネントの責任を明確にします。

誤解を無視し、構造を受け入れましょう。内部構造を明確にモデル化し、堅牢で保守可能なシステムを構築しましょう。

📚 よくある質問

この図は、すべてのUMLツールでサポートされていますか？

ほとんどの現代的なUMLモデル化ツールは、複合構造図をサポートしています。ただし、一部の軽量な図作成ツールでは、ポートや役割の完全なサポートが欠けている可能性があります。

データベーススキーマにこれを使用できますか？

はい、データベースエンジンの内部構造や複雑なORMレイヤーをモデル化する場合です。シンプルなリレーショナルスキーマにはあまり一般的ではありません。

図の詳細度はどの程度にすべきですか？

重要な経路と価値の高いコンポーネントに注目してください。すべてのメソッドをモデル化する必要はありません。アーキテクチャを定義する部分をモデル化してください。

この図はテストに役立ちますか？

間接的に役立ちます。インターフェースやポートを明確に定義することで、内部部品のユニットテスト用のテストスタブやモックの定義が容易になります。