基础 (Fundamentals) _ Spring Modulith 1.1.7-SNAPSHOT 中文文档(官方文档中文翻译) —

Spring Modulith 支持开发人员在 Spring Boot 应用程序中实现逻辑模块。它允许他们应用结构验证，记录模块排列，对单个模块运行集成测试，在运行时观察模块的交互，并且通常以松散耦合的方式实现模块交互。本节将讨论开发人员在深入了解技术支持之前需要了解的基本概念。Spring中文文档

应用模块

在 Spring Boot 应用程序中，应用程序模块是一个功能单元，由以下部分组成：Spring中文文档

向 Spring Bean 实例实现的其他模块和模块发布的应用程序事件公开的 API，通常称为提供的接口。Spring中文文档
不应由其他模块访问的内部实现组件。Spring中文文档
其他模块以 Spring Bean 依赖、监听的应用程序事件和公开的配置属性的形式对 API 的引用，通常称为必需接口。Spring中文文档

Spring Moduliths 在 Spring Boot 应用程序中提供了不同的模块表达方式，主要区别在于整体排列中涉及的复杂程度。这允许开发人员从简单开始，并在需要时自然地转向更复杂的方法。Spring中文文档

类型`ApplicationModules`

Spring Moduliths 允许检查代码库，以根据给定的排列和可选配置派生应用程序模块模型。该工件包含可指向 Spring Boot 应用程序类的项：spring-modulith-coreApplicationModulesSpring中文文档

创建应用程序模块模型

JavaSpring中文文档
KotlinSpring中文文档

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

var modules = ApplicationModules.of(Application::class)

将包含从代码库派生的应用程序模块排列的内存中表示形式。其中哪些部分将被检测为模块取决于类所指向的包所在的包下的 Java 包结构。详细了解简单应用程序模块中默认的排列方式。高级配置和自定义选项在高级应用程序模块和modulesSpring中文文档

为了了解所分析的排列情况，我们可以将整个模型中包含的各个模块写入控制台：Spring中文文档

将应用程序模块排列写入控制台

JavaSpring中文文档
KotlinSpring中文文档

modules.forEach(System.out::println);

modules.forEach(println(it))

我们的应用模块排列的控制台输出

## example.inventory ##
> Logical name: inventory
> Base package: example.inventory
> Spring beans:
  + ….InventoryManagement
  o ….SomeInternalComponent

## example.order ##
> Logical name: order
> Base package: example.order
> Spring beans:
  + ….OrderManagement
  + ….internal.SomeInternalComponent

请注意每个模块是如何列出的，包含的 Spring 组件是如何被识别的，以及相应的可见性是如何呈现的。Spring中文文档

不包括套餐

如果您想从应用程序模块检查中排除某些 Java 类或完整包，您可以通过以下方式执行此操作：Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

