アーキテクチャの比較と実装準備 「アーキテクトの教科書 価値を生むソフトウェアのアーキテクト構築」書評 第2回

前回は「アーキテクトの教科書」を基に、アーキテクチャの基本と進め方について解説しました。

https://zenn.dev/fumi_mizu/articles/73d905a4e20db6

今回は、その続きとして、アーキテクチャの比較方法、アーキテクチャの文書化の詳細、そしてアプリケーション基盤の構築について掘り下げていきます。

皆さん、こんな経験はありませんか？「素晴らしいアーキテクチャだ！」と思って設計したものの、実際に開発が始まると様々な問題が浮上してきて、結局当初の設計とはかけ離れたものになってしまう……

私自身、過去のプロジェクトで「理想的」と考えていたマイクロサービスアーキテクチャを採用したものの、チームのスキルセットとのミスマッチから開発が難航し、納期に追われる日々を過ごした苦い経験があります。

この記事では、本書の知見とそうした実体験を踏まえ、失敗を防ぐための実践的なアプローチを共有したいと思います。

1. アーキテクチャの比較方法

1.1 モノリシックとマイクロサービスの比較

アーキテクチャを選定する際に、よく比較対象となるのが「モノリシック」と「マイクロサービス」のアプローチです。単純に「最新だから」「トレンドだから」という理由でマイクロサービスを選ぶのは危険です。それぞれの特徴を理解し、プロジェクトの状況に応じた選択をすることが重要です。

モノリシックアーキテクチャ

• 一つの大きなアプリケーションとして構築
• シンプルな開発・デプロイプロセス
• コンポーネント間の連携が容易
• スケーリングは全体単位で行う必要がある
• 小〜中規模のプロジェクトに適している

マイクロサービスアーキテクチャ

• 独立して動作する小さなサービスの集合体
• サービスごとに独立した開発・デプロイが可能
• 部分的なスケーリングが可能
• サービス間連携の複雑さが増す
• 大規模で複雑なシステムに適している

私のお気に入りのアナロジーは、モノリシックは「オールインワン料理」、マイクロサービスは「コース料理」だということです。

オールインワンは準備と片付けが簡単ですが、一部だけ調整するのは難しい。

コース料理は各皿を別々に完璧に仕上げられますが、全体の調和と準備の複雑さが課題になります。

1.2 アーキテクチャデシジョンレコード(ADR)の活用

アーキテクチャに関する意思決定を記録し、共有するための優れた方法が アーキテクチャデシジョンレコード(ADR) です。ADRは単なる文書ではなく、「なぜその決定をしたのか」という背景と理由を残すためのツールです。

ADRの基本構造：

1. タイトル：意思決定の簡潔な説明
2. 背景：意思決定が必要になった状況
3. 決定内容：選択した内容とその理由
4. ステータス：提案中、承認済み、廃止、など
5. 備考：補足情報、代替案、将来の展望など

ADRの効果は絶大です。あるプロジェクトでは、主要な設計者が途中で離脱するアクシデントがありましたが、ADRのおかげで新しいチームメンバーが素早く背景を理解し、プロジェクトを軌道に乗せることができました。

「なぜこの技術を使っているのか？」「なぜこの方式を採用したのか？」という疑問への回答がADRに記録されていれば、数か月後、あるいは数年後に別のメンバーがコードを見たときでも、理解が容易になります。

2. アーキテクチャの文書化の詳細

前回触れたアーキテクチャの文書化について、もう少し詳しく説明します。「4+1ビュー」モデルは、システムを異なる視点から表現する優れた手法です。

こんな感じでxに投稿したりしてました。

2.1 論理ビュー（Logical View）

論理ビューは、システムの機能構造を表します。クラス図やコンポーネント図などがこれに該当します。

私はこれを「建物の間取り図」に例えています。リビングと寝室とキッチンがどう配置されているか、どうつながっているかを示すものです。

例えば、ECサイトの論理ビューには、「商品カタログ」「ショッピングカート」「注文処理」「ユーザー管理」などのコンポーネントとその関係が示されます。

2.2 開発ビュー（Development View）

開発ビューは、システムのモジュール構成とパッケージ構造を表します。ソースコードの構成に近い視点です。

これは「本棚の整理」に似ています。プログラムのファイルやフォルダがどう整理されているかを示すものです。

