クリーンアーキテクチャフレームワーク

ビジネスルールをフレームワーク、データベース、配信メカニズムから独立させるように、ソフトウェアを構造化する規律あるアプローチです。システムアーキテクチャを設計する際、モジュール境界を検査する際、または依存関係管理についてアドバイスする際にこれらの原則を適用してください。

コアプリンシプル

ソースコード依存関係は内側を向く必要があります -- より高レベルのポリシーに向かって。 内側の円のものは、外側の円のものについて何も知ることはできません。この単一ルールを一貫して適用すれば、テスト可能で、フレームワークから独立し、UIから独立し、データベースから独立し、あらゆる外部エージェンシーから独立したシステムが生まれます。

基礎: ソフトウェアアーキテクチャは線 -- 境界 -- を引いて、重要なものと詳細を分離することです。ビジネスルールが重要なものです。データベース、Webフレームワーク、配信メカニズムは詳細です。詳細がポリシーに依存する場合(その逆ではなく)、決定を先延ばしにしたり、実装を入れ替えたり、ビジネスロジックを分離してテストできます。

スコアリング

目標: 10/10。 ソフトウェアアーキテクチャを検査または作成する際、以下の原則への準拠に基づいて0-10の評価をします。10/10はすべてのガイドラインとの完全な整合を意味します。低いスコアは対処が必要なギャップを示しています。常に現在のスコアと10/10に到達するために必要な具体的な改善を提供してください。

クリーンアーキテクチャフレームワーク

時間の経過に耐えるシステムを構築するための6つの原則:

1. 依存関係ルールと同心円

コアコンセプト: アーキテクチャは同心円として構成されます。最も内側の円はエンティティ(エンタープライズビジネスルール)を含みます。次の円はユースケース(アプリケーションビジネスルール)を含みます。その次はインターフェースアダプターです。最も外側の円はフレームワークとドライバーを含みます。ソースコード依存関係は常に内側を向きます。

なぜそれが機能するか: 高レベルのポリシーが低レベルの詳細に依存しない場合、データベースをMySQLからMongoDBに変更したり、Webフレームワークを入れ替えたり、REST APIをGraphQLで置き換えたりできます -- すべてビジネスロジックに触れることなく。システムはテクノロジースタックの最も不安定な部分に対応力を持つようになります。

重要な洞察:

• 依存関係ルールは最優先ルール: 内側の円は外側の円の名前(クラス、関数、変数、データ形式)を言及できません
• 境界を越えるデータは内側の円にとって便利な形式である必要があり、外側の円が指定する形式で決してあってはいけません
• 依存関係逆転(内側で定義されたインターフェース、外側で実装される)がルールを強制するメカニズムです
• 円の数は固定されていません -- 4つが典型的ですが、より多くある場合もあります。ルールは同じです
• フレームワークは詳細です。アーキテクチャではありません -- 最も外側の円に属します

コード適用:

コンテキスト	パターン	例
レイヤー方向	内側の円はインターフェースを定義します。外側の円がそれを実装します	UserRepositoryインターフェースはユースケースで。PostgresUserRepositoryはアダプターで
データ交差	DTOまたは単純な構造体は境界を越えます。ORMエンティティではありません	ユースケースはUserResponseDTOを返します。ActiveRecordモデルではなく
フレームワーク分離	フレームワーク呼び出しをインターフェースの背後でラップします	EmailSenderインターフェースがSendGridまたはSESを使用しているかどうかを隠します
データベース独立性	リポジトリパターンは永続化を抽象化します	ビジネスロジックはrepo.save(user)を呼び出します。生のSQLを決して実行しません
依存関係方向	ダイアグラムのインポート矢印は常に内側を向きます	コントローラーはユースケースをインポートします。ユースケースはコントローラーをインポートしません

参照: references/dependency-rule.md

2. エンティティとユースケース

コアコンセプト: エンティティはエンタープライズ全体のビジネスルール -- ソフトウェアシステムが存在しなくても存在するであろう最も一般的で最高レベルのルール -- をカプセル化します。ユースケースはアプリケーション固有のビジネスルールを含み、エンティティとの間のデータフローをオーケストレーションします。

