文件化應用模組

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

描述各個應用模組之間關係的 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 元件圖形式呈現

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

A subset of application modules and their relationships starting from the order module rendered as C4 component diagram

圖 2. 從 order 模組開始的應用模組子集及其關係以 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. 從 order 模組開始的應用模組子集及其關係以 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` Repository `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 原型註解。
公開的聚合根—我們找到其 Repository 或透過 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()
  }
}

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