例えば、MVCパターンを採用したWebアプリケーションの開発ビューには、「controllers」「models」「views」といったパッケージ構造が示されます。

2.3 プロセスビュー（Process View）

プロセスビューは、システムの実行時の振る舞いとプロセス間の連携を表します。シーケンス図やアクティビティ図などがこれに該当します。

これは「料理のレシピ」に似ています。どんな順番で処理が行われるか、を示すものです。

例えば、「ユーザーが注文を確定する」というプロセスのシーケンス図には、在庫確認、支払い処理、配送手配などの一連の流れが示されます。

2.4 物理ビュー（Physical View）

物理ビューは、システムのハードウェア構成やデプロイメント構成を表します。ネットワーク図やデプロイメント図がこれに該当します。

これは「建物の配置図」に似ています。実際のサーバーやネットワーク機器がどう配置されるかを示すものです。

例えば、Webアプリケーションの物理ビューには、Webサーバー、アプリケーションサーバー、データベースサーバーの構成と関係が示されます。

2.5 ユースケースビュー（Use Case View）

最後の「+1」がユースケースビューで、システムがユーザーにどのような価値を提供するかを表します。ユースケース図やユーザーストーリーがこれに該当します。

これは「遊園地のパンフレット」に似ています。「このシステムでは何ができるのか」を示すものです。

このような多角的な視点でアーキテクチャを文書化することで、様々なステークホルダー（開発者、運用担当者、経営者など）がそれぞれの関心事項に応じた理解を得ることができます。

3. アプリケーション基盤の構築

アーキテクチャが決まったら、次はアプリケーション基盤の構築です。アプリケーション基盤とは、業務アプリケーションの「土台」となる共通機能や仕組みのことです。

3.1 アプリケーション階層構造

アプリケーション基盤は、一般的に以下のような階層構造で考えることができます：

1. 業務アプリケーション：ユーザーが利用する実際の機能
2. アプリケーション基盤：共通機能や仕組み（認証、ロギングなど）
3. フレームワーク／ライブラリ：開発効率を高めるための道具セット
4. アプリケーションサーバー：プログラムを実行する環境
5. ランタイム環境：プログラミング言語の実行環境
6. OS：基本的なシステム機能

この階層構造を理解すると、いざというときのトラブルシューティングが容易になります。「問題はどの層で発生しているのか？」と考えることで、効率的に原因を特定できます。

3.2 アプリケーション基盤の役割

身近な例で考えてみましょう。アプリケーション基盤は、学校でいえば「保健室」「図書室」「体育館」のような共通施設です。教室（業務アプリケーション）ごとにこれらを作る必要はなく、学校全体で共有して使います。

主なアプリケーション基盤の役割をみていきましょう：

認証と認可

• 認証：「あなたは誰ですか？」を確認する機能
• 認可：「あなたは何ができますか？」を制御する機能

例えば、会社のオフィスでは、入館証で本人確認（認証）をし、役職に応じて入れる部屋が決まっている（認可）というのに似ています。

セッション管理

• ユーザーの状態を一時的に保持する機能

これは、ショッピングモールでカートを貸し出し、買い物中はそのカートにアイテムを入れておけるというのに似ています。

エラーハンドリングとロギング

• エラーを適切に処理し、記録する機能

これは、事故報告書と防犯カメラのような役割です。何か問題が起きた時に、何が起きたのかを把握し、再発防止に役立てます。

セキュリティ

• 不正アクセスや攻撃から守る機能

これは、建物のセキュリティシステムに似ています。侵入者を監視し、防御する仕組みです。

データベースアクセス

• データの保存と取得を担当する機能

これは図書館の本の貸し出しシステムのようなものです。必要な情報を整理して保存し、必要な時にすぐに取り出せるようにします。

3.3 会議要約アプリケーションの例

具体的に、「会議要約アプリケーション」を例に考えてみましょう。このアプリケーションは、会議の音声を文字起こしし、AIで要約するというものです。

このシステムの階層構造は以下のようになります：

1. 業務アプリケーション：

   • 会議録音機能
   • 文字起こし機能
   • 要約生成機能
   • 履歴表示機能

2. アプリケーション基盤：

   • ユーザー認証（誰の会議か識別）
   • ロギング（いつ、どの会議を処理したか記録）
   • エラーハンドリング（音声認識失敗時の対応）
   • データ永続化（要約結果の保存）