なぜそれが機能するか: ビジネスが何をするか(エンティティ)をアプリケーションがどのようにオーケストレーションするか(ユースケース)から分離することで、複数のアプリケーション全体でエンティティを再利用でき、コアビジネスルールを変更することなくアプリケーション動作を変更できます。

重要な洞察:

• エンティティはデータベース行ではありません -- 重要なビジネスルールとデータをカプセル化するオブジェクト(または純粋な関数)です
• ユースケースはアプリケーション固有の自動化ルールを説明します。エンティティをオーケストレーションしますがエンタープライズロジックは含みません
• ユースケースはリクエストモデルを受け取ってレスポンスモデルを返します -- フレームワークオブジェクトを決して返しません
• 各ユースケースは単一のアプリケーション操作を表します(例: CreateOrder、ApproveExpense)
• インターアクターパターン: ユースケースクラスは入力境界インターフェースを実装し、出力境界インターフェースを呼び出します
• ユースケースへの変更はエンティティに影響を与えるべきではありません。エンティティへの変更はユースケース更新を要求する場合があります

コード適用:

コンテキスト	パターン	例
エンティティ設計	フレームワーク依存性のない重要なビジネスルールをカプセル化します	Order.calculateTotal()は税ルールを適用します。HTTPについて何も知りません
ユースケース境界	入力ポートと出力ポートインターフェースを定義します	CreateOrderInputインターフェース。CreateOrderOutputインターフェース
リクエスト/レスポンス	単純なデータ構造は境界を越えます	CreateOrderRequest { items, customerId } -- ORMモデルではありません
単一責任	アプリケーション操作あたり1つのユースケース	PlaceOrder、CancelOrder、RefundOrderを別々のクラスとして
インターアクター	ユースケースクラスが入力ポートを実装し、出力ポートを呼び出します	PlaceOrderInteractor implements PlaceOrderInput

参照: references/entities-use-cases.md

3. インターフェースアダプターとフレームワーク

コアコンセプト: インターフェースアダプターはユースケースとエンティティに最も便利なフォーマットと外部エージェンシー(データベース、Web、デバイス)に必要なフォーマットの間のデータを変換します。フレームワークとドライバーは最も外側のレイヤー -- 外の世界に接続するグルーコードです。

なぜそれが機能するか: Webフレームワーク、ORM、またはメッセージキューが最も外側の円に限定されている場合、それらのいずれかを置き換えることはローカルな変更になります。データベースは詳細です。Webは詳細です。フレームワークは詳細です。詳細はあなたのビジネスルールへのプラグインであるべきで、アプリケーションのスケルトンではありません。

重要な洞察:

• コントローラーはHTTPリクエストをユースケース入力に翻訳します。プレゼンターはユースケース出力をビューモデルに翻訳します
• ゲートウェイはユースケースで定義されたリポジトリインターフェースを実装します -- ユースケースが契約を定義し、ゲートウェイが満たします
• データベースは詳細です: ビジネスルールはデータがSQL、NoSQL、またはフラットファイルに保存されているかどうかを知る必要がありません
• Webは詳細です: ビジネスルールはHTTP上で配信されていることを知りません
• フレームワークに疑いを持ってください -- フレームワークはあなたをそれらに結合させたいです。腕の長さを保ってください
• プラグインアーキテクチャ: システムはフレームワークがビジネスルールにプラグインするように構造化されるべきで、その逆ではありません

コード適用:

コンテキスト	パターン	例
コントローラー	配信メカニズムをユースケース入力に翻訳します	OrderController.create(req)はCreateOrderRequestを構築してインターアクターを呼び出します
プレゼンター	ユースケース出力をビューモデルに翻訳します	OrderPresenter.present(response)はJSON/HTML用にデータをフォーマットします
ゲートウェイ	特定のDBを使用してリポジトリインターフェースを実装します	SqlOrderRepository implements OrderRepository
フレームワーク境界	フレームワークコードは内側を呼び出します。内側のコードは決してフレームワークを呼び出しません	Expressルートハンドラーはコントローラーを呼び出します。コントローラーはExpressをインポートしません
プラグインアーキテクチャ	メインコンポーネントはスタートアップで依存関係を配線します	main()は具体的なクラスをインスタンス化して挿入します

