基礎
Spring Modulith は、Spring Boot アプリケーションに論理モジュールを実装する開発者をサポートします。これにより、構造検証の適用、モジュールの配置のドキュメント化、個々のモジュールの統合テストの実行、実行時のモジュールの相互作用の観察、一般に疎結合方法でのモジュール相互作用の実装が可能になります。このセクションでは、開発者がテクニカルサポートに入る前に理解しておく必要がある基本的な概念について説明します。
アプリケーションモジュール
Spring Boot アプリケーションでは、アプリケーションモジュールは次の部分で構成される機能の単位です。
Spring Bean インスタンスによって実装される他のモジュールに公開される API、およびモジュールによって公開されるアプリケーションイベント。通常は、提供されたインターフェースと呼ばれます。
他のモジュールからアクセスされることが想定されていない内部実装コンポーネント。
Spring Bean 依存関係、リッスンされるアプリケーションイベント、および公開される構成プロパティの形式で他のモジュールによって公開される API への参照。通常、必須インターフェースと呼ばれます。
Spring Moduliths は、Spring Boot アプリケーション内でモジュールを表現するさまざまな方法を提供します。主に、全体的な配置に含まれる複雑さのレベルが異なります。これにより、開発者は単純な方法から始めて、必要に応じてより高度な手段に自然に移行することができます。
ApplicationModules
型
Spring Moduliths を使用すると、コードベースをインスペクションして、指定された配置とオプションの構成に基づいてアプリケーションモジュールモデルを導出できます。spring-modulith-core
アーティファクトには、Spring Boot アプリケーションクラスを指すことができる ApplicationModules
が含まれています。
Java
Kotlin
var modules = ApplicationModules.of(Application.class);
var modules = ApplicationModules.of(Application::class)
modules
には、コードベースから派生したアプリケーションモジュール配置のメモリ内表現が含まれます。モジュールとして検出される部分は、クラスが属するパッケージの Java パッケージ構造によって異なります。シンプルなアプリケーションモジュールでデフォルトで期待される配置について詳しく確認してください。高度な配置とカスタマイズオプションについては、高度なアプリケーションモジュールとで説明されています。
分析された配置がどのように見えるかを把握するには、モデル全体に含まれる個々のモジュールをコンソールに書き込むだけです。
Java
Kotlin
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 コンポーネントが識別され、それぞれの可視性もレンダリングされるかに注目してください。
パッケージの除外
アプリケーションモジュールインスペクション から特定の Java クラスまたは完全なパッケージを除外する場合は、次のようにします。
Java
Kotlin
ApplicationModules.of(Application.class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify();
ApplicationModules.of(Application::class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify()
除外の追加例:
com.example.db
— 指定されたパッケージcom.example.db
内のすべてのファイルと一致します。com.example.db..
— 指定されたパッケージ (com.example.db
) およびすべてのサブパッケージ (com.example.db.a
またはcom.example.db.b.c
) 内のすべてのファイルと一致します。..example..
—a.example
、a.example.b
、a.b.example.c.d
に一致しますが、a.exam.b
には一致しません。
可能なマッチャーの詳細については、ArchUnit PackageMatcher
[GitHub] (英語) の JavaDoc を参照してください。
シンプルなアプリケーションモジュール
アプリケーションのメインパッケージは、メインアプリケーションクラスが存在するパッケージです。つまり、@SpringBootApplication
のアノテーションが付けられたクラスであり、通常はその実行に使用される main(…)
メソッドが含まれています。デフォルトでは、メインパッケージの各直接サブパッケージは、アプリケーションモジュールパッケージとみなされます。
このパッケージにサブパッケージが含まれていない場合、単純なパッケージとみなされます。Java のパッケージスコープを使用して、他のパッケージに存在するコードから型が参照されないようにすることで、そのパッケージ内のコードを非表示にすることができ、その結果、他のパッケージへの依存性注入の影響を受けなくなります。当然のことながら、モジュールの API はパッケージ内のすべてのパブリック型で構成されます。
配置例を見てみましょう ( パブリック型を示します。 パッケージプライベートのもの)。
Example
└─ src/main/java
├─ example (1)
| └─ Application.java
└─ example.inventory (2)
├─ InventoryManagement.java
└─ SomethingInventoryInternal.java
1 | アプリケーションのメインパッケージ example 。 |
2 | アプリケーションモジュールパッケージ inventory 。 |
高度なアプリケーションモジュール
アプリケーションモジュールパッケージにサブパッケージが含まれている場合、まったく同じモジュールのコードから参照できるように、サブパッケージ内の型をパブリックにする必要がある場合があります。
Example
└─ src/main/java
├─ example
| └─ Application.java
├─ example.inventory
| ├─ InventoryManagement.java
| └─ SomethingInventoryInternal.java
├─ example.order
| └─ OrderManagement.java
└─ example.order.internal
└─ SomethingOrderInternal.java
このような配置では、order
パッケージは API パッケージと見なされます。他のアプリケーションモジュールのコードは、その中の型を参照できます。order.internal
は、アプリケーションモジュールベースパッケージの他のサブパッケージと同様に、内部パッケージと見なされます。それらの中のコードは、他のモジュールから参照できません。SomethingOrderInternal
がパブリック型である点に注意してください。これは、おそらく OrderManagement
がそれに依存しているためです。残念ながら、これは inventory
などの他のパッケージからも参照できることを意味します。この場合、Java コンパイラーは、これらの不正な参照を防ぐのにあまり役立ちません。
オープンアプリケーションモジュール
上記の配置は、公開対象としてアクティブに選択された他のモジュールにのみ型を公開するため、クローズドであると見なされます。Spring Modulith をレガシーアプリケーションに適用する場合、ネストされたパッケージにあるすべての型を他のモジュールから非表示にすることは不十分であるか、それらのすべてのパッケージを公開対象としてマークする必要がある可能性があります。
アプリケーションモジュールをオープンモジュールに変換するには、package-info.java
型の @ApplicationModule
アノテーションを使用します。
Java
Kotlin
@org.springframework.modulith.ApplicationModule(
type = Type.OPEN
)
package example.inventory;
@org.springframework.modulith.ApplicationModule(
type = Type.OPEN
)
package example.inventory
アプリケーションモジュールをオープンとして宣言すると、検証に次の変更が加えられます。
通常、他のモジュールからアプリケーションモジュールの内部型へのアクセスは許可されます。
すべての型、さらにはアプリケーションモジュールベースパッケージのサブパッケージに存在する型も、名前付きインターフェースに明示的に割り当てられていない限り、名前のない名前付きインターフェースに追加されます。
この機能は、主に、Spring Modulith 推奨パッケージ構造に徐々に移行している既存プロジェクトのコードベースで使用することを目的としています。完全にモジュール化されたアプリケーションでは、オープンアプリケーションモジュールを使用すると、通常、モジュール化とパッケージ構造が最適ではなくなります。 |
アプリケーションモジュールの明示的な依存関係
モジュールは、package-info.java
ファイルを通じて表されるパッケージの @ApplicationModule
アノテーションを使用して、許可された依存関係を宣言することを選択できます。たとえば、Kotlin はそのファイルをサポートしていないため、アプリケーションモジュールのルートパッケージにある単一の型にアノテーションを使用することもできます。
Java
Kotlin
@org.springframework.modulith.ApplicationModule(
allowedDependencies = "order"
)
package example.inventory;
package example.inventory
import org.springframework.modulith.ApplicationModule
@ApplicationModule(allowedDependencies = "order")
class ModuleMetadata {}
この場合、在庫モジュール内のコードは、オーダーモジュール内のコードを参照することのみが許可されていました (そして、コードはそもそもどのモジュールにも割り当てられていませんでした)。アプリケーションモジュール構造の検証でそれを監視する方法について調べましょう。
名前付きインターフェース
デフォルトでは、高度なアプリケーションモジュールに従って、アプリケーションモジュールの基本パッケージは API パッケージと見なされ、他のモジュールからの受信依存関係を許可する唯一のパッケージになります。追加のパッケージを他のモジュールに公開する場合は、名前付きインターフェースを使用する必要があります。これは、それらのパッケージの package-info.java
ファイルに @NamedInterface
または明示的に @org.springframework.modulith.PackageInfo
でアノテーションを付けることで実現します。
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
Java
Kotlin
@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 {}
この宣言の効果は 2 つあります。まず、他のアプリケーションモジュールのコードが SomeSpiInterface
を参照できるようになります。アプリケーションモジュールは、明示的な依存関係宣言で名前付きインターフェースを参照できます。インベントリーモジュールがそれを利用していると仮定すると、上記で宣言された名前付きインターフェースを次のように参照できます。
Java
Kotlin
@org.springframework.modulith.ApplicationModule(
allowedDependencies = "order :: spi"
)
package example.inventory;
@org.springframework.modulith.ApplicationModule(
allowedDependencies = "order :: spi"
)
package example.inventory
名前付きインターフェースの名前 spi
を二重コロン ::
で連結する方法に注目してください。この設定では、インベントリ内のコードは、SomeSpiInterface
および order.spi
インターフェースに存在する他のコードに依存することが許可されますが、たとえば OrderManagement
には依存しません。依存関係が明示的に記述されていないモジュールの場合、アプリケーションモジュールのルートパッケージと SPI パッケージの両方にアクセスできます。
アプリケーションモジュールが明示的に宣言されたすべての名前付きインターフェースを参照できることを表現する場合は、次のようにアスタリスク (*
) を使用できます。
Java
Kotlin
@org.springframework.modulith.ApplicationModule(
allowedDependencies = "order :: *"
)
package example.inventory;
@org.springframework.modulith.ApplicationModule(
allowedDependencies = "order :: *"
)
package example.inventory
モジュール検出のカスタマイズ
デフォルトでは、アプリケーションモジュールは、Spring Boot アプリケーションクラスが存在するパッケージの直接のサブパッケージに配置されるものと想定されます。Spring、Modulith の @ApplicationModule
または jMolecules @Module
アノテーションを介して明示的にアノテーションされたパッケージのみを考慮する代替検出戦略をアクティブ化できます。この戦略は、spring.modulith.detection-strategy
を explicitly-annotated
に構成することでアクティブ化できます。
spring.modulith.detection-strategy=explicitly-annotated
デフォルトのアプリケーションモジュール検出戦略も手動でアノテーションを付けた戦略もアプリケーションで機能しない場合は、ApplicationModuleDetectionStrategy
の実装を提供することでモジュールの検出をカスタマイズできます。そのインターフェースは単一のメソッド Stream<JavaPackage> getModuleBasePackages(JavaPackage)
を公開し、Spring Boot アプリケーションクラスが存在するパッケージで呼び出されます。次に、その中に存在するパッケージをインスペクションし、命名規則などに基づいてアプリケーションモジュールベースパッケージと見なすパッケージを選択できます。
次のようにカスタム ApplicationModuleDetectionStrategy
実装を宣言するとします。
ApplicationModuleDetectionStrategy
の実装 Java
Kotlin
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-strategy
として登録できます。
spring.modulith.detection-strategy=example.CustomApplicationModuleDetectionStrategy
アプリケーションモジュールの配置のカスタマイズ
Spring モジュリスを使用すると、メインの Spring Boot アプリケーションクラスで使用される @Modulithic
アノテーションを介して作成するアプリケーションモジュール配置に関するいくつかのコアアスペクトを構成できます。
Java
Kotlin
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 Modulith に、構成されたパッケージを追加のルートアプリケーションパッケージとして扱うように指示します。つまり、それらに対してもアプリケーションモジュールの検出がトリガーされます。 |