Spring BootでWebアプリケーションを開発していると、最初はきれいだったプロジェクトが、機能追加とともに徐々に複雑になっていくことがあります。

たとえば、次のような構成です。

controller
├── OrderController
├── ProductController
└── CustomerController

service
├── OrderService
├── ProductService
└── CustomerService

repository
├── OrderRepository
├── ProductRepository
└── CustomerRepository

小規模なうちは分かりやすいですが、サービスが大きくなるにつれて、

OrderServiceからProductServiceを呼ぶ
ProductServiceからCustomerServiceを呼ぶ
さらに別のServiceを呼ぶ

といった依存関係が増えていきます。

結果として、

「このクラスを変更すると、どこまで影響するのか分からない」

という状態になりがちです。

そこで使えるのが Spring Modulith です。

Spring Modulithを利用すると、Spring Bootアプリケーションを「注文」「在庫」「決済」といった業務機能単位に分割し、モジュール間の依存関係まで検証できます。

この記事では、注文と在庫を例に、

Spring Boot
     │
     ├── Order Module
     │
     └── Inventory Module

というモジュラーモノリスを実際に作りながら、Spring Modulithの基本を解説します。

Spring Modulithとは

Spring Modulithは、Spring Bootアプリケーションを業務機能単位のモジュールに分割するためのSpring公式プロジェクトです。

重要なのは、Spring Modulithを使ってもアプリケーションそのものは1つという点です。

                 Spring Boot Application
                         │
          ┌──────────────┼──────────────┐
          │              │              │
       Order          Inventory       Payment
       Module          Module          Module

Order、Inventory、Paymentという複数のモジュールがありますが、デプロイするアプリケーションは1つです。

このようなアーキテクチャを、

モジュラーモノリス（Modular Monolith）

と呼びます。

モノリス・モジュラーモノリス・マイクロサービスの違い

まず、この3つを整理しておきましょう。

一般的なモノリス

Spring Boot
│
├── Controller
├── Service
├── Repository
└── Entity

アプリケーション全体を1つのシステムとして作ります。

シンプルですが、規模が大きくなると依存関係が複雑になりやすい問題があります。

モジュラーモノリス

Spring Boot
│
├── Order
│   ├── API
│   └── Internal
│
├── Inventory
│   ├── API
│   └── Internal
│
└── Payment
    ├── API
    └── Internal

アプリケーション自体は1つですが、内部を業務機能単位に分割します。

マイクロサービス

Order Service
      │
      ├── HTTP / Messaging
      │
Inventory Service
      │
Payment Service

それぞれが独立したアプリケーションとして動作します。

デプロイやデータベース、通信なども分離できますが、そのぶん運用が複雑になります。

Spring Modulithは、この中間に位置するアプローチと考えると分かりやすいでしょう。

なぜモジュラーモノリスなのか

「それなら最初からマイクロサービスにすればいいのでは？」

と思うかもしれません。

しかしマイクロサービスにすると、

サービス間通信
認証
分散トランザクション
障害対策
ログの追跡
OpenTelemetryなどによる分散トレーシング
Kubernetesなどのインフラ管理

といった問題も増えます。

一方、モジュラーモノリスなら、

デプロイ単位：1
プロセス：1
↓
内部構造だけを明確に分割

できます。

そのため、

「まだマイクロサービスにするほどではないが、巨大なSpring Bootアプリケーションにはしたくない」

というケースで非常に使いやすい設計です。

今回作るアプリケーション

今回はECサイトのバックエンドをイメージします。

次の2つのモジュールを作ります。

Order
  注文を受け付ける

Inventory
  在庫を管理する

処理の流れは次のとおりです。

HTTP Request
     │
     ▼
Order Module
     │
     │ OrderCompleted Event
     ▼
Inventory Module
     │
     ▼
在庫を減らす

OrderモジュールがInventoryモジュールの内部クラスを直接呼び出すのではなく、イベントを使って連携させます。

プロジェクトを作成する

この記事では次の環境を想定します。

Java 21
Spring Boot 4.1.x
Gradle
Spring Modulith 2.1.1

build.gradleは次のようにします。

