文件化應用程式模組

透過 ApplicationModules 建立的應用程式模組模型可用於建立文件片段，以便納入以 Asciidoc 撰寫的開發人員文件。Spring Modulith 的 Documenter 抽象概念可以產生兩種不同種類的片段

描述個別應用程式模組之間關係的 C4 和 UML 元件圖
所謂的應用程式模組畫布，是以表格形式概述模組及其中最相關的元素（Spring beans、聚合根、已發布和監聽的事件，以及組態屬性）。

此外，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 元件圖呈現的所有模組及其關係

第二次呼叫將建立額外的圖表，這些圖表僅包含個別模組及其直接依賴的模組在畫布上。

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 components	服務 `c.a.c.i.InventoryManagement` Repositories `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 beans，依原型分組。— 換句話說，位於 API 套件或任何具名介面套件中的 beans。這將偵測由 jMolecules 架構抽象定義的元件原型，以及標準 Spring 原型註解。
公開的聚合根 — 我們為其找到儲存庫或明確宣告為透過 jMolecules 聚合的任何實體。
模組發布的應用程式事件 — 這些事件類型需要使用 jMolecules @DomainEvent 標記或實作其 DomainEvent 介面來劃分。
模組監聽的應用程式事件 — 從使用 Spring 的 @EventListener、@TransactionalEventListener、jMolecules 的 @DomainEventHandler 註解的方法或實作 ApplicationListener 的 beans 衍生而來。
組態屬性 — 應用程式模組公開的 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()
  }
}

彙總文件將包含任何現有的應用程式模組元件圖和應用程式模組畫布。如果沒有，則此方法將不會產生輸出檔案。