文件化應用程式模組

透過 ApplicationModules 建立的應用程式模組模型可用於生成文件片段，以包含在用 Asciidoc 編寫的開發人員文件中。Spring Modulith 的 Documenter 抽象可以生成兩種不同型別的片段

C4 和 UML 元件圖，描述各個應用程式模組之間的關係
所謂的應用程式模組畫布，是關於模組及其最相關元素（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 元件圖呈現

第二次呼叫將建立額外的圖表，這些圖表只包含單個模組以及它們直接依賴的模組。

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` 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 bean，按原型分組。 — 換句話說，位於 API 包或任何命名介面包中的 bean。這將檢測由 jMolecules 架構抽象定義的元件原型，以及標準 Spring 原型註解。
公開的聚合根 — 我們發現其儲存庫或透過 jMolecules 明確宣告為聚合的任何實體。
模組釋出的應用程式事件 — 這些事件型別需要使用 jMolecules @DomainEvent 標記或實現其 DomainEvent 介面。
模組監聽的應用程式事件 — 來源於使用 Spring 的 @EventListener、@TransactionalEventListener、jMolecules 的 @DomainEventHandler 批註的方法或實現 ApplicationListener 的 bean。
配置屬性 — 應用程式模組公開的 Spring Boot 配置屬性。需要使用 spring-boot-configuration-processor artifact 來提取附加到屬性的元資料。

生成聚合文件

使用 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()
  }
}

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