architecture-paradigm-hexagonal

ヘキサゴナル（ポート＆アダプター）パラダイム

使用する場面

• ビジネスロジックを外部依存関係から分離する場合
• テストのためにアダプターを切り替え可能にする必要があるシステム

使用しない場面

• 外部依存関係のない小規模なスクリプトやユーティリティ
• ポート／アダプターの抽象化によってオーバーヘッドが増えるプロトタイプ

このパラダイムを採用する場面

• データベース、フレームワーク、ユーザーインターフェースが頻繁に変更されることが予想され、コアドメインロジックを安定させておく必要がある場合。
• コアアプリケーションのテストに、複雑または低速なインフラストラクチャコンポーネントのモックが必要な場合。
• 開発チームがサードパーティとの統合に向けて、明確なインバウンドおよびアウトバウンドのインターフェースを提供する必要がある場合。

導入手順

1. ドメインポートを定義する：コアドメインとのすべてのやり取りを特定します。アクションを開始するアクター（UI、CLI、自動ジョブなど）向けのインバウンド「ドライバーポート」と、アプリケーションが利用するサービス（データベース、メッセージバス、外部 API など）向けのアウトバウンド「ドリブンポート」を定義します。これらのポートを正式なインターフェースとして表現します。
2. 境界にアダプターを実装する：外部テクノロジーごとに、そのポートのインターフェースを実装する「アダプター」を作成します。アダプターで使用される特定のフレームワークやライブラリについて、コアドメインが一切認識しないようにします。
3. ユースケースを集約する：アプリケーションの機能を、ビジネスケイパビリティを中心に構築されたサービスとして整理します。これらのサービスは、定義されたポートを通じてドメインへの呼び出しを調整します。
4. コントラクトテストを実装する：各アダプターが、実装するポートの要件を正しく満たしていることを検証します。コントラクトテストまたはコンシューマー駆動型コントラクトテストを使用して、この動作を検証します。
5. 依存関係のルールを徹底する：最も重要なルールは、外部フレームワークに依存してよいのはアダプターのみであることです。自動アーキテクチャテストまたは静的解析ルールを使って、このルールを徹底します。

主な成果物

• ポート、その対応するアダプター、依存関係のポリシーを正式に定めたアーキテクチャ決定記録（ADR）。
• コアドメインモジュールに格納された、ポートインターフェース定義一式。
• ドメインおよびアプリケーションサービスのユニットテストと、各アダプターのコントラクトテスト一式。
• 運用チームやアーキテクチャレビュー担当者向けの、インバウンドおよびアウトバウンドのデータフローを示すアーキテクチャ図。

リスクと軽減策

• ポート／インターフェースの肥大化：
  • 軽減策：ポートが多すぎると、メンテナンスの負荷が増加する可能性があります。関連する操作を、よりまとまりのある高レベルのポートにグループ化します。多くの場合、ドメイン集約を中心に整理します。
• 抽象化の漏れ：
  • 軽減策：ポートのインターフェースがトランスポート層の詳細（HTTP ヘッダーなど）を公開している場合、それは「抽象化の漏れ」です。これらのインターフェースを、ドメイン中心のデータ転送オブジェクト（DTO）を使用するようにリファクタリングします。
• アダプターの乖離：
  • 軽減策：アダプターが、表現対象の外部テクノロジーと同期しなくなることがあります（データベーススキーマの変更など）。永続化ポートの要件と SQL マイグレーションの整合性を確認するなど、アダプターの定期的かつ自動的な検証を計画します。

具体的なコンポーネント

このパラダイムの実装でよく使われるツールや抽象化の用語です。依存関係ではなく、tools: のフロントマターでもありません。

• boundary-validator：各アダプターがポートのコントラクトに準拠していることを確認します
• adapter-generator：ポート仕様からプライマリアダプターとセカンダリアダプターのひな形を生成します
• contract-tester：共通のコントラクトテストを通じて、各アダプターをポートに照らして検証します

終了条件

• ポートのインターフェースは正式な契約（インターフェース、抽象クラス、または型エイリアス）として定義され、アダプターのディレクトリではなく、コアドメインモジュール内に配置されています。
• ADR には、すべてのインバウンドドライバーポートとアウトバウンドドリブンポート、それぞれに対応するアダプターの実装、および依存関係のポリシーが記載されています。
• 自動化されたアーキテクチャテスト（例：ArchUnit、dep-cruise）により、あるアダプターから別のアダプター、またはコアの内部実装への直接参照がないことを保証しています。
• 各アダプターには、マージ前にポートの要件を正しく満たしていることを検証するコントラクトテストが少なくとも1つあります。