最新の安定バージョンについては、Spring Modulith 1.3.4 を使用してください！

アプリケーションモジュールのドキュメント化

ApplicationModules で作成されたアプリケーションモジュールモデルは、Asciidoc で記述された開発者ドキュメントに含めるドキュメントスニペットを作成するために使用できます。Spring Modulith の Documenter 抽象化では、次の 2 種類のスニペットを生成できます。

  • 個々のアプリケーションモジュール間の関連を説明する C4 および UML コンポーネント図

  • いわゆる Application Module Canvas。モジュールに関する表形式の概要と、モジュール内の最も関連性の高い要素 (Spring Bean、集約ルート、公開およびリッスンされるイベント、構成プロパティ)。

さらに、Documenter は、既存のすべてのコンポーネントダイアグラムとキャンバスを含む集約 Asciidoc ファイルを生成できます。

アプリケーションモジュールコンポーネント図の生成

ドキュメントのスニペットは、ApplicationModules インスタンスを Documenter に渡すことによって生成できます。

Documenter を使用したアプリケーションモジュールコンポーネント図の生成

  • Java

  • Kotlin

class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
      .writeModulesAsPlantUml()
      .writeIndividualModulesAsPlantUml();
  }
}
class DocumentationTests {
    private val modules = ApplicationModules.of(Application::class.java)

    @Test
    fun writeDocumentationSnippets() {
        Documenter(modules)
            .writeModulesAsPlantUml()
            .writeIndividualModulesAsPlantUml()
    }
}

Documenter の最初の呼び出しでは、システム内のすべてのモジュールを含む C4 コンポーネント図が生成されます。

All modules and their relationships rendered as C4 component diagram
図 1: C4 コンポーネント図としてレンダリングされたすべてのモジュールとその関連

2 回目の呼び出しでは、個々のモジュールとキャンバスに直接依存するモジュールのみを含む追加の図が作成されます。

A subset of application modules and their relationships starting from the order module rendered as C4 component diagram
図 2: C4 コンポーネント図としてレンダリングされたオーダーモジュールから始まるアプリケーションモジュールのサブセットとその関連

従来の UML コンポーネント図の使用

従来の UML スタイルのコンポーネント図を好む場合は、次のように DiagramOptions を調整してそのスタイルを使用します。

  • Java

  • Kotlin

DiagramOptions.defaults()
  .withStyle(DiagramStyle.UML);
DiagramOptions.defaults()
  .withStyle(DiagramStyle.UML)

これにより、図は次のようになります。

All modules and their relationships rendered as UML component diagram
図 3: UML コンポーネント図としてレンダリングされたすべてのモジュールとその関連
A subset of application modules and their relationships starting from the order module rendered as UML component diagram
図 4: UML コンポーネント図としてレンダリングされたオーダーモジュールから始まるアプリケーションモジュールのサブセットとその関連

アプリケーションモジュールキャンバスの生成

アプリケーションモジュールキャンバスは、Documenter.writeModuleCanvases() を呼び出すことで生成できます。

Documenter を使用したアプリケーションモジュールキャンバスの生成

  • Java

  • Kotlin

class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
      .writeModuleCanvases();
  }
}
class DocumentationTests {

  private val modules = ApplicationModules.of(Application::class.java)

  @Test
  fun writeDocumentationSnippets() {
    Documenter(modules)
        .writeModuleCanvases()
  }
}

デフォルトでは、ドキュメントはビルドシステムのビルドフォルダー内の spring-modulith-docs フォルダーに生成されます。生成されたキャンバスは次のようになります。

表 1: サンプルのアプリケーションモジュールキャンバス

基本パッケージ

com.acme.commerce.inventory

Spring コンポーネント

サービス

  • c.a.c.i.InventoryManagement

リポジトリ

  • c.a.c.i.Inventory

イベントリスナー

  • c.a.c.i.InternalInventoryListeners が o.s.m.m.DayHasPassed、c.a.c.i.QuantityReduced を聞いている

  • c.a.c.i.InventoryOrderEventListener が c.a.c.o.OrderCanceled、c.a.c.o.OrderCompleted を聞いている

構成プロパティ

  • c.a.c.i.InventoryProperties

その他

  • c.a.c.i.InventoryItemCreationListener

集約ルート

  • c.a.c.i.InventoryItem

公開されたイベント

  • c.a.c.i.QuantityReduced 作成者:

    • c.a.c.i.InventoryItem.decreaseQuantity(…)

  • c.a.c.i.StockShort 作成者:

    • c.a.c.i.InternalInventoryListeners.on(…)

聞いたイベント

  • c.a.c.o.OrderCompleted

  • c.a.c.o.OrderCanceled

プロパティ

  • acme.commerce.inventory.restock-threshold — c.a.c.c.Quantity。インベントリの更新中に InventoryEvents.StockShort がトリガーされると想定されるしきい値。

これは次のセクションで構成されます。

  • アプリケーションモジュールの基本パッケージ。

  • アプリケーションモジュールによって公開され、ステレオタイプ別にグループ化された Spring Bean。つまり、API パッケージまたは任意の名前付きインターフェースパッケージに配置されている Bean です。これにより、jMolecules アーキテクチャ抽象化 [GitHub] (英語) によって定義されたコンポーネントステレオタイプだけでなく、標準の Spring ステレオタイプアノテーションも検出されます。

  • 露出した集約ルート  — リポジトリが見つかったエンティティ、または jMolecules を介して集約として明示的に宣言されたエンティティ。

  • モジュールによって公開されるアプリケーションイベント - これらのイベント型は、jMolecules @DomainEvent を使用して区別するか、DomainEvent インターフェースを実装する必要があります。

  • モジュールによってリッスンされるアプリケーションイベント — Spring の @EventListener、@TransactionalEventListener、jMolecules の @DomainEventHandler でアノテーションが付けられたメソッド、または ApplicationListener を実装する Bean から派生します。

  • 構成プロパティ  — Spring Boot アプリケーションモジュールによって公開される構成プロパティ。プロパティに添付されたメタデータを抽出するには、spring-boot-configuration-processor アーティファクトを使用する必要があります。

集約ドキュメントの生成

Documenter.writeDocumentation(…) を使用すると、生成されたすべてのダイアグラムとアプリケーションモジュールキャンバスをリンクする all-docs.adoc ファイルが生成されます。Documenter.writeAggregatingDocument() を呼び出すことで、集約ドキュメントを手動で生成できます。

Documenter を使用して集約ドキュメントを生成する

  • Java

  • Kotlin

class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
        .writeAggregatingDocument();
  }
}
class DocumentationTests {

  private val modules = ApplicationModules.of(Application::class.java)

  @Test
  fun writeDocumentationSnippets() {
    Documenter(modules)
        .writeAggregatingDocument()
  }
}

集約ドキュメントには、既存のアプリケーションモジュールコンポーネントダイアグラムとアプリケーションモジュールキャンバスが含まれます。これらがない場合、このメソッドでは出力ファイルは生成されません。