707-technologies-hexagonal-architecture

Java のヘキサゴナルアーキテクチャ境界レビュー

Spring Boot、Quarkus、Micronaut のランタイム構成に依存しない形で、Java アプリケーションのヘキサゴナルアーキテクチャの境界をチームがレビューし、改善できるよう支援します。

このスキルで扱う内容

• ドメインの独立性：エンティティ、値オブジェクト、ドメインサービス、ドメインポリシーが、フレームワーク、永続化、Web、メッセージング、インフラストラクチャの API に依存しないこと
• アプリケーション／ユースケースのオーケストレーション：ユースケースが具象アダプターに依存せず、インバウンドまたはアウトバウンドのポートを通じてドメインの振る舞いを調整すること
• アダプターとインフラストラクチャの境界：駆動アダプターがインバウンドポートを呼び出し、被駆動アダプターがアウトバウンドポートを実装すること
• 依存関係の方向の確認：アダプターがコアに依存し、コアがアダプターに依存していないことを示す、パッケージ、モジュール、インポート、Maven モジュール、テストの証拠
• 任意のアーキテクチャ検証：プロジェクトに適している場合の、Hexagonal 境界に対する ArchUnit 形式のルール
• 根拠に基づく修正案：指摘事項で具体的なクラス、インポート、依存関係、パッケージ、テストを挙げ、境界を維持する小規模な変更を提案すること

対象範囲： Java プロジェクトを対象とした、フレームワークに依存しないアーキテクチャ境界レビューです。Spring Boot、Quarkus、Micronaut のランタイム構成については、該当するフレームワークスキルを参照してください。ArchUnit やその他の Maven 依存関係の追加については、111-java-maven-dependencies を参照してください。

制約

ユーザーがフレームワークのランタイム実装を明示的に求めない限り、アーキテクチャ境界と依存関係の方向に関する推奨事項に集中してください。このリポジトリの XML ソースを編集した後は、スキルを再生成してビルドを検証してください。

• 必須：同じ変更セット内で Java または Maven の変更を提案する前に、./mvnw compile または mvn compile を実行してください
• 境界：ドメインパッケージは、アプリケーション、アダプター、インフラストラクチャ、フレームワーク、永続化、Web、メッセージング、依存性注入の API に依存してはなりません
• ユースケース：アプリケーション／ユースケースのコードは、ドメインの振る舞いを調整し、インバウンド／アウトバウンドポートに依存できますが、具象アダプターの実装に依存してはなりません
• アダプター：駆動アダプターはインバウンドポートを呼び出し、被駆動アダプターはアウトバウンドポートを実装します。アダプターが共有ドメインロジックになったり、不要に互いへ依存したりしてはなりません
• ArchUnit は任意：ArchUnit は、プロジェクトに適している場合に選択する任意の検証手段として扱ってください。Hexagonal アーキテクチャのガイダンスを有用にするために、先に ArchUnit を追加することを必須にしてはなりません
• 依存関係：ArchUnit の依存関係追加を含む Maven 依存関係の評価は、111-java-maven-dependencies に委ねてください
• フレームワークへの振り分け：Spring Boot、Quarkus、Micronaut のランタイム構成は、該当するフレームワーク固有のスキルに委ねてください。このガイダンスにフレームワークスキルへの直接リンクを埋め込まないでください
• 検証：変更を採用する前に、./mvnw clean verify または mvn clean verify を実行してください
• エッジケース：パッケージ構成、モジュール境界、フレームワークの管理範囲、または永続化方針が曖昧でレビューに影響する場合は、アーキテクチャに関わるコードを編集する前に確認の質問をしてください
• エッジケース：確認済みの境界違反と、推測、命名規則から推定した慣例、コンテキスト不足を区別してください

このスキルを使用する場面

• Hexagonal アーキテクチャをレビューする
• ポートとアダプターの境界をレビューする
• アーキテクチャの境界をレビューする
• 依存関係の方向を徹底する
• ArchUnit によるアーキテクチャテストを追加する
• ドメインコードへのインフラストラクチャの漏出を検出する
• ポートとアダプターの境界を改善する

ワークフロー

1. リファレンスを読み、コードベースの構成を把握する

アーキテクチャの境界について判断する前に、references/707-technologies-hexagonal-architecture.md を読み、パッケージ、モジュール、インポート、Maven モジュール、テスト、フレームワークのエントリーポイントを調べます。

2. ポート、アダプター、依存関係の方向を特定する

ドメイン、アプリケーション／ユースケース、インバウンドポート、アウトバウンドポート、駆動側アダプター、被駆動側アダプター、インフラストラクチャの責務を整理します。根拠として使用した情報を記録し、不明確な点は仮定として明示します。

3. 違反を確認し、境界を維持する変更を提案する

コアからアダプターへの具体的な依存違反、フレームワークやインフラストラクチャの漏れ、アダプター間の結合、配置が不適切な振る舞いを報告し、既存のプロジェクト構成に沿った小規模な修正手順を提案します。

4. 任意の検証を推奨し、対象範囲外の作業を適切なスキルに案内する

有用な場合は ArchUnit 形式のテストを提案します。依存関係の追加は 111-java-maven-dependencies に、フレームワークのランタイム設定は該当するフレームワークスキルに案内し、検証結果をまとめます。

リファレンス

詳細なガイダンス、例、制約については、references/707-technologies-hexagonal-architecture.md を参照してください。