参照: references/adapters-frameworks.md

4. コンポーネント原則

コアコンセプト: コンポーネントはデプロイメントの単位です。3つの凝集性の原則が何がコンポーネント内に入るかを管理します。3つのカップリング原則がコンポーネント間の関係を管理します。一緒に、システムのリリース可能性、保守性、安定性を決定します。

なぜそれが機能するか: 不完全なコンポーネント構成は波及効果を作成します: 1つの変更が無関係なコードの再デプロイを強制します。凝集性とカップリングの原則は、クラスをグループ化して、コンポーネント間の依存関係を管理し、変更をローカルに保つ方法を提供します。

重要な洞察:

• REP(再利用/リリース等価性): コンポーネント内のクラスは一緒にリリース可能である必要があります -- それらを単位として版管理およびリリースできない場合、それらは一緒に属していません
• CCP(共通クロージャー): 同じ理由で同じ時間に変更するクラスは同じコンポーネントに属します(コンポーネント向けSRP)
• CRP(共通再利用): ユーザーが使用しないものに依存するよう強制しないでください -- コンポーネントをインポートする必要がある場合、そのクラスのほとんどが必要であるべきです
• ADP(非環状依存): コンポーネントの依存グラフは循環を持つべきではありません。DIPまたは新しいコンポーネントを抽出することで循環を破ります
• SDP(安定依存): 安定の方向に依存します -- 多くの依存者を持つコンポーネントは変更が難しいべきです
• SAP(安定抽象): 安定コンポーネントは抽象的であるべきです。不安定なコンポーネントは具象であるべきです

コード適用:

コンテキスト	パターン	例
コンポーネントグループ化	一緒に変更するクラスをグループ化します(CCP)	すべての注文関連ユースケースを1つのコンポーネントに
循環の破棄	DIPを適用して依存エッジを反転します	循環依存を破るために新しいコンポーネントにインターフェースを抽出します
安定性メトリクス	不安定性を測定します: I = Ce / (Ca + Ce)	多くの入力依存と出力依存なしのコンポーネントはI近い0(安定)
抽象性バランス	安定コンポーネントはほとんどインターフェースを含むべきです	コアドメインコンポーネントは抽象的。アダプターコンポーネントは具象
リリース粒度	コンポーネントを独立して版管理およびリリースします	order-domain v2.1.0はpayment-adapterに触れずにリリース

参照: references/component-principles.md

5. SOLID原則

コアコンセプト: クラスとモジュールレベルで依存関係を管理するための5つの原則: 単一責任(SRP)、開放閉鎖(OCP)、リスコフ置換(LSP)、インターフェース分離(ISP)、依存関係逆転(DIP)。これらは依存関係ルールを可能にする中レベルのビルディングブロックです。

なぜそれが機能するか: SOLID原則はソースコードを柔軟で、理解可能で、変更に対応しやすく保ちます。ソースコードがレガシーナイトメアに変わることを防ぎます: 硬直性、脆弱性、動員不足。各原則は依存関係が間違う特定の方法に対処します。

重要な洞察:

• SRP: モジュールは1つの、そしてただ1つの理由で変更される必要があります -- 1つの俳優に仕えます(「1つのことをする」ではなく)
• OCP: 既存のコードを変更することなく新しいコードを追加することで動作を拡張します。戦略パターンとプラグインパターンはメカニズムです
• LSP: サブタイプは基本型インターフェース経由で使用可能である必要があります。クライアントが違いを知ることなく。サブクラスが予期しない例外をスローまたはメソッドを無視する場合は違反です
• ISP: クライアントは使用しないメソッドに依存するよう強制されるべきではありません。太いインターフェースは不要なカップリングを作成します
• DIP: 高レベルモジュールは低レベルモジュールに依存するべきではありません。両方は高レベルモジュールで定義される抽象に依存するべきです

