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

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

個々のアプリケーションモジュール間の関連を説明する C4 および UML コンポーネント図
いわゆる Application Module Canvas。モジュールに関する表形式の概要と、モジュール内の最も関連性の高い要素 (Spring Bean、集約ルート、公開およびリッスンされるイベント、構成プロパティ)。

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

ドキュメントのスニペットは、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)

    @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)

  @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 アーティファクトを使用する必要があります。