アーキテクチャ図を作成する技術

ある時点で、私たちが関与するすべてのソフトウェア プロジェクトにおいて、アーキテクチャ図を作成する必要性が生じるかもしれません。 正式なアーキテクチャモデル（Kruchten 4+1、Rozanski & Woods など）に従っているかどうかにかかわらず、図を作成することによってアプリケーションのいくつかの部分を文書化する必要性があるのです。 ソフトウェアアーキテクチャでは、そのような図は、モデルの一部となり得る特定の視点に関連するビューに準拠して作成されますが、今回の記事では、アーキテクチャ図という用語にこだわり、あまり堅苦しくしないことを希望します。 レンダリングされる情報の不整合、断片化、粒度、そしてダイアグラムの見た目に関する多くの問題を目の当たりにしました。 正式で標準化されていなければならないアーキテクチャーのモデルと比較して、ダイアグラムは必ずしも正式ではなく、特定の標準に準拠していないかもしれません。 なぜなら、アーキテクチャ図は、長期にわたってアプリケーションのアーキテクチャ (たとえば、構造、要素、関係、プロパティ、原則) を伝達し、さまざまな技術的背景や関心を持つ異なる利害関係者間で共通の基盤だからです。

アーキテクチャ図を設計する際の現在の落とし穴

考えられる問題に深く踏み込む前に、英語の慣用語に例えて「a picture is worth a thousand words」(絵は千語に値する) という言い方があるように、私はこの言い方をしたいと思います。 このウィキの説明によると、「複雑なアイデアもたった1枚の静止画で伝えることができる、あるいは、ある主題の画像は説明よりも効果的にその意味や本質を伝えるという考え方を指す」のだそうです。 建築の図も同じで、答えよりも疑問が多い図は、うまく作成されているとは言えません。 アーキテクチャ図が何千もの言葉や説明を必要としないようにしてください！

不適切なアーキテクチャ図の例。

では、アーキテクチャ図を適切に作成するプロセスを妨げるかもしれない落とし穴のリストを繰り返し見ていきましょう。

ボックスまたは図形は何を示すのか？ それは、データの一部、コードの束、またはプロセスのいずれかと関連付けられるかもしれません。

図形の異なる辺は何を表すのか

• 図形の各辺 (破線、点線など) は、下手すると誤解される可能性があります。 特定の境界は特定のコンポーネント タイプを指すのか (たとえば、破線はコンテナー、マイクロサービス、レイヤーなどを指す)、それとも単にルック アンド フィールを豊かにするためにデザイナーの好みなのでしょうか。

線や矢印は何を示すのか

• 線や矢印は、データ フロー (たとえば、データはシステム A からシステム B へ流れる) として、または要素間の関係 (たとえば、コンポーネント A はコンポーネント B に依存する) として解釈することができます。 ほとんどの場合、矢印で表される関係やデータフローは同じ方向に収束しないので、図の凡例に明示的に書くことが重要です。

線や矢印が示す通信/関連タイプは何ですか。

• 線がデータフローやコンポーネント間の関係を示す場合でも、その線や矢印が示す通信タイプ（データフローの場合など）や関連タイプ（関連の場合など）は詳細に記述しなければならない。 例えば、その線がデータフローを表す場合、通信は同期か非同期か、関係を指す場合、依存関係、継承関係、実装関係などで表現されるかもしれない。

その色の意味は？

• 適切に文書化された意図なしに「ペロッ」ポリカラー図（ボックスや線に複数の色など）があると、複数の質問が生じるかもしれません（たとえば、なぜいくつかのボックスは緑で、他のものは赤なのか？ なぜある線は黒で、他の線は青なのか?） ダイアグラムでは配色はそれほど重要ではなく、豊富な色数を使用しても、追加的な内容や価値のある情報はあまり多くありません。 区別できる色を使って図の一部を強調しなければならないという厳しい制約がない限り、黒と白の色を使うだけで図が説明でき、うまくデザインできることもあります。

Missing relationships between diagram elements or isolated entities

• Missing relationships between elements or isolated entities in a diagram might be a clue of incompleteness.This case is always better to stick to the simplicity in terms of colors used, but if it is not the case, forget to detail the choice.