コード適用:

コンテキスト	パターン	例
SRP違反	クラスは複数の俳優に仕えます	Employeeは給与計算(CFO)、報告(COO)、永続化(CTO)を処理します
戦略を通じたOCP	新しいクラスを通じた新しい動作。編集ではなく	ExpressShippingクラスをShippingStrategy実装として追加。Orderへの変更なし
LSP違反	サブタイプは予期される動作を変更します	Square extends RectangleはsetWidth()/setHeight()契約を破ります
ISP適用	太いインターフェースをロールインターフェースに分割します	Printer、Scanner、Fax代わりに1つのMultiFunctionDevice
DIP配線	高レベルがインターフェースを定義。低レベルが実装します	OrderServiceはPaymentGatewayインターフェースに依存します。StripeClientではなく

参照: references/solid-principles.md

6. 境界と境界解剖学

コアコンセプト: 境界は重要なものと詳細を分離する線です。境界は多型により実装されます: ソースコード依存関係は境界を越えて内側を向きながら、制御フローはどちらの方向でも越えることができます。謙虚なオブジェクトパターンは境界でのコードをテスト可能にします。

なぜそれが機能するか: あなたが引く各境界は決定を先延ばしにしたり実装を入れ替えるオプションをあなたに与えます。境界は不安定なものを安定したものから分離し、具象をコンテナから分離します。早期で戦略的な境界配置は、システムが年にわたって保守する喜びであるか苦痛であるかを決定します。

重要な洞察:

• 完全な境界は両側に相互インターフェースを使用します。部分的な境界はより単純な戦略パターンまたはファサードを使用します
• 謙虚なオブジェクトパターン: 境界でのコードを2つのクラスに分割 -- テストが難しい(境界に近い)と簡単(ロジックを含む)
• サービスは本質的にはアーキテクチャ境界ではありません -- 太い共有データモデルを持つマイクロサービスはネットワーク呼び出しを持つモノリスにすぎません
• メインコンポーネントはプラグイン: すべてのファクトリ、戦略、依存関係を作成してから、制御を高レベルポリシーに引き継ぎます
• テスト境界: テストは最も分離されたコンポーネント。常に内側に依存し、何もテストに依存しません
• 早すぎる境界は費用がかかりますが、欠落している境界も費用がかかります -- 越える費用が持たない費用より少ない場合に描画します

コード適用:

コンテキスト	パターン	例
完全な境界	両側の入力/出力ポートインターフェース	ユースケースはPlaceOrderInputとPlaceOrderOutputの両方を定義します
部分的な境界	完全な相互インターフェースなしの戦略またはファサード	ShippingCalculatorはShippingStrategyを受け入れます -- 完全なポートより単純
謙虚なオブジェクト	テスト可能なロジックをテスト困難なインフラから分離します	PresenterLogic(テスト可能)はViewModelを生成します。View(謙虚)がそれをレンダリングします
プラグインとしてのメイン	組成根はシステムを組み立てます	main()はすべての具体的な実装を配線してアプリを開始します
テスト境界	テストはソースに依存します。ソースは決してテストに依存しません	テストはPlaceOrderInteractorをインポート。本番コードはテストコードをインポートしません

参照: references/boundaries.md

一般的な間違い

間違い	失敗する理由	修正
ORMがビジネスロジックに漏れさせる	エンティティはデータベーススキーマに結合されます。DBを変更することはビジネスルール書き直しを意味します	ドメインエンティティを永続化モデルから分離します。アダプターレイヤーで間にマップします
ビジネスルールをコントローラーに入れる	ロジックはHTTPなしでテスト不可能です。エンドポイント間で複製します	すべてのビジネスロジックをユースケースインターアクターに移動します。コントローラーは翻訳と委譲のみです
フレームワークファーストアーキテクチャ	フレームワークは折り畳み構造と依存フローを指定します。フレームワークを入れ替えることは書き直しを意味します	フレームワークを最も外側の円のプラグインとして扱います。コードをビジネス機能別に構造化します
コンポーネント間の循環依存	変更は予測不可能に波及します。独立してリリース不可能	DIPを適用して循環を破るか、共有抽象コンポーネントを抽出します
機能あたり1つの巨大なユースケース	ユースケースは数千行のブロートアクターになります	単一アプリケーション操作で焦点を絞ったユースケースに分割します
「単純だから」境界をスキップする	カップリングは静かに蓄積します。境界が必要な時点で、費用は膨大です	可能性が高い変動性のポイントで能動的に境界を描画します
マイクロサービスを自動良アーキテクチャとして扱う	共有データベースと緊密なカップリングを持つ分散モノリスはよく構造化されたモノリスより悪いです	サービス内および全体で依存関係ルールを適用します。サービスはデプロイメント境界です。アーキテクチャ境界ではありません

