spring-modulith-verifier

Spring Modulith 検証スキル

ドメイン駆動のモジュール型レイアウトを使用し、技術レイヤーではなくビジネスモジュールごとにパッケージを構成します。

推奨するパッケージ構成の例

dev.sivalabs.projectname/
├── Application                      # Main Spring Boot entrypoint class
├── shared/                          # Cross-cutting concerns
│   ├── package-info.java
├── users/                           # Users module (bounded context)
│   ├── config/                      # Users module-specific config
│   ├── domain/                      # Domain logic
│   │   ├── models/                  # Domain models
│   │   │   ├── package-info.java
│   │   ├── exceptions/              # Domain custom Exception classes
│   │   │   ├── package-info.java
│   │   ├── {entities, repositories, mappers, services}
│   ├── api/                        # REST API layer
│   │   ├── {controllers, DTOs}      # REST controllers, Request, Response payload DTOs
│   └── UsersAPI.java                # Module's public API (facade)
│
├── catalog/                         # Catalog module
├── orders/                          # Orders module
└── config/                          # Global Configuration
    └── WebMvcConfig.java
    └── SecurityConfig.java
    └── WebSecurityConfig.java
    └── GlobalExceptionHandler.java

上記のパッケージ構成の説明：

• Application.java：@SpringBootApplication が付与された、Spring Boot のメインエントリークラスです。アプリケーションを起動する main() メソッドを含みます。

• shared/：複数のモジュールで共有される横断的な関心事やユーティリティ（共通ユーティリティ、共有 DTO、基底クラス、カスタムアノテーションなど）を格納します。

• {module}/（例：users/、catalog/、orders/）：各ビジネスモジュールは境界づけられたコンテキストを表し、以下を含みます。

  • config/：このモジュールにのみ関連する Bean、プロパティ、サードパーティとの連携を設定するための、@Configuration が付与されたモジュール固有の設定クラスです。

  • domain/：中核となるビジネスロジック層で、以下を含みます。

    • models/：ビジネス概念を表すドメインモデルクラス（Command、Query オブジェクト、Enum、値オブジェクト、Result オブジェクトなど）を格納します（JPA エンティティではありません）。ビジネスルールをカプセル化する、純粋な Java オブジェクトです。
    • exceptions/：ドメイン固有のカスタム例外クラスを格納します。
    • entities：データベーステーブルにマッピングする、@Entity が付与された JPA エンティティクラスを格納します。直接インスタンス化されないようにし、カプセル化を確保するため、public にしないでください。
    • repositories：データアクセス用の JpaRepository または CrudRepository を継承する Spring Data JPA リポジトリーインターフェースを格納します。public にしないでください。
    • mappers：エンティティ、ドメインモデル、DTO の間で変換を行うマッパークラス／インターフェース（MapStruct マッパーなど）を格納します。public にしないでください。
    • services：@Service が付与されたサービスクラスを格納します。ビジネスロジック、マッパーを使用した Bean の変換、トランザクション管理、リポジトリー呼び出しのオーケストレーションを担います。

  • api/：REST API 層で、以下を含みます。

    • controllers：HTTP リクエストを処理し、入力を検証してサービスに委譲する、@RestController が付与された REST コントローラークラスを格納します。
    • DTOs：リクエストペイロード（クライアントから受け取るデータ）とレスポンスペイロード（クライアントに送信するデータ）を含む、データ転送オブジェクトを格納します。

  • {Module}API.java：サービスに処理を委譲するファサードクラスです。モジュールの公開 API として機能し、内部実装の詳細を隠しながら、他のモジュールがアクセスすべきもののみを公開します。

• config/：アプリケーション全体に適用する設定クラスを格納します。以下を含みます。

  • WebMvcConfig.java：MVC 設定（CORS、インターセプター、フォーマッター）。
  • SecurityConfig.java：認証と認可のための Spring Security 設定。
  • GlobalExceptionHandler.java：一貫したエラーレスポンスを実現するため、@RestControllerAdvice を使用した一元的な例外処理。

可視性修飾子

必要最小限の可視性をデフォルトとします。他のモジュールやレイヤーが本当に必要とするものだけを公開してください。

コンポーネント	クラス	コンストラクター	メソッド
コントローラー	パッケージプライベート	パッケージプライベート	パッケージプライベート
サービス	public	パッケージプライベート	public
リポジトリー	パッケージプライベート（インターフェース）	—	—
エンティティ	パッケージプライベート	protected	public
DTO／record	public またはパッケージプライベート	—	—
モジュール API ファサード	public	パッケージプライベート	public
リクエスト／レスポンス record	パッケージプライベート	—	—
設定／例外ハンドラー	パッケージプライベート	—	—

Naming Conventions

Type	Convention	Example
Entities	*Entity	UserEntity, AddressEntity
Value Objects	Domain name (record)	Email, UserCode, UserId
Commands	*Cmd	CreateUserCmd, UpdateAddressCmd
Command Response	*Result	LoginResult, RegistrationResult
DTOs	*Dto	UserDto, AddressDto
HTTP Request	*Request	CreateUserRequest, CreateAddressRequest
HTTP Response	*Response	CreateUserResponse, CreateAddressResponse
Repositories	*Repository	UserRepository, AddressBookRepository
Services	*Service	UserService, AddressBookService
Domain Exceptions	*Exception	InvalidUserCreationException, UserCancellationException
Module API	*API	UsersAPI