ダイアグラムの要素や孤立したエンティティ間の関係がない。 構造的および動作的な観点から、すべての要素または実体は、別の要素によって表されるシステムの別の部分に依存し、関係 (線または矢印で表される) を持っていなければなりません。

誤解を招く/文書化されていない略語またはあまりにも曖昧/一般用語

• 図中の要素にラベルを使う場合、誤解を招く、もしくは文書化されていない略語を使わないようお勧めします。 ダイアグラム要素に適切な説明がない場合、あるいは、ダイアグラムの凡例 (例: TFH – チケット フィード ハンドラー、RBPM – レート ビジネス プロセス マネージャー) であればなおよいのですが。 この問題はコード レベルにも存在する可能性があり、クリーン コードの原則に従うことで、常に自己説明的で示唆に富む名前を使用することを提案します。

Emphasize technologies, frameworks, programming or scripting languages, IDE or development methodology on diagram

• Architectural design is not related or fundamentially based on any technology, framework, programming or scripting language, IDE or development methodology.This issue is not disclosed at the same level as the same level as well as. これらはすべて、アーキテクチャの構築を支援するためにプロセスの後半で登場しますが、中心点ではありません。 7916>

ランタイムと静的要素を同じ図に混ぜる

• ランタイム要素 (たとえば、スレッド、プロセス、仮想マシン、コンテナー、サービス、ファイアーウォール、データリポジトリ、等) はコンパイル時には存在せず、これらの要素と静的要素 (たとえば、コンポーネント、パッケージ、クラス) を同じ図の中で混ぜないことが推奨されています。 実行時の要素に主に焦点を当てた専用のダイアグラム タイプ (同時実行ダイアグラム、デプロイメント ダイアグラムなど) があり、これら 2 つの要素のカテゴリを区別し、できるだけ混在させないことが重要です。

“I will verbally describe this”, “I will explain it later”

• The everything is missing by the diagram itself, and there is no room to provide verbal details to complement an diagram.これは、図で説明できないものはすべて、図を補完するための言葉の詳細を提供する余地がありません。 なぜか？ なぜなら、口頭で述べられたが図に取り込まれていない説明はすべて失われ、後で他の関係者 (たとえば、開発者、設計者) が図を読んだときに、これらの説明を知ることができないからです。

衝突する詳細レベルまたは混合された抽象化

• 同じ図に異なる抽象化レベルに関連する要素を追加すると、それらが異なる観点から見られるため、衝突する可能性があります。 たとえば、アーキテクチャーのコンテキスト図にコンポーネントを追加したり、配置図にクラスを追加すると、図自体の目的が乖離する可能性があります。

あまりに多くの、あるいは不十分な詳細レベルを示そうとする、乱雑な、あるいは曖昧すぎる図

• 「すべてはできるだけ単純化すべきであるが、これ以上単純化してはならない」というのは、Albert Einstein の有名な言葉です。 これは、アーキテクチャ図にも当てはまります。捕捉される情報のレベルと粒度は、意味のあるものに選ばれるべきです。 これは簡単なことではなく、使用するアーキテクチャモデル、アーキテクトの経験、システムの複雑さによって異なります。

アーキテクチャ図を作成する際に従うべきガイドライン

上記の落とし穴を避けるために前提条件のチェックリストの一部である必要があるほか、図を適切に作成する方法についての一般的なガイドラインもあります。 アーキテクチャを表現するために単一の青写真を使用すると、理解できない意味上の混乱が生じます。” と述べています。 現代のシステムを文書化するためには、一種類の図だけで終わらせるわけにはいかないが、アーキテクチャ図を作成する場合、どの図を選び、いくつ作成すればよいかは、必ずしも単純ではない。 例えば、アーキテクチャーの性質や複雑さ、ソフトウェアアーキテクトのスキルや経験、使える時間、維持に必要な作業量、利害関係者の関心事を満たすために何が理にかなっているか、何が有用であるかなど、決定する前に考慮すべき要因は多数あります。 例えば、ネットワークエンジニアはホスト、通信ポート、プロトコルを含む明示的なネットワークモデルを見たがるだろうし、データベース管理者はシステムがどのようにデータを操作、管理、配布するかに関心がある、などだ。 これらのすべての側面に基づいて、最適な数のダイアグラムをピックアップすることが推奨されます。

ダイアグラムが不十分な場合 (例: 文書化不足)、アーキテクチャの一部が隠されたり文書化されないことがあります。