クイック診断

質問	イフノー	アクション
データベース、Webサーバー、またはフレームワークなしでビジネスルールをテストできますか?	ビジネスルールはインフラに結合されます	インターフェースの背後にエンティティとユースケースを抽出します。外側のレイヤーをモックします
すべてのインポートでソースコード依存関係は内側を向いていますか?	依存関係ルールは違反されています	境界にインターフェースを導入します。オフェンダー依存関係を反転します
ビジネスロジックを変更することなくデータベースを入れ替えることができますか?	永続化は内側に漏れています	リポジトリパターンを実装します。永続化をアダプターに分離します
ユースケースは配信メカニズムから独立していますか?	ユースケースはHTTP、CLI、またはメッセージキューについて知っています	ユースケース署名から配信固有の型を削除します。プレーンDTOを使用します
フレームワークは最も外側の円に限定されていますか?	フレームワークはあなたのアーキテクチャです。詳細の代わりに	フレームワーク呼び出しをインターフェースでラップします。フレームワークコードをエッジにプッシュします
コンポーネント依存グラフを識別して、サイクルなしを確認できますか?	循環依存が存在します	ADP を適用: DIPを使用するか、すべての循環を破るために新しいコンポーネントを抽出します
Main(または合成根)はすべての依存関係を配線していますか?	具体的なクラスは内側の円でインスタンス化されます	すべての構築ロジックをメインに移動します。依存注入またはファクトリを使用します

参照ファイル

• dependency-rule.md: 依存関係ルール、同心円、境界を越えるデータ、内側の円を純粋に保つ
• entities-use-cases.md: エンタープライズビジネスルール、アプリケーションビジネスルール、インターアクターパターン、リクエスト/レスポンスモデル
• adapters-frameworks.md: インターフェースアダプター、詳細としてのフレームワーク、詳細としてのデータベース、プラグインアーキテクチャ
• component-principles.md: REP、CCP、CRP、ADP、SDP、SAP -- コンポーネント凝集性とカップリング
• solid-principles.md: SRP、OCP、LSP、ISP、DIPとコード例および共通違反
• boundaries.md: 境界解剖学、謙虚なオブジェクトパターン、部分的な境界、プラグインとしてのメイン、テスト境界

さらに詳しく

このスキルはRobert C. Martinのソフトウェアアーキテクチャの決定的ガイドに基づいています。詳細な例とケーススタディを含む完全な方法論について:

• "Clean Architecture: A Craftsman's Guide to Software Structure and Design" by Robert C. Martin

著者について

Robert C. Martin("Uncle Bob") はソフトウェアエンジニア、著者、およびAgile Manifestoの創立署名者の1人です。1970年からプログラミングを行っており、世界中の開発チームにコンサルタントおよびトレーニングを提供しています。MartinはClean Code、The Clean Coder、Clean Architecture、Clean Agileなどの著者です。Uncle Bob Consulting LLCおよびcleancoder.comの創立者です。彼のSOLID原則はオブジェクト指向設計の基礎語彙になっており、ソフトウェア開発における職人技と規律の提唱は何世代ものプログラマーに影響を与えました。Martinの作品は一貫してソフトウェアアーキテクチャが依存関係を管理し、境界を描き、ビジネスルールを配信メカニズムとインフラストラクチャの詳細から独立して保つことであると主張しています。