plugins {
    id 'java'
    id 'org.springframework.boot' version '4.1.0'
    id 'io.spring.dependency-management' version '1.1.7'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencyManagement {
    imports {
        mavenBom 'org.springframework.modulith:spring-modulith-bom:2.1.1'
    }
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.modulith:spring-modulith-starter-core'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.modulith:spring-modulith-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

Spring ModulithではBOMが用意されているため、各ライブラリのバージョンを個別に指定する必要はありません。

Spring Modulithではパッケージ構成が重要

Spring Modulithの特徴の1つが、Javaのパッケージ構成を利用してモジュールを定義することです。

Spring Bootのメインクラスを、

com.example.shop

に置いた場合、その直下にあるパッケージが基本的にモジュールとして認識されます。

今回なら次のようにします。

com.example.shop
│
├── ShopApplication.java
│
├── order
│   ├── OrderManagement.java
│   ├── OrderCompleted.java
│   │
│   └── web
│       └── OrderController.java
│
└── inventory
    └── internal
        └── InventoryEventListener.java

Spring Modulithから見ると、

order
inventory

がそれぞれApplication Moduleになります。

つまり、

com.example.shop.order

と

com.example.shop.inventory

が独立したモジュールとして扱われます。

Spring Bootの起動クラス

通常のSpring Bootアプリケーションと同じです。

package com.example.shop;

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

@SpringBootApplication
public class ShopApplication {

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

Spring Modulithだからといって、特殊な起動方法が必要になるわけではありません。

Orderモジュールを作る

まず注文を担当するOrderモジュールを作ります。

order
├── OrderManagement.java
├── OrderCompleted.java
└── web
    └── OrderController.java

ここで重要なのが、

order

直下と、

order.web

の違いです。

Spring Modulithでは基本的にモジュールのルートパッケージが、ほかのモジュールから利用可能なAPIになります。

つまり、

order.OrderManagement
order.OrderCompleted

はOrderモジュールが外部へ公開するAPIとして扱えます。

一方、

order.web
order.internal

などのサブパッケージは、基本的にモジュール内部の実装として扱われます。

OrderManagementを作る

注文処理を行うクラスを作ります。

package com.example.shop.order;

import java.util.UUID;

import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Service;

@Service
public class OrderManagement {

    private final ApplicationEventPublisher eventPublisher;

    public OrderManagement(ApplicationEventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }

    public UUID placeOrder(String sku, int quantity) {

        UUID orderId = UUID.randomUUID();

        // 本来はRepositoryなどを利用して注文を保存する
        System.out.println(
                "Order created: " + orderId
                        + ", sku=" + sku
                        + ", quantity=" + quantity
        );

        eventPublisher.publishEvent(
                new OrderCompleted(orderId, sku, quantity)
        );

        return orderId;
    }
}

通常のSpringの、

ApplicationEventPublisher

を使っています。

注文が完了すると、

OrderCompleted

イベントを発行します。

OrderCompletedイベント

イベントはJavaのrecordを使ってシンプルに定義します。

package com.example.shop.order;

import java.util.UUID;

public record OrderCompleted(
        UUID orderId,
        String sku,
        int quantity
) {
}

ここで重要なのは配置場所です。

order
└── OrderCompleted

Orderモジュールのルートパッケージに配置しています。

そのため、Inventoryなどの別モジュールから利用できます。

Controllerを作る

HTTP APIも用意します。

package com.example.shop.order.web;

import java.util.UUID;

import com.example.shop.order.OrderManagement;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/orders")
public class OrderController {

    private final OrderManagement orderManagement;

    public OrderController(OrderManagement orderManagement) {
        this.orderManagement = orderManagement;
    }

    @PostMapping
    public OrderResponse create(
            @RequestBody CreateOrderRequest request
    ) {

        UUID orderId = orderManagement.placeOrder(
                request.sku(),
                request.quantity()
        );

        return new OrderResponse(orderId);
    }
}

record CreateOrderRequest(
        String sku,
        int quantity
) {
}

record OrderResponse(
        UUID orderId
) {
}

ここまでで、

POST /orders

から注文を登録できます。

Inventoryモジュールを作る

続いて在庫管理です。

inventory
└── internal
    └── InventoryEventListener.java

Inventoryモジュールは、Orderモジュールから発行されたOrderCompletedを受け取ります。

package com.example.shop.inventory.internal;

import com.example.shop.order.OrderCompleted;

import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Component
class InventoryEventListener {

    @EventListener
    void on(OrderCompleted event) {

        System.out.println(
                "Reserve inventory: sku="
                        + event.sku()
                        + ", quantity="
                        + event.quantity()
        );
    }
}

ここでポイントなのが、

import com.example.shop.order.OrderCompleted;

です。

InventoryモジュールはOrderモジュールの公開APIであるOrderCompletedだけを参照しています。

OrderモジュールのRepositoryや内部Serviceを直接参照していません。

モジュール間の依存が弱くなる

この設計では、

Order
   │
   │ OrderCompleted
   ▼
Inventory

という関係になります。

Order側は、

「注文後にInventoryのどのServiceを呼べばよいか」

を知る必要がありません。

Orderが知っているのは、

注文が完了した

という事実だけです。

そのイベントを誰が処理するのかはOrderから切り離されています。

将来的に、

OrderCompleted
    │
    ├── Inventory
    ├── Mail
    ├── Point
    └── Analytics

のように処理を追加することもできます。

Spring Modulith最大の特徴「依存関係を検証する」

ここからがSpring Modulithのおもしろいところです。

単にパッケージを分けるだけなら、Spring Modulithを使わなくてもできます。

Spring Modulithでは、

本当にそのモジュール構成が守られているか

をテストできます。

次のテストを作ります。

package com.example.shop;

import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;

class ModulithArchitectureTest {

    @Test
    void verifyModules() {

        ApplicationModules
                .of(ShopApplication.class)
                .verify();
    }
}

これだけです。

.verify();

によってモジュール構造を検証できます。

verify()は何をチェックするのか

代表的には次のような問題を検出できます。

モジュール間の循環依存

たとえば、

Order
  ↓
Inventory
  ↓
Order

という状態です。

OrderがInventoryに依存し、InventoryもOrderに依存していると、アプリケーションの変更が難しくなります。

Spring Modulithでは、このようなモジュール間の循環依存を検出できます。

他モジュールの内部実装へのアクセス

たとえばInventoryに、

inventory
└── internal
    └── InventoryRepository

が存在するとします。

Orderから、

import com.example.shop.inventory.internal.InventoryRepository;

のように直接参照すると、モジュール境界を破っています。

Spring Modulithは、このような依存も検出できます。

つまり、

Order
  ↓
Inventory API

はOKですが、

Order
  ↓
Inventory Internal

はNGです。

Javaだけでは防げない問題を検出できる

ここはSpring Modulithを理解するうえで重要です。

Javaには、

public
private
protected

などのアクセス修飾子があります。

しかし、モジュール内部の事情によって、

public class InventoryRepository

としなければならない場合もあります。

publicにするとJavaコンパイラ上は別パッケージから参照できてしまいます。

そこでSpring Modulithが、

Javaとしてはアクセス可能

しかし

アーキテクチャとしてはアクセス禁止

というルールをテストで検証してくれます。

モジュール一覧を確認する

Spring Modulithがどのようにモジュールを認識しているのか確認することもできます。

@Test
void printModules() {

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

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

実行すると、

order
inventory

などのモジュール情報を確認できます。

既存プロジェクトへSpring Modulithを導入するときは、まずこれを実行してみると分かりやすいでしょう。

モジュール単位でテストする

Spring Modulithには、

@ApplicationModuleTest

という便利なテスト機能があります。

通常の、

@SpringBootTest

ではアプリケーション全体を起動します。

一方、

@ApplicationModuleTest

では、対象モジュールを中心にテストできます。

Orderモジュールのテストを作ってみます。

package com.example.shop.order;

import static org.assertj.core.api.Assertions.assertThat;

import java.util.UUID;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.modulith.test.ApplicationModuleTest;
import org.springframework.modulith.test.PublishedEvents;

@ApplicationModuleTest
class OrderModuleTest {

    @Autowired
    OrderManagement orderManagement;

    @Test
    void publishesOrderCompletedEvent(
            PublishedEvents events
    ) {

        UUID orderId =
                orderManagement.placeOrder(
                        "SKU-001",
                        2
                );

        var published =
                events.ofType(OrderCompleted.class)
                        .matching(
                                OrderCompleted::orderId,
                                orderId
                        );

        assertThat(published).hasSize(1);
    }
}

このテストでは、

注文する
↓
OrderCompletedが発行される

というOrderモジュールの責務を確認しています。

モジュール単位でテストするメリット

アプリケーションが大きくなると、

@SpringBootTest

によるテストは起動するBeanが増えていきます。

さらに、

Orderのテストなのに
Paymentも
Inventoryも
Customerも
起動する

という状態になりがちです。

モジュール単位でテストできれば、

Order Module
だけに注目

できます。

また、あるモジュールが大量の別モジュールへ依存している場合、

「このモジュール、責務を持ちすぎていないか？」

と気付くきっかけにもなります。

モジュール構成図も生成できる

Spring Modulithには、モジュール構成からドキュメントを生成する機能もあります。

たとえば次のようなテストを書けます。

package com.example.shop;

import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;
import org.springframework.modulith.docs.Documenter;

class DocumentationTest {

    @Test
    void createDocumentation() {

        ApplicationModules modules =
                ApplicationModules
                        .of(ShopApplication.class)
                        .verify();

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

すると、モジュール間の関係を表すPlantUMLなどを生成できます。

イメージとしては、

┌──────────────┐
│    Order     │
└──────┬───────┘
       │ OrderCompleted
       ▼
┌──────────────┐
│  Inventory   │
└──────────────┘

のような構成です。

設計書を手作業で更新するのではなく、実際のコードからアーキテクチャドキュメントを生成できるのは実務でも便利です。

allowedDependenciesでさらに厳しくする

規模が大きくなってきたら、

「このモジュールはどのモジュールに依存してよいか」

まで明示できます。

package-info.javaを利用します。

たとえばInventoryモジュールがOrderだけに依存できるようにする場合です。

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

これによって、

Inventory
    ↓
Order

は許可されます。

しかし、

Inventory
    ↓
Payment

など、定義されていない依存を作ると検証で検出できます。

大規模なシステムほど効果が大きい機能です。

Named Interfaceとは

さらに細かくAPIを公開したい場合、

@NamedInterface

を利用できます。

通常、

order

のルートパッケージがAPIになります。

しかし、

order
└── api

のような別パッケージを明示的に公開したいケースもあります。

その場合、

@org.springframework.modulith.NamedInterface("api")
package com.example.shop.order.api;

のように定義できます。

そして依存側では、

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

と指定できます。

これによって、

Inventory
↓
Order API

だけを許可し、

Inventory
↓
Order Internal

を禁止できます。

レイヤードアーキテクチャとの違い

従来のSpring Bootでは、

controller
service
repository
entity

という「技術」でパッケージを分けるケースが多いでしょう。

これはレイヤードアーキテクチャとして非常に一般的です。

しかし規模が大きくなると、

service
├── OrderService
├── PaymentService
├── InventoryService
├── CustomerService
├── PointService
├── CouponService
└── MailService

のようになり、1つのパッケージへ大量のクラスが集まってきます。

Spring Modulithでは逆に、

order
├── OrderController
├── OrderService
├── OrderRepository
└── Order

inventory
├── InventoryController
├── InventoryService
├── InventoryRepository
└── Inventory

payment
├── PaymentController
├── PaymentService
├── PaymentRepository
└── Payment

というように業務機能を中心にまとめる考え方になります。

つまり、

技術単位

ではなく、

業務・ドメイン単位

で分割します。

Spring Modulithを使えばDDDになるわけではない

Spring Modulithを調べると、DDD（Domain-Driven Design）という言葉がよく出てきます。

ただし、

Spring Modulithを使う
=
DDDが完成する

というわけではありません。

Spring Modulithが提供してくれるのは、

ドメイン単位で分割しやすくする仕組み

です。

どこまでをOrderとするか、どこからInventoryにするかといった境界は、開発者が業務要件を考えて設計する必要があります。

Spring Modulithが向いているケース

特に向いているのは、

中〜大規模なSpring Bootアプリケーション

機能が増えてService同士の依存が複雑になっている場合です。

将来的にマイクロサービス化する可能性がある

あらかじめ、

Order
Inventory
Payment

という境界を作っておけば、将来サービスを分離するときにも考えやすくなります。

ただし、「Spring Modulithを使えば簡単にマイクロサービス化できる」という意味ではありません。

データベース境界や分散トランザクション、ネットワーク通信など別の問題は残ります。

チーム開発

Team A → Order
Team B → Inventory
Team C → Payment

のように責務を整理しやすくなります。

アーキテクチャのルールを自動テストしたい

Spring Modulithの大きな強みです。

人間のレビューだけでは、

OrderからInventoryのRepositoryを直接呼んでいる

といったルール違反を見逃す可能性があります。

Spring ModulithならCIで、

./gradlew test

を実行するだけでアーキテクチャを継続的に検証できます。

Spring Modulithが向いていないケース

逆に、非常に小さなCRUDアプリなら無理に導入する必要はありません。

たとえば、

Controller
↓
Service
↓
Repository

だけで完結する小規模アプリなら、Spring Modulithを導入してもメリットを感じにくいでしょう。

モジュール境界について考えるコストも発生します。

重要なのは、

Spring Modulithを使うこと

ではなく、

システムの責務と依存関係を整理すること

です。

実務ではイベント連携が重要になる

今回の記事では、

Order
   │
   │ OrderCompleted
   ▼
Inventory

というイベント連携を紹介しました。

この設計を進めると、次の疑問が出てきます。

イベント処理中にアプリが落ちたら？

Inventoryの処理が失敗したら？

イベントをKafkaやSQSへ送りたい場合は？

注文DBへの保存は成功したのにイベント送信が失敗したら？

ここから、

Transactional Event
Event Publication Registry
Transactional Outbox Pattern
Kafka
Amazon SQS
冪等性

といったバックエンド設計につながっていきます。

Spring Modulithは単なるパッケージ整理ツールではなく、こうしたイベント駆動アーキテクチャを学ぶ入り口としても非常に面白い技術です。

まとめ

Spring Modulithを利用すると、Spring Bootアプリケーションを業務機能単位で整理できます。

今回のポイントをまとめると、

従来

Controller
↓
Service
↓
Repository

だけで考えるのではなく、

Spring Boot
│
├── Order Module
├── Inventory Module
└── Payment Module

という単位でアプリケーションを設計できます。

さらにSpring Modulithでは、

モジュール検出
↓
依存関係検証
↓
モジュール単位のテスト
↓
イベント連携
↓
ドキュメント生成

までサポートされています。

特に重要なのが、

ApplicationModules
        .of(ShopApplication.class)
        .verify();

です。

単に「パッケージを分けました」で終わらず、そのアーキテクチャが守られていることをテストで保証できるのがSpring Modulithの大きなメリットです。

Spring Bootアプリケーションが大きくなり、

Service同士の依存関係が複雑になってきた

マイクロサービスにするほどではないが、アプリケーションを整理したい

という場合は、Spring Modulithを検討してみる価値があります。

そしてSpring Modulithを理解した後におすすめなのが、

Transactional Outbox Pattern

です。

「注文をDBへ保存できたのに、イベントの送信には失敗した」という問題をどのように解決するのか。

この問題を理解すると、Spring Modulithだけでなく、KafkaやAmazon SQSを使ったイベント駆動システムの設計にもつながっていきます。

ぜひご参考ください！

是非フォローしてください

Follow @https://twitter.com/fuji67600543

最新の情報をお伝えします

Spring Modulithとは

モノリス・モジュラーモノリス・マイクロサービスの違い

一般的なモノリス

モジュラーモノリス

マイクロサービス

なぜモジュラーモノリスなのか

今回作るアプリケーション

プロジェクトを作成する

Spring Modulithではパッケージ構成が重要

Spring Bootの起動クラス

Orderモジュールを作る

OrderManagementを作る

OrderCompletedイベント

Controllerを作る

Inventoryモジュールを作る

モジュール間の依存が弱くなる

Spring Modulith最大の特徴「依存関係を検証する」

verify()は何をチェックするのか

モジュール間の循環依存

他モジュールの内部実装へのアクセス

Javaだけでは防げない問題を検出できる

モジュール一覧を確認する

モジュール単位でテストする

モジュール単位でテストするメリット

モジュール構成図も生成できる

allowedDependenciesでさらに厳しくする

Named Interfaceとは

レイヤードアーキテクチャとの違い

Spring Modulithを使えばDDDになるわけではない

Spring Modulithが向いているケース

中〜大規模なSpring Bootアプリケーション

将来的にマイクロサービス化する可能性がある

チーム開発

アーキテクチャのルールを自動テストしたい

Spring Modulithが向いていないケース

実務ではイベント連携が重要になる

まとめ

類似投稿