Keep structural and semantical consistency across diagrams

• Every diagram should be consistent with the others in terms of boxes, shapes, borders, lines, colors, etc…. 構造的なルック アンド フィールは同じであるべきで、すべての利害関係者が、チーム内の異なる開発者によって作成された図を理解するのに苦労することはないはずです。 理想的には、共通のダイアグラム ツールにこだわり、すべてのプロジェクトでそれを再利用します。
• 意味論的な観点から、これらの図はすべて、最新のコード変更とそれらの間で定期的に同期させる必要があります。 このプロセスは、手動またはモデリング ツールを使用して自動的にトリガーされるかもしれません。 後者が望ましいメカニズムですが、これはプロジェクトによって異なります。どのような場合でも、考え方としては、手法やツールに関係なく、図とコードの間の整合性を維持することです。 Simon Brown 氏は「ダイアグラムは、コードに接続されていなければ、アーキテクチャの改善に役立たない」と述べており、意味的な一貫性の考えを強調しています。

Prevent diagrams fragmentation

• 複数の図を持つことにより、アーキテクチャの記述が理解しづらくなり、それらを維持するのにかなりの労力がかかるかもしれません。 副次的な効果として、断片化が現れるかもしれません（例えば、2つ以上の図が同じ品質属性（性能、スケーラビリティなど）を説明している場合など）。 – 例えば、2つ以上の図が同じ品質属性（パフォーマンス、スケーラビリティなど）を説明しているが、それぞれが個々に不完全である）。 このような場合、関連する品質属性 (アーキテクチャ的に重要な要件にリンク) を反映していない図を削除するか、あるいは、より良い方法として、図をマージすることを推奨します (たとえば、同時実行および配置)。 それができないモデリングツールを使うことは、障害になるかもしれません。 最近の傾向として、シンプルで直感的なプレーンテキスト言語を使って、そこから図を生成することに依存しており、これはトレーサビリティの懸念を解決するように思われます。 7916>

アーキテクチャ図の横に凡例を追加する

• 標準アーキテクチャ記述言語（例：UML、ArchiMate）に従っていない場合、図のすべての部分を凡例で詳述します（例：ボックス、図形、枠、線、色、略語、その他）。
• そうでない場合は、凡例にキーとしてアーキテクチャ記述言語を追加するだけで、追加の説明は必要ありません。

アーキテクチャ記述言語（UML、ArchiMate など）は違いを生むか。 UML は硬直的で、アーキテクチャ設計をモデル化するのに十分な柔軟性がないと主張する人もいるかもしれませんが、その点については私も同意見です。 しかし、プロファイルやステレオタイプのようなUMLの拡張性に頼らず、アーキテクチャの基本を文書化するには、UMLで十分すぎる場合もある。 他の記述言語を見てみると、ArchiMateはUMLに比べてより強力でエンタープライズ・システムのモデリングに適していることがわかる。 比較は続くかもしれませんが、この記事の目的ではないので、それらについて深く検討するつもりはありません。

アーキテクチャ記述言語が十分に包括的で柔軟であるということは大きな前進であり、これはそれを選択する際の確かな基準となるはずです。 しかし、私の観点では、本当の原因は別のところにあり、アーキテクチャの文書がまったく作成されないという事実に関連しています。 人々はしばしば、その作成が退屈で、無駄で、無意味なものだと感じています。 ドキュメントを作成しない、あるいは不適切なドキュメントを作成するソフトウェアプロジェクトは膨大な数に上ります。 私は、人々が不適切な記述言語を使って集中的にアーキテクチャ図を作成したり、作成に関与しているとは思いませんし、もし彼らがより良い記述言語に置き換えたとしたら、結果は全く異なるものになるはずです。 いいえ、人々はアーキテクチャの文書（アーキテクチャ図を含む）を作成していませんし、さらに悪いことに、彼らのほとんどはそれを適切に作成する方法について知らないのです。

システムが開発され、アーキテクチャへの変更が具体化したときに、図をどのようにして最新の状態に保つことができるでしょうか