ApplicationModules.of(Application.class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify();

ApplicationModules.of(Application::class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify()

排除的其他示例：Spring中文文档

com.example.db— 匹配给定包中的所有文件。com.example.dbSpring中文文档
com.example.db..— 匹配给定包（）和所有子包（或）中的所有文件。com.example.dbcom.example.db.acom.example.db.b.cSpring中文文档
..example..— 匹配，或，但不是a.examplea.example.ba.b.example.c.da.exam.bSpring中文文档

有关可能的匹配器的完整详细信息可以在 ArchUnit PackageMatcher 的 JavaDoc 中找到。Spring中文文档

简单应用模块

应用程序的主包是主应用程序类所在的包。这就是类，它带有注释，通常包含用于运行它的方法。默认情况下，主包的每个直接子包都被视为一个应用程序模块包。@SpringBootApplicationmain(…)Spring中文文档

如果此包不包含任何子包，则将其视为简单包。它允许通过使用 Java 的包范围来隐藏其中的代码，以隐藏类型，使其不被驻留在其他包中的代码引用，从而不受依赖注入到这些包中的影响。因此，模块的 API 自然由包中的所有公共类型组成。Spring中文文档

让我们看一个示例排列（表示公共类型，包私有类型）。Spring中文文档

单个库存应用程序模块

 Example
└─  src/main/java
   ├─  example                        (1)
   |  └─  Application.java
   └─  example.inventory              (2)
      ├─  InventoryManagement.java
      └─  SomethingInventoryInternal.java

1	应用程序的主包。`example`
2	应用程序模块包。`inventory`

高级应用模块

如果应用程序模块包包含子包，则可能需要公开这些子包中的类型，以便可以从同一模块的代码中引用它。Spring中文文档

库存和订单应用程序模块

 Example
└─  src/main/java
   ├─  example
   |  └─  Application.java
   ├─  example.inventory
   |  ├─  InventoryManagement.java
   |  └─  SomethingInventoryInternal.java
   ├─  example.order
   |  └─  OrderManagement.java
   └─  example.order.internal
      └─  SomethingOrderInternal.java

在这种安排中，该包被视为 API 包。允许来自其他应用程序模块的代码引用其中的类型。，就像应用程序模块基础包的任何其他子包一样，被视为内部子包。其中的代码不得从其他模块引用。注意 how 是公共类型，可能是因为依赖于它。不幸的是，这意味着它也可以从其他包（例如一个包）中引用。在这种情况下，Java 编译器对于防止这些非法引用没有多大用处。orderorder.internalSomethingOrderInternalOrderManagementinventorySpring中文文档

打开应用程序模块

上述安排被视为封闭的，因为它们仅将类型公开给主动选择进行公开的其他模块。将 Spring Modulith 应用于旧版应用程序时，将嵌套包中的所有类型与其他模块隐藏起来可能是不够的，或者还需要标记所有这些包以进行公开。Spring中文文档

若要将应用程序模块转换为打开的模块，请使用类型上的注释。@ApplicationModulepackage-info.javaSpring中文文档

将应用程序模块声明为打开状态

JavaSpring中文文档
KotlinSpring中文文档

@org.springframework.modulith.ApplicationModule(
  type = Type.OPEN
)
package example.inventory;

@org.springframework.modulith.ApplicationModule(
  type = Type.OPEN
)
package example.inventory

将应用程序模块声明为打开将导致对验证进行以下更改：Spring中文文档

通常允许从其他模块访问应用程序模块内部类型。Spring中文文档
除非显式分配给命名接口，否则所有类型（包括驻留在应用程序模块基础包的子包中的类型）都将添加到未命名的命名接口中。Spring中文文档

此功能主要用于现有项目的代码库，逐渐转向 Spring Modulith 推荐的打包结构。在完全模块化的应用中，使用开放式应用模块通常意味着次优的模块化和封装结构。

显式应用程序模块依赖项

模块可以选择使用包上的注释（通过文件表示）来声明其允许的依赖项。例如，由于 Kotlin 缺乏对该文件的支持，因此您也可以对位于应用程序模块根包中的单个类型使用注释。@ApplicationModulepackage-info.javaSpring中文文档

显式配置模块依赖项的清单

JavaSpring中文文档
KotlinSpring中文文档

@org.springframework.modulith.ApplicationModule(
  allowedDependencies = "order"
)
package example.inventory;

package example.inventory

import org.springframework.modulith.ApplicationModule

@ApplicationModule(allowedDependencies = "order")
class ModuleMetadata {}

在这种情况下，库存模块中的代码只允许引用订单模块中的代码（并且代码一开始就没有分配给任何模块）。在验证应用程序模块结构中了解如何监视它。Spring中文文档

命名接口

默认情况下，如高级应用程序模块中所述，应用程序模块的基础包被视为 API 包，因此是唯一允许来自其他模块的传入依赖项的包。如果您想向其他模块公开其他包，则需要使用命名接口。您可以通过使用或显式注释的类型来批注这些包的文件来实现这一点。package-info.java@NamedInterface@org.springframework.modulith.PackageInfoSpring中文文档

封装 SPI 命名接口的封装排列

 Example
└─  src/main/java
   ├─  example
   |  └─  Application.java
   ├─ …
   ├─  example.order
   |  └─  OrderManagement.java
   ├─  example.order.spi
   |  ├—  package-info.java
   |  └─  SomeSpiInterface.java
   └─  example.order.internal
      └─  SomethingOrderInternal.java

package-info.java在example.order.spi

JavaSpring中文文档
KotlinSpring中文文档

@org.springframework.modulith.NamedInterface("spi")
package example.order.spi;

package example.order.spi

import org.springframework.modulith.PackageInfo
import org.springframework.modulith.NamedInterface

@PackageInfo
@NamedInterface("spi")
class ModuleMetadata {}

该声明的效果是双重的：首先，允许其他应用程序模块中的代码引用。应用程序模块能够在显式依赖项声明中引用命名接口。假设清单模块正在使用它，它可以像这样引用上面声明的命名接口：SomeSpiInterfaceSpring中文文档

定义专用命名接口的允许依赖关系

JavaSpring中文文档
KotlinSpring中文文档

@org.springframework.modulith.ApplicationModule(
  allowedDependencies = "order :: spi"
)
package example.inventory;

@org.springframework.modulith.ApplicationModule(
  allowedDependencies = "order :: spi"
)
package example.inventory

请注意我们如何通过双冒号连接命名接口的名称。在此设置中，清单中的代码将被允许依赖于接口中的其他代码，但不允许依赖于例如。对于没有明确描述依赖关系的模块，应用程序模块根包和 SPI 模块都可以访问。spi::SomeSpiInterfaceorder.spiOrderManagementSpring中文文档

如果要表示允许应用程序模块引用所有显式声明的命名接口，则可以使用星号（），如下所示：*Spring中文文档

使用星号声明所有已声明的命名接口的允许依赖项

JavaSpring中文文档
KotlinSpring中文文档

@org.springframework.modulith.ApplicationModule(
  allowedDependencies = "order :: *"
)
package example.inventory;

@org.springframework.modulith.ApplicationModule(
  allowedDependencies = "order :: *"
)
package example.inventory

自定义模块检测

默认情况下，应用程序模块应位于 Spring Boot 应用程序类所在的包的直接子包中。可以激活另一种检测策略，以仅考虑通过Spring Modulith或jMolecules注释显式注释的包。可以通过配置 to 来激活该策略。@ApplicationModule@Modulespring.modulith.detection-strategyexplicitly-annotatedSpring中文文档

将应用程序模块检测策略切换为仅考虑带注释的包

spring.modulith.detection-strategy=explicitly-annotated

如果默认的应用程序模块检测策略和手动注释的策略都不适用于您的应用程序，则可以通过提供的实现来自定义模块的检测。该接口公开一个方法，并将与Spring Boot应用程序类所在的包一起调用。然后，您可以检查驻留在其中的包，并根据命名约定等选择要被视为应用程序模块基础包的包。ApplicationModuleDetectionStrategyStream<JavaPackage> getModuleBasePackages(JavaPackage)Spring中文文档

假设您声明了一个自定义实现，如下所示：ApplicationModuleDetectionStrategySpring中文文档

实现自定义ApplicationModuleDetectionStrategy

JavaSpring中文文档
KotlinSpring中文文档

package example;

class CustomApplicationModuleDetectionStrategy implements ApplicationModuleDetectionStrategy {

  @Override
  public Stream<JavaPackage> getModuleBasePackages(JavaPackage basePackage) {
    // Your module detection goes here
  }
}

package example

class CustomApplicationModuleDetectionStrategy : ApplicationModuleDetectionStrategy {

  override fun getModuleBasePackages(basePackage: JavaPackage): Stream<JavaPackage> {
    // Your module detection goes here
  }
}

现在可以按如下方式注册此类：spring.modulith.detection-strategySpring中文文档

spring.modulith.detection-strategy=example.CustomApplicationModuleDetectionStrategy

1	应用程序的主包。`example`
2	应用程序模块包。`inventory`

自定义应用程序模块排列

Spring Moduliths 允许围绕您通过主 Spring Boot 应用程序类上使用的注解创建的应用程序模块排列配置一些核心方面。@ModulithicSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

package example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.modulith.Modulithic;

@Modulithic
@SpringBootApplication
class MyApplication {

  public static void main(String... args) {
    SpringApplication.run(DemoApplication.class, args);
  }
}

package example

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.modulith.Modulithic

@Modulithic
@SpringBootApplication
class DemoApplication

fun main(args: Array<String>) {
  runApplication<DemoApplication>(*args)
}

批注公开了以下要自定义的属性：Spring中文文档

Annotation 属性描述

Annotation 属性	描述
`systemName`Spring中文文档	要在生成的文档中使用的应用程序的人类可读名称。Spring中文文档
`sharedModules`Spring中文文档	将具有给定名称的应用程序模块声明为共享模块，这意味着它们将始终包含在应用程序模块集成测试中。Spring中文文档
`additionalPackages`Spring中文文档	指示 Spring Modulith 将配置的包视为其他根应用程序包。换句话说，应用程序模块检测也将被触发。Spring中文文档

systemNameSpring中文文档

要在生成的文档中使用的应用程序的人类可读名称。Spring中文文档

sharedModulesSpring中文文档

将具有给定名称的应用程序模块声明为共享模块，这意味着它们将始终包含在应用程序模块集成测试中。Spring中文文档

additionalPackagesSpring中文文档

指示 Spring Modulith 将配置的包视为其他根应用程序包。换句话说，应用程序模块检测也将被触发。Spring中文文档