3. フレームワーク／ライブラリ：

   • Web：Flask/Django (Python)
   • 音声処理：PyAudio
   • AI：Hugging Face Transformers

4. アプリケーションサーバー：

   • Gunicorn/uWSGI

5. ランタイム環境：

   • Python 3.9

6. OS：

   • Ubuntu Linux

このように階層構造で整理することで、どのレイヤーにどんな技術や機能を配置するかが明確になります。

私がこのプロジェクトで学んだ重要な教訓は、「基盤にかける時間を惜しむな」ということです。

最初は「とりあえず機能を作れば」と思っていましたが、基盤がしっかりしていないと、後半になって問題が雪だるま式に増えていきました。特に認証とエラーハンドリングは、後から追加するのが非常に大変でした。

4. 開発プロセスの標準化

アーキテクチャと基盤が決まったら、次は開発プロセスを標準化します。これは「どのように作るか」という方法論です。

4.1 要求分析の標準化

要求分析では、以下のような成果物を作成します：

1. To-Be業務フロー図：
   新しいシステムでの業務の流れを表したもの。利用者と開発者の共通理解を形成するのに役立ちます。

2. ユースケース図：
   システムと利用者（アクター）の関わりを示したもの。シンプルに作成し、業務に詳しくてもUMLに詳しくない人でも理解できるようにします。

   私の経験では、カラフルなユースケース図は意外と効果的です。色で関連するユースケースをグルーピングすると、非技術者との会話がスムーズになりました。

3. ユースケース記述：
   各ユースケースの詳細を記述したもの。

   ユースケース記述のポイント：

   • システムの外部から見た状態を記述する
   • UI依存の書き方をしない（「ボタンをクリック」ではなく「会議を開始する」）
   • 情報は細かく列挙せず、チャンクとして記載（「会議に関する情報」）
   • ビジネスロジックの詳細は記述しない
   • アクターが対処できない例外は記述しない

4. 機能仕様書：

   • 画面遷移図
   • 画面レイアウト
   • 項目定義
   • 画面イベント定義
   • ロジック定義

   これらは「システムが何をするか（What）」を記述し、「どう実現するか（How）」は記述しないことがポイントです。

4.2 設計の標準化

設計書の標準化も重要ですが、すべての機能に詳細な設計書を作成するのは現実的ではありません。複雑な処理に限って必要に応じて作成するという方針が合理的です。

ただし、データベース設計書は必ず標準化しましょう：

• ER図
• テーブル一覧
• テーブル定義書

これらには正規化方針やキー設計方針、命名規約などの標準を定める必要があります。

私がプロジェクトリーダーを務めた際、「コードがドキュメント」という考えに傾倒しすぎて設計書を軽視したことがありました。

結果として、新しく参加したメンバーの立ち上がりに時間がかかり、結局後から設計書を作成することになりました。事前の設計書作成は、単なる手間ではなく、将来の効率化への投資なのです。

5. まとめと次のステップ

今回は、アーキテクチャの比較方法、文書化の詳細、アプリケーション基盤の構築、そして開発プロセスの標準化について解説しました。

アーキテクチャ設計は、単なる技術的な活動ではなく、プロジェクトの成功に直結する重要な活動です。適切なアーキテクチャとプロセスは、開発効率を高め、保守性を向上させ、最終的にはユーザー満足度の向上につながります。

次回は「アプリケーション実装と品質保証」について解説します。認証・認可、エラーハンドリング、ロギングなどの共通機能の実装方法と、テスト戦略について詳しく見ていきます。

皆さんのプロジェクトでは、どのようなアーキテクチャ基盤を採用していますか？また、どのような開発プロセスを実践していますか？コメント欄でぜひ共有してください。

こちら本を購入したいという方はこちらに画像リンクを貼っています👇

最後に

私は2つのプラットフォームで生成AIに関する発信を行なっております。

生成AIサービスの考察を見たい方へ

生成AIサービスの動向やや具体的な内容は、noteで詳しく解説しています。

noteプロフィール: @mizupee

日々の生成AI分析を追いたい方へ

毎日1つの生成AIサービスを分析するTwitter投稿「#100DaysofAI」もぜひフォローください。簡潔なポイント分析とアイデア共有を継続中です。

Twitter: @mizupee

次回もお楽しみに！