クリーンアーキテクチャフレームワーク
ソフトウェアを構造化するための規律あるアプローチであり、ビジネスルールがフレームワーク、データベース、配信メカニズムから独立している状態を保つことを目的とします。システムアーキテクチャの設計、モジュール境界のレビュー、依存関係管理に関するアドバイスを行う際に、これらの原則を適用してください。
基本原則
ソースコードの依存関係は、内側(より上位のポリシー)に向かって指し示さなければなりません。 内側の円は、外側の円について何も知ることはできません。この単一のルールにより、テストが可能で、フレームワーク、UI、データベース、および外部のあらゆる機関から独立したシステムが生まれます。ビジネスルールが重要であり、データベース、Webフレームワーク、配信メカニズムは詳細にすぎません。詳細がポリシーに依存する場合、決定を先延ばしにし、実装を交換し、ビジネスロジックを分離してテストすることができます。
スコアリング
目標: 10/10。 アーキテクチャが満たすクイック診断の7つの質問のうち、該当する数(0~7)に1ポイントを加算し、0~10の範囲にマッピングします。6~7個該当 = 9~10(依存関係ルールが成立し、ビジネスロジックがフレームワークおよびデータベースから独立している);4~5個 = 6~8(コアはテスト可能だが、一部の詳細が内側に漏れている);2~3個 = 3~5(フレームワークまたは永続化が構造を決定している);0~1個 = 0~2(境界がなく、ビジネスルールがコントローラーやORMモデルに混在している)。スコア、不合格となった診断項目、および各項目を修正するために必要な具体的な逆転を報告してください。
1. 依存関係ルールと同心円
中核概念: アーキテクチャを同心円として構成します。最も内側にエンティティ(エンタープライズビジネスルール)、次にユースケース(アプリケーションビジネスルール)、その次にインターフェースアダプター、最も外側にフレームワークとドライバーを配置します。ソースコードの依存関係は常に内側を向いています。
なぜ機能するのか: 上位レベルのポリシーが低レベルの詳細に依存しない場合、ビジネスロジックに触れることなく、データベース、Webフレームワーク、APIスタイルを交換できます。システムは、スタックの中で最も変動しやすい部分に対して回復力を持つようになります。
重要な洞察:
- 内側の円は外側の円の名前を参照してはいけません。外部のクラス、関数、変数、データ形式も使用できません。
- 境界を越えるデータは、内側の円にとって最も便利な形式でなければならず、外側によって決定されてはなりません。
- 依存関係逆転(インターフェースを内側で定義し、外側で実装する)は、このルールを強制するメカニズムです。
- 円の数は固定されておらず、4つが一般的ですが、ルールは変わりません。
- フレームワークはアーキテクチャではなく詳細であり、最も外側の円に属します。
コードへの適用:
| コンテキスト | パターン | 例 |
|---|---|---|
| レイヤーの方向 | 内側の円がインターフェースを定義し、外側が実装する | UserRepository インターフェースをユースケースで定義、PostgresUserRepository をアダプターで実装 |
| データの境界越え | DTOが境界を越える、ORMエンティティは越えない | ユースケースは UserResponse DTO を返し、ActiveRecord モデルは返さない |
| 依存関係の方向 | インポートの矢印は常に内側を向く | コントローラーはユースケースをインポート、ユースケースは決してコントローラーをインポートしない |
内側の円のインポートが外側を指している場合、4つの円のコードウォークスルー、データ境界越えルール、およびそれを修正するための4段階の依存関係逆転手順については、references/dependency-rule.md を参照してください。
2. エンティティとユースケース
中核概念: エンティティはエンタープライズ全体のビジネスルールをカプセル化します。これらのルールは、ソフトウェアがなくても存在するルールです。ユースケースは、アプリケーション固有のルールを含み、エンティティとの間のデータフローを調整します。
なぜ機能するのか: ビジネスが行うこと(エンティティ)と、アプリケーションがそれをどのように調整するか(ユースケース)を分離することで、エンティティを複数のアプリケーション間で再利用でき、中核となるビジネスルールを変更せずにアプリケーションの動作を変更できます。
重要な洞察:
- エンティティはデータベースの行ではありません。重要なビジネスルールをカプセル化するオブジェクトまたは純粋関数です。
- ユースケースはリクエストモデルを受け入れ、レスポンスモデルを返します。フレームワークのオブジェクトを決して使用しません。
- 各ユースケースは単一のアプリケーション操作です(
CreateOrder、ApproveExpense)。 - インタラクターパターン: ユースケースクラスは入力境界インターフェースを実装し、出力境界インターフェースを呼び出します。
- ユースケースの変更がエンティティに影響を与えることはあってはなりません。エンティティの変更はユースケースに波及する可能性があります。
コードへの適用:
| コンテキスト | パターン | 例 |
|---|---|---|
| エンティティ設計 | 重要なビジネスルール、フレームワーク依存関係ゼロ | Order.calculateTotal() は税率ルールを適用、HTTPについては何も知らない |
| リクエスト/レスポンス | 単純なデータ構造が境界を越える | CreateOrderRequest { items, customerId } — ORMモデルは含まない |
| 単一責任 | 操作ごとに1つのユースケース | PlaceOrder、CancelOrder、RefundOrder を個別のクラスとして定義 |
| インタラクター | 入力ポートを実装し、出力ポートを呼び出す | PlaceOrderInteractor implements PlaceOrderInput |
インタラクターを設計する場合、またはエンティティとユースケースのどちらに何を属させるかを決定する場合 — エンタープライズ vs アプリケーションビジネスルールの完全な解説とリクエスト/レスポンスモデルの例については、references/entities-use-cases.md を参照してください。
3. インターフェースアダプターとフレームワーク
中核概念: インターフェースアダプターは、ユースケース/エンティティにとって便利な形式と、外部機関が必要とする形式の間でデータを変換します。フレームワークとドライバーは最も外側の層であり、外部世界へのグルーコードです。
なぜ機能するのか: Webフレームワーク、ORM、メッセージキューが外側の円に限定されている場合、それらを置き換えることは局所的な変更で済みます。データベースは詳細であり、Webは詳細であり、詳細はビジネスルールへのプラグインであるべきであり、アプリケーションの骨格であってはなりません。
重要な洞察:
- コントローラーはHTTPをユースケース入力に変換し、プレゼンターはユースケース出力をビューモデルに変換します。
- ゲートウェイはユースケースによって定義されたリポジトリインターフェースを実装します。内側の円が契約を定義し、外側がそれを履行します。
- ビジネスルールは、データがSQL、NoSQL、フラットファイルのいずれに保存されているか、または配信がHTTPであるかを決して知りません。
- フレームワークには懐疑的になりましょう。フレームワークはあなたを結合させようとします。距離を置いてください。
コードへの適用:
| コンテキスト | パターン | 例 |
|---|---|---|
| コントローラー | 配信メカニズム → ユースケース入力 | OrderController.create(req) は CreateOrderRequest を構築し、インタラクターを呼び出す |
| プレゼンター | ユースケース出力 → ビューモデル | OrderPresenter.present(response) は JSON/HTML 用にフォーマットする |
| ゲートウェイ | DBごとに実装されるリポジトリインターフェース | SqlOrderRepository implements OrderRepository |
| フレームワーク境界 | フレームワークは内側を呼び出し、逆はない | Expressルートハンドラーはコントローラーを呼び出す、コントローラーはExpressをインポートしない |
コントローラー、プレゼンター、ゲートウェイの配線、またはデータベース/Webは詳細であると主張する場合 — プラグインアーキテクチャとフレームワークを縁に閉じ込める方法については、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に近い(安定) |
クラスをデプロイ可能なコンポーネントにグループ化する場合、または依存関係の循環を断つ場合 — REP、CCP、CRP、ADP、SDP、SAPの各原則を不安定性メトリクスとともに詳しく解説したものについては、references/component-principles.md を参照してください。
5. SOLID原則
中核概念: クラスおよびモジュールレベルの5つの原則 — 単一責任、オープン・クローズド、リスコフの置換、インターフェース分離、依存関係逆転 — 依存関係ルールを可能にする中級レベルの構成要素です。
なぜ機能するのか: 各原則は、依存関係が誤る特定の方法に対処し、コードベースをレガシーの悪夢にする硬直性、脆弱性、不動性を防ぎます。
重要な洞察:
- SRP: モジュールは変更理由が1つだけあるべきです。つまり、1つのアクターにサービスを提供します(「1つのことだけを行う」ではありません)。
- OCP: 既存のコードを修正するのではなく、新しいコードを追加することで動作を拡張します。ストラテジーやプラグインパターンが該当します。
- LSP: サブタイプは、クライアントが知らなくてもベースインターフェースを介して使用可能でなければなりません。予期しない例外や無視されたメソッドによって違反されます。
- ISP: クライアントは使用しないメソッドに依存すべきではありません。肥大化したインターフェースは不必要な結合を生み出します。
- DIP: 高レベルモジュールと低レベルモジュールの両方が、高レベルモジュールによって定義された抽象化に依存すべきです。
コードへの適用:
| コンテキスト | パターン | 例 |
|---|---|---|
| SRP違反 | クラスが複数のアクターにサービスを提供 | Employee が給与(CFO)、レポート(COO)、永続化(CTO)を担当 |
| ストラテジーによるOCP | 新しいクラスを通じて新しい動作を追加 | ShippingStrategy を実装する ExpressShipping を追加、Order は変更なし |
| LSP違反 | サブタイプが期待される動作を変更 | Square extends Rectangle が setWidth()/setHeight() の契約を破る |
| ISPの適用 | 肥大化したインターフェースをロールインターフェースに分割 | 1つの MultiFunctionDevice ではなく Printer、Scanner、Fax |
| DIPの配線 | 高レベルがインターフェースを定義、低レベルが実装 | OrderService は StripeClient ではなく PaymentGateway に依存 |
SRP/OCP/LSP/ISP/DIPを特定のクラスに適用する場合、または違反を診断する場合 — 各原則をコード例と防止するコードの臭いとともに詳しく解説したものについては、references/solid-principles.md を参照してください。
6. 境界と境界の構造
中核概念: 境界は、重要なものと詳細を分ける線であり、ポリモーフィズムを通じて実装されます。依存関係は内側を向いて境界を越え、制御フローはどちらの方向にも越える可能性があります。
なぜ機能するのか: すべての境界は、決定を先延ばしにしたり、実装を交換したりするオプションをもたらします。戦略的な境界の配置は、システムが長年にわたって保守が楽しくなるか、苦痛になるかを決定します。
重要な洞察:
- 完全な境界は両側で相互インターフェースを使用します。部分的な境界は、より単純なストラテジーまたはファサードを使用します。
- ハンブルオブジェクトパターン: 境界コードを、テストが難しい部分(境界に近い部分)とテストが簡単な部分(ロジック)に分割します。
- サービスは自動的にアーキテクチャ上の境界になるわけではありません。肥大化した共有データモデルを持つマイクロサービスは、ネットワークコールを伴うモノリスです。
- テストは最も隔離されたコンポーネントです。テストは内側に依存し、何もテストに依存しません。
- 時期尚早な境界は高くつきますが、境界の欠如も高くつきます。変動の可能性が高いポイントに境界を引きましょう。
コードへの適用:
| コンテキスト | パターン | 例 |
|---|---|---|
| 完全境界 vs 部分境界 | 相互ポート、または単一のストラテジー | ユースケースは PlaceOrderInput/PlaceOrderOutput を定義、単純なケースは ShippingStrategy を取る |
| ハンブルオブジェクト | テスト可能なロジックをインフラストラクチャから分離 | PresenterLogic(テスト可能)が ViewModel を生成、View(ハンブル)がそれをレンダリング |
| プラグインとしてのMain | コンポジションルートがシステムを組み立てる | main() がすべての具象実装を配線し、アプリを起動 |
境界をどこに引くか、完全境界と部分境界の選択、ハンブルオブジェクトパターンの適用を決定する場合 — サービスを境界として扱う方法、テスト境界、究極のプラグインとしてのMainについてもカバーしたものについては、references/boundaries.md を参照してください。
よくある間違い
| 間違い | なぜ失敗するか | 修正方法 |
|---|---|---|
| ORMのビジネスロジックへの漏洩 | エンティティがスキーマに結合、DBの変更がビジネスルールを書き換える | ドメインエンティティと永続化モデルを分離、アダプター層でマッピング |
| コントローラー内のビジネスルール | HTTPなしではテスト不可能、エンドポイント間で重複 | ロジックをユースケースインタラクターに移動、コントローラーは変換と委譲のみ |
| フレームワークファーストのアーキテクチャ | フレームワークが構造を決定、交換は書き換えを意味する | フレームワークをプラグインとして扱う、ビジネス機能ごとにコードを構造化 |
| 循環するコンポーネント依存関係 | 変更が予測不能に波及、独立したリリースが不可能 | DIPを適用するか、共有抽象コンポーネントを抽出する |
| 機能ごとに1つの巨大なユースケース | 肥大化した数千行のオーケストレーター | 焦点を絞った単一操作のユースケースに分割 |
| 「シンプルだから」と境界をスキップする | 結合が静かに蓄積され、コストが莫大になるまで気づかない | 変動の可能性が高いポイントに積極的に境界を引く |
| マイクロサービスを自動的に良いアーキテクチャとみなす | 分散モノリスはクリーンなモノリスよりも悪い | サービス内外で依存関係ルールを適用、サービスはデプロイ境界であり、アーキテクチャ上の境界ではない |
クイック診断
| 質問 | 「いいえ」の場合 | アクション |
|---|---|---|
| DB、Webサーバー、フレームワークなしでビジネスルールをテストできますか? | ルールがインフラに結合している | インターフェースの背後にエンティティとユースケースを抽出、外側の層をモック化 |
| すべてのソース依存関係は内側を向いていますか? |
(以下、原文が途中で切れているため、翻訳もここまでとなります。)
[truncated for translation]