図を最新の状態に保つにはいくつかのアプローチがあります。 最初の選択肢は、最も簡単なもので、グランドトゥルースであるソースコードからダイアグラムを自動的に生成することである。 これによって、図がすべてコードと一致していることが保証されます。 残念ながら、既存のツールでは、これはまだ完全に可能ではありません（少なくとも私の知る限りでは）。 Len Bass は「理想的な開発環境は、ボタンを押すだけでドキュメントが実質的に無料で利用できるものである」と言い、暗に図を自動生成していますが、私たちはその地点に到達していません。 この方法では、アーキテクチャにおけるすべての変更は、自動的にコード スケルトンを再生成または更新するダイアグラム自体からトリガーされる必要があります。 すべてのコード変更がダイアグラムに反映されていることを確認するために、ダイアグラムの更新を開発プロセスで行われる定義の一部とすることが推奨されます。 このシナリオは、古い図や一貫性のない図を簡単に作成できる (たとえば、開発者はしばしば図を更新することを忘れたり、気分が乗らなかったりする) ため、あまり推奨されませんが、残念ながら、大多数のプロジェクトではまだこのようなことが起こっています。 たとえば、ソース コードに基づくツールで、ノイズ (乱雑すぎたり、無意味な情報) をあまり含まないように合理的にレンダリングできる図を自動生成するようにします。 このカテゴリーには、揮発性の高い図（頻繁に開発変更される傾向があり、通常は抽象度が低い）、あるいは逆に静的な図を含めることができます。 このような図には、コンテキスト図、参照アーキテクチャ図、パッケージ図、クラス図、エンティティ図などがあります。 しかし、ソースコードだけでは、システムがどのような品質属性（可用性、スケーラビリティ、パフォーマンスなど）を満たしているのか分からない場合があり、図の自動作成は十分な選択肢とは言えません。 そのため、手動でモデリングしたダイアグラムで補完する必要があります。 そのような図の例としては、シーケンス図、状態図、並行処理図、展開図、運用図などがある

現代のアーキテクチャ（たとえば、「Security」）を扱う場合、アーキテクチャ図にはどのような複雑さ（または単純さ）が生じるのだろうか。

Microservices またはその他の最新のアーキテクチャ スタイル (サーバーレス、イベント駆動型など) は、システムの構造、コンポーネントが互いに通信する方法 (コンポーネント間の関係など)、およびそれらを制御する原理を駆動するだけです。 個人的には、アーキテクチャーのスタイルが、ダイアグラム（および暗黙のうちにアーキテクチャーの説明）を作成する根拠や概念、およびダイアグラムが捉えるべき内容を変える必要はないと考えています。 しかし、最新のシステムアーキテクチャについて話すと、古いシステムや古典的なシステム（モノリスなど）と比較して、通常、より高いレベルの複雑性を持っているため、注意すべき点が複数あるという意味で、アーキテクチャの記述やダイアグラムに確実に影響を及ぼします。 そのような考慮事項は、分散コンポーネント (分散マイクロサービスなど) の数、各コンポーネントのタイプ、コンポーネントが互いに通信する方法 (境界、API、メッセージなど)、それらのライフサイクル、および各コンポーネントを誰が所有しているかの理解に関してかもしれません。 たとえば、非常に多くのマイクロサービスを持つシステムを想像してください。そのような場合、各マイクロサービスが独自のダイアグラムのセットを持つことになるため、ダイアグラムの数が大幅に増加する可能性があります。 一貫性（例えば、あるサービスのAPIを変更すると他のXサービスに影響するので、影響するすべての図を更新する必要がある）、断片化（例えば、分散したサービス間の高い可用性やパフォーマンスが1つの図に統合されていない）、または横断的な懸念（例えば、システム要素全体の監視やセキュリティなどの側面を統合的に説明する担当者がいる）に関する問題は簡単に処理できない可能性があります。 その上、プロジェクト開発中やその後も維持するために、チームの共存や協力に関する課題があるかもしれない。

要約すると、複雑なアーキテクチャを持つ現代のシステムは、ダイアグラムレベルでも複雑化する可能性のある、さらなる懸念をもたらすかもしれないということだ。

著者について

Ionut Balosin はソフトウェア設計者であり、独立した技術トレーナーでもあります。 彼は、世界中のソフトウェア開発会議やミートアップで定期的に講演を行い、プレゼンテーション、トレーニング コース、およびワークショップを提供しています。 詳細については、彼のウェブサイトをご覧ください。