应用程序模块文档

通过 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` 存储库 `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 工件来提取附加到属性的元数据。

生成聚合文档

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

聚合文档将包含任何现有的应用程序模块组件图和应用程序模块画布。如果没有，则此方法不会生成输出文件。