Spring Modulithのドキュメント生成機能は、アプリケーションのモジュール構造とその依存関係を可視化するための強力なツールです。この機能を使用することで、モジュール間の関係を明確に理解し、アーキテクチャの整合性を確保することができます。ドキュメント生成機能は、開発者間のコミュニケーションを促進し、新しいチームメンバーのオンボーディングを容易にします。
Spring Modulithは、静的解析を使用してアプリケーションのモジュール構造を分析し、その結果をPlantUML図やAsciiDoc形式のドキュメントとして出力します。これにより、モジュール間の依存関係、公開API、イベントの発行と購読などの情報を視覚的に理解することができます。
+------------------------------------------+
| Spring Boot Application |
| |
| +-------------+ +-------------+ |
| | | | | |
| | Module A |------>| Module B | |
| | | | | |
| +-------------+ +-------------+ |
| | | |
| | v |
| | +-------------+ |
| | | | |
| +------------>| Module C | |
| | | |
| +-------------+ |
| |
| +----------------------------------+ |
| | | |
| | Spring Modulith Documentation | |
| | | |
| +----------------------------------+ |
| |
+------------------------------------------+
図1: Spring Modulithのドキュメント生成機能によるモジュール構造の可視化
Spring Modulithは、以下のドキュメント生成機能を提供しています：
Spring Modulithは、アプリケーションのモジュール構造を可視化するための機能を提供します。ModulithクラスのtoModuleModel()メソッドを使用して、アプリケーションのモジュール構造をモデル化し、そのモデルを使用して様々な形式のドキュメントを生成することができます。
@Test
void createModulithDiagram() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// PlantUML図の生成
new PlantUmlModuleWriter().write(model, Paths.get("modulith-diagram.puml"));
// AsciiDoc図の生成
new AsciiDocModuleWriter().write(model, Paths.get("modulith-diagram.adoc"));
}Spring Modulithは、モジュール間の依存関係を可視化するための機能を提供します。依存関係の可視化により、モジュール間の関係を明確に理解し、不適切な依存関係を特定することができます。
@Test
void createModulithDependencyDiagram() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// 依存関係図の生成
new PlantUmlModuleWriter(Options.defaults().withDependencies()).write(model, Paths.get("modulith-dependencies.puml"));
}Spring Modulithは、モジュール間のイベント発行と購読の関係を可視化するための機能を提供します。イベントの可視化により、モジュール間の疎結合な通信パターンを理解することができます。
@Test
void createModulithEventDiagram() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// イベント図の生成
new PlantUmlModuleWriter(Options.defaults().withEvents()).write(model, Paths.get("modulith-events.puml"));
}Spring Modulithは、モジュールの公開APIを可視化するための機能を提供します。公開APIの可視化により、モジュールが外部に公開している機能を明確に理解することができます。
@Test
void createModulithApiDiagram() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// 公開API図の生成
new PlantUmlModuleWriter(Options.defaults().withApiTypes()).write(model, Paths.get("modulith-api.puml"));
}Spring Modulithのドキュメント生成機能を使用するためには、以下の設定と手順が必要です：
Spring Modulithのドキュメント生成機能を使用するには、spring-modulith-docs依存関係を追加する必要があります。
<dependency>
<groupId>org.springframework.modulith</groupId>
<artifactId>spring-modulith-docs</artifactId>
<version>1.1.0</version>
<scope>test</scope>
</dependency>ドキュメント生成のためのテストクラスを作成します。このテストクラスは、アプリケーションのモジュール構造を分析し、ドキュメントを生成するためのテストメソッドを含みます。
@SpringBootTest
class ModulithDocumentationTests {
@Test
void createModulithDocumentation() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// ドキュメントの生成
new PlantUmlModuleWriter(Options.defaults()
.withDependencies()
.withEvents()
.withApiTypes())
.write(model, Paths.get("target/modulith-documentation"));
}
}テストを実行して、ドキュメントを生成します。生成されたドキュメントは、指定したパスに保存されます。
$ ./mvnw test -Dtest=ModulithDocumentationTests生成されたPlantUML図は、PlantUMLビューアーやオンラインサービスを使用して表示することができます。また、AsciiDoc形式のドキュメントは、AsciiDocビューアーやHTMLに変換して表示することができます。
$ java -jar plantuml.jar target/modulith-documentation/modulith-overview.pumlSpring Modulithのドキュメント生成機能は、様々なオプションを使用してカスタマイズすることができます。以下に、主要なカスタマイズオプションを紹介します。
Spring Modulithは、PlantUML形式とAsciiDoc形式のドキュメントを生成することができます。出力形式は、使用するライターによって決まります。
// PlantUML形式のドキュメント生成
new PlantUmlModuleWriter().write(model, Paths.get("modulith-diagram.puml"));
// AsciiDoc形式のドキュメント生成
new AsciiDocModuleWriter().write(model, Paths.get("modulith-diagram.adoc"));Spring Modulithは、Optionsクラスを使用して、ドキュメントの表示オプションをカスタマイズすることができます。表示オプションには、依存関係の表示、イベントの表示、公開APIの表示などがあります。
// 表示オプションのカスタマイズ
Options options = Options.defaults()
.withDependencies() // 依存関係を表示
.withEvents() // イベントを表示
.withApiTypes() // 公開APIを表示
.withDisplayName(DisplayName.FULLY_QUALIFIED) // 完全修飾名を表示
.withColorSelector(module -> module.getName().equals("orders") ? "#ff0000" : "#0000ff"); // モジュールの色を指定
// カスタマイズされたオプションを使用してドキュメントを生成
new PlantUmlModuleWriter(options).write(model, Paths.get("modulith-diagram.puml"));Spring Modulithは、特定のモジュールのみを表示するためのフィルタリング機能を提供します。フィルタリングを使用することで、関心のあるモジュールに焦点を当てたドキュメントを生成することができます。
// モジュールのフィルタリング
ModuleModel filteredModel = model.filterModules(module -> module.getName().startsWith("orders"));
// フィルタリングされたモデルを使用してドキュメントを生成
new PlantUmlModuleWriter().write(filteredModel, Paths.get("orders-modules.puml"));Spring Modulithは、PlantUML図にカスタムスタイルを適用するための機能を提供します。カスタムスタイルを使用することで、ドキュメントの見た目をカスタマイズすることができます。
// カスタムスタイルの定義
String customStyle = """
!define MODULITH_STYLE
skinparam component {
BackgroundColor #f0f0f0
BorderColor #000000
FontColor #000000
}
!enddefinition
""";
// カスタムスタイルを適用してドキュメントを生成
new PlantUmlModuleWriter(Options.defaults().withStyle(customStyle)).write(model, Paths.get("styled-modulith.puml"));Spring Modulithのドキュメント生成機能は、様々なユースケースで活用することができます。以下に、代表的なユースケースを紹介します。
Spring Modulithのドキュメント生成機能を使用して、アプリケーションのアーキテクチャを可視化することができます。アーキテクチャの可視化により、モジュール間の関係を明確に理解し、アーキテクチャの整合性を確保することができます。
@Test
void visualizeArchitecture() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// アーキテクチャ図の生成
new PlantUmlModuleWriter(Options.defaults().withDependencies()).write(model, Paths.get("architecture.puml"));
}Spring Modulithのドキュメント生成機能を使用して、継続的インテグレーションパイプラインの一部としてドキュメントを自動生成することができます。ドキュメントの自動生成により、常に最新のアーキテクチャドキュメントを維持することができます。
// CI/CDパイプラインでのドキュメント生成
@Test
void generateDocumentation() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// ドキュメントの生成
new PlantUmlModuleWriter(Options.defaults()
.withDependencies()
.withEvents()
.withApiTypes())
.write(model, Paths.get("target/site/modulith"));
// AsciiDocからHTMLへの変換
Asciidoctor asciidoctor = Asciidoctor.Factory.create();
asciidoctor.convertFile(
new File("target/site/modulith/modulith-overview.adoc"),
Options.builder().toFile(true).backend("html5").build()
);
}Spring Modulithのドキュメント生成機能を使用して、アーキテクチャの検証を行うことができます。モジュール間の依存関係を可視化することで、不適切な依存関係を特定し、アーキテクチャの整合性を確保することができます。
@Test
void verifyArchitecture() {
// モジュール構造のモデル化と検証
new Modulith(Application.class)
.verify()
.assertThatDependenciesAreValid();
// 検証結果の可視化
ModuleModel model = new Modulith(Application.class).toModuleModel();
new PlantUmlModuleWriter(Options.defaults().withDependencies()).write(model, Paths.get("verification-result.puml"));
}Spring Modulithのドキュメント生成機能を使用して、新しいチームメンバーのオンボーディングを支援することができます。アプリケーションのモジュール構造と依存関係を可視化することで、新しいチームメンバーがアーキテクチャを理解しやすくなります。
// オンボーディングドキュメントの生成
@Test
void generateOnboardingDocumentation() {
// モジュール構造のモデル化
ModuleModel model = new Modulith(Application.class).toModuleModel();
// オンボーディングドキュメントの生成
new AsciiDocModuleWriter(Options.defaults()
.withDependencies()
.withEvents()
.withApiTypes()
.withDisplayName(DisplayName.SIMPLE))
.write(model, Paths.get("onboarding/architecture.adoc"));
}Spring Modulithのドキュメント生成機能を効果的に活用するためのベストプラクティスを紹介します。
ドキュメント生成を継続的インテグレーションパイプラインの一部として自動化することで、常に最新のアーキテクチャドキュメントを維持することができます。自動化により、ドキュメントとコードの乖離を防ぎ、ドキュメントの信頼性を高めることができます。
ドキュメントの粒度は、目的や対象者に応じて適切に選択する必要があります。全体像を把握するための概要図と、詳細な情報を提供する詳細図を組み合わせることで、様々なニーズに対応することができます。
モジュールの種類や重要度に応じて、色や形状などの視覚的な区別を活用することで、ドキュメントの可読性を向上させることができます。視覚的な区別により、重要な情報を強調し、ドキュメントの理解を促進することができます。
Spring Modulithのドキュメント生成機能と他のドキュメントツールを組み合わせることで、より包括的なドキュメントを作成することができます。例えば、Spring Modulithの図とAsciiDocの説明文を組み合わせることで、視覚的な情報と詳細な説明を提供することができます。
アプリケーションのアーキテクチャは時間とともに変化するため、ドキュメントも定期的に更新する必要があります。ドキュメントの更新を怠ると、ドキュメントとコードの乖離が生じ、ドキュメントの信頼性が低下します。
ドキュメントの利用者からフィードバックを収集し、それを反映することで、ドキュメントの品質を向上させることができます。フィードバックにより、ドキュメントの不足点や改善点を特定し、より有用なドキュメントを作成することができます。
ドキュメントの目的を明確にし、その目的に合わせてドキュメントを設計することが重要です。目的が明確でないと、ドキュメントが冗長になったり、必要な情報が不足したりする可能性があります。
Spring Modulithのドキュメント生成機能は、アプリケーションのモジュール構造とその依存関係を可視化するための強力なツールです。この機能を使用することで、モジュール間の関係を明確に理解し、アーキテクチャの整合性を確保することができます。
Spring Modulithは、モジュール構造の可視化、依存関係の可視化、イベントの可視化、公開APIの可視化など、様々なドキュメント生成機能を提供しています。これらの機能を適切に活用することで、アプリケーションのアーキテクチャを効果的に可視化し、開発者間のコミュニケーションを促進することができます。
ドキュメント生成を効果的に活用するためには、ドキュメント生成の自動化、適切な粒度の選択、視覚的な区別の活用、ドキュメントの組み合わせ、定期的な更新、フィードバックの収集と反映、目的の明確化などのベストプラクティスを適用することが重要です。これらのプラクティスを実践することで、より有用で信頼性の高いアーキテクチャドキュメントを作成することができます。