此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Modulith 1.3.0spring-doc.cadn.net.cn

记录应用程序模块

通过ApplicationModules可用于创建文档片段,以包含在用 Asciidoc 编写的开发人员文档中。 Spring Modulith 的Documenterabstraction 可以生成两种不同类型的代码片段:spring-doc.cadn.net.cn

  • 描述各个应用程序模块之间关系的 C4 和 UML 组件图spring-doc.cadn.net.cn

  • 所谓的应用程序模块画布,关于模块及其中最相关元素(Spring bean、聚合根、发布和侦听的事件以及配置属性)的表格概述。spring-doc.cadn.net.cn

此外Documenter可以生成一个聚合的 Asciidoc 文件,其中包含所有现有的组件图和画布。spring-doc.cadn.net.cn

生成应用程序模块 Component 图

文档片段可以通过将ApplicationModules实例转换为Documenter.spring-doc.cadn.net.cn

生成应用程序模块组件图Documenter
class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
      .writeModulesAsPlantUml()
      .writeIndividualModulesAsPlantUml();
  }
}

第一次调用Documenter将生成一个包含系统内所有模块的 C4 组件图。spring-doc.cadn.net.cn

所有模块及其关系都呈现为 C4 组件图
图 1.所有模块及其关系都呈现为 C4 组件图

第二次调用将创建其他图表,这些图表仅包含单个模块以及它们直接依赖于画布的模块。spring-doc.cadn.net.cn

应用程序模块的子集及其关系,从呈现为 C4 组件图的 order 模块开始
图 2.应用程序模块的子集及其关系,从呈现为 C4 组件图的 order 模块开始

使用传统的 UML 组件图

如果您更喜欢传统的 UML 样式组件图,请调整DiagramOptions而是使用该样式,如下所示:spring-doc.cadn.net.cn

DiagramOptions.defaults()
  .withStyle(DiagramStyle.UML);

这将使图表如下所示:spring-doc.cadn.net.cn

所有模块及其关系都呈现为 UML 组件图
图 3.所有模块及其关系都呈现为 UML 组件图
应用程序模块的子集及其关系,从呈现为 UML 组件图的顺序模块开始
图 4.应用程序模块的子集及其关系,从呈现为 UML 组件图的顺序模块开始

生成应用程序模块画布

应用程序模块 Canvas 可以通过调用Documenter.writeModuleCanvases():spring-doc.cadn.net.cn

使用 生成应用程序模块画布Documenter
class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
      .writeModuleCanvases();
  }
}

默认情况下,文档将生成为spring-modulith-docs文件夹中。 生成的 canvas 如下所示:spring-doc.cadn.net.cn

表 1.示例 Application Module Canvas

基础包spring-doc.cadn.net.cn

com.acme.commerce.inventoryspring-doc.cadn.net.cn

弹簧组件spring-doc.cadn.net.cn

事件侦听器spring-doc.cadn.net.cn

聚集根spring-doc.cadn.net.cn

已发布的事件spring-doc.cadn.net.cn

侦听的事件spring-doc.cadn.net.cn

性能spring-doc.cadn.net.cn

  • acme.commerce.inventory.restock-thresholdc.a.c.c.Quantity.阈值InventoryEvents.StockShort应该在清单更新期间触发。spring-doc.cadn.net.cn

它由以下部分组成:spring-doc.cadn.net.cn

  • 应用程序模块的基础包。spring-doc.cadn.net.cn

  • 应用程序模块公开的 Spring bean,按构造型分组。— 换句话说,位于 API 包或任何命名接口包中的 bean。 这将检测由 jMolecules 架构抽象定义的组件构造型,以及标准的 Spring 构造型 Comments。spring-doc.cadn.net.cn

  • 公开的聚合根 — 我们为其找到存储库或通过 jMolecules 显式声明为聚合的任何实体。spring-doc.cadn.net.cn

  • 模块发布的应用程序事件 — 这些事件类型需要使用 jMolecules 进行划分@DomainEvent或实现其DomainEvent接口。spring-doc.cadn.net.cn

  • 模块监听的应用程序事件 — 派生自用 Spring 的@EventListener,@TransactionalEventListener、jMolecules 的@DomainEventHandler或 bean 实现ApplicationListener.spring-doc.cadn.net.cn

  • Configuration properties — 应用程序模块公开的 Spring Boot Configuration 属性。 需要使用spring-boot-configuration-processorartifact 提取附加到属性的元数据。spring-doc.cadn.net.cn

生成聚合文档

使用Documenter.writeDocumentation(…)all-docs.adoc文件,链接所有生成的图表和应用程序模块画布。 我们可以通过调用Documenter.writeAggregatingDocument():spring-doc.cadn.net.cn

使用 生成聚合文档Documenter
class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
        .writeAggregatingDocument();
  }
}

聚合文档将包括任何现有的应用程序模块组件图和应用程序模块画布。 如果没有,则此方法不会生成输出文件。spring-doc.cadn.net.cn


APP信息