大規模Mavenマルチモジュールを高速化せよ！『Maven Incremental Build』を正しく機能させるための設計思想
こんにちは。開発環境アーキテクトの私だ。
これまで数千を超えるエンタープライズJavaプロジェクトのビルドパイプラインを診断・最適化してきたが、いまだに次のような悲痛な叫びを耳にする。
> 「モノリスから移行した数百モジュールのMavenマルチモジュール構成で、たった1行のコメントを直しただけなのに、フルビルドが走ってしまいCIに15分かかる」
> 「ローカルでの開発ループ（コーディング→ビルド→検証）が遅すぎて、開発者の生産性がドブに捨てられている」
ネットを検索すれば「`-T 1C` をつけて並列ビルドしろ」「`-o` オプションでオフラインモードにしろ」といった、どこにでもある浅いアドバイスが溢れている。だが、それらは対症療法に過ぎない。根本的な解決策は、Mavenのコアメカニズムである「インクリメンタルビルド（Incremental Build）」の本質を理解し、それが破綻する原因を物理的に断ち切る事にある。
今回は、Mavenマルチモジュールのビルド時間を極限まで削ぎ落とし、CI/CDパイプラインとコンテナ環境を支配するための「最高峰のアーキテクチャ設計」を授けよう。
—
1. なぜMavenのインクリメンタルビルドはデフォルトで機能しないのか？
まず、Mavenの思想とアーキテクチャの内部に踏み込む。
Mavenは本来、宣言的ビルドツールであり、各ライフサイクルフェーズ（`compile`, `test`, `package` 等）はプラグインのゴールに紐づいている。
標準の `maven-compiler-plugin` は、ソースコードのタイムスタンプ（`.java`）と、出力先ディレクトリ（`target/classes`）のクラスファイルのタイムスタンプを比較し、変更がないファイルのコンパイルをスキップする機能（内部的にはplexus-compilerの仕組み）を持っている。
では、なぜ「マルチモジュール」になるとインクリメンタルビルドが崩壊するのか？
原因の解剖：
1. 「汚染された」リアクティブな依存関係解決
モジュールAがモジュールBに依存しているとき、モジュールBのAPI（シグネチャ）に変更がなくても、モジュールBのビルドが走ると `target/` がクリア（`clean`）されるか、成果物が再生成される。Mavenのリアクター（Reactor）は、依存関係グラフに基づき「依存元モジュール」の再ビルドを誘発する。
2. 不適切な `clean` の常態化
「とりあえず確実なビルドをしたいから」という理由で、CIやローカルスクリプトの常枕として `mvn clean package` が実行されている。`clean` を叩いた瞬間、ファイルシステム上のタイムスタンプはすべて現在時刻にリセットされ、インクリメンタルビルドの前提条件である「過去の成果物とのタイムスタンプ比較」が完全に破壊される。
3. 無駄なジェネレータ（Lombok, MapStruct, QueryDSL等）の暴走
コード生成系のアノテーションプロセッサが、入力ファイルの変更がなくても毎回のビルドでファイルを吐き出し直すため、コンパイラプラグインが「変更あり」と誤認する。
これを克服するには、「タイムスタンプ依存からの脱却」と「モジュール間結合の疎文化」の2つを同時に達成しなければならない。
—
2. 変更検出を最適化する `maven-compiler-plugin` とキャッシュ戦略
まず、コンパイルレイヤーでの無駄を根絶する。
以下の設定は、大規模マルチモジュールのルート `pom.xml`（あるいはビルドプラットフォーム用parent POM）の `
アーキテクトの知見：なぜ `mvn clean` を殺すべきなのか？
「ビルドが壊れたらとりあえず `clean`」という文化をチームから排除せよ。
現代のMavenにおいて、適切なプラグイン設定がされていれば、`clean` は「SNAPSHOTの依存関係がローカルリポジトリで破損した時」または「IDEとの同期ズレ」以外で使う必要はない。
CI/CDパイプラインにおいても、`mvn package`（`clean` なし）を基本とし、後述するファイルハッシュベースのキャッシュ機構と組み合わせるのが正解だ。
—
3. モジュール間の依存関係を疎にする設計パターン
数百モジュールある巨大なコードベースでは、モジュールAの「単なる内部実装の変更」によってモジュールB、C、D……と、ドミノ倒し式に再ビルドが発生する構造（密結合）が最大のボトルネックになる。
これを解決するためのアーキテクチャ原則を提示する。
原則1: インターフェイスと実装の分離（API/SPIパターン）
モジュールを以下の2つに強制分離する。
- `module-X-api`: DTO、サービスインターフェイス、例外クラスのみを含む（変更頻度が極めて低い）。
- `module-X-impl`: 具体的なビジネスロジック、フレームワーク依存実装を含む。
依存関係の矢印を常に `impl -> api` の単一方向に制限する。これにより、`impl` 側のコードを変更しても、`api` に依存している他のモジュール群は再コンパイルの対象外となる。Mavenのリアクターは、`.class` のバイトコードやAPIシグネチャに変更がない場合、依存する上位モジュールの再ビルドを賢くスキップするようになる。
原則2: 不必要な推移的依存（Transitive Dependencies）の遮断
親POMの `
—
4. CI/CDパイプラインにおける極限の高速化：ファイルハッシュ駆動キャッシュ
GitHub Actions、GitLab CI、JenkinsなどのCI環境において、ワークスペースが毎回クリーンな状態から始まる場合、Mavenのローカルリポジトリ（`~/.m2/repository`）とビルドキャッシュをどう維持するかが勝負の分かれ目となる。
ここで紹介するのは、単なるディレクトリキャッシュではなく、「ソースコードのハッシュ値に基づくインクリメンタルビルド戦略」だ。
GitLab CI / GitHub Actions 向けの高度なキャッシュ戦略（概念設計）
単に `~/.m2` をキャッシュするだけでは不十分だ。なぜなら、自社製モジュールの成果物（JAR）も `~/.m2` にインストールされるか、リアクター内で解決される必要があるからだ。
以下のシェルスクリプトは、CIのビルド前処理として、変更のあったモジュールを特定し、無関係なモジュールのビルドをスキップするカスタムCLIロジックの概念である。
!/usr/bin/env bash
set -euo pipefail
—————————————————————–
変更されたファイルから、ビルドすべきMavenモジュールを動的抽出するスクリプト
—————————————————————–
1. 前回のコミットから変更があったファイル群を取得
CHANGED_FILES=$(git diff –name-only HEAD~1 HEAD)
echo “=== 変更されたファイル ===”
echo “$CHANGED_FILES”
2. 変更されたモジュールのpom.xmlまたはソースパスを特定
AFFECTED_MODULES=””
for file in $CHANGED_FILES; do
# ディレクトリのルート名（モジュール名）を抽出
MODULE_DIR=$(echo “$file” | cut -d’/’ -f1)
if [ -f “$MODULE_DIR/pom.xml” ]; then
# 該当モジュールをビルド対象リストに追加（重複排除）
if [[ ! “$AFFECTED_MODULES” =~
$MODULE_DIR
]]; then
AFFECTED_MODULES=”$AFFECTED_MODULES,$MODULE_DIR”
fi
fi
done
先頭のカンマを削除
AFFECTED_MODULES=$(echo “$AFFECTED_MODULES” | sed ‘s/^,//’)
if [ -z “$AFFECTED_MODULES” ]; then
echo “ソースコードの変更がJavaモジュール外のため、ビルドをスキップします。”
exit 0
fi
echo “=== 影響を受けるモジュール: $AFFECTED_MODULES ===”
3. Mavenの Reactor を用いて、影響を受けるモジュールとその依存関係のみをビルド
-am (also-make): 依存している下流モジュールも含めてビルド
-amd (also-make-dependents): このモジュールに依存している上流モジュールも含めてビルド（必要に応じて選択）
mvn package -pl “$AFFECTED_MODULES” -am -T 1C -DskipTests=true
このスクリプトをパイプラインに組み込むことで、巨額のコストがかかる全モジュールのフルビルドを回避し、変更箇所にピンポイントで最適化されたビルドを実現できる。
—
5. Dockerコンテナ環境における完全自動構成とレイヤー最適化
DockerでJava/Mavenアプリケーションをビルドする際、Dockerfileの書き方一つでビルド時間が数分単位で変わる。
「ソースコードをコピーして `mvn clean package` を実行する」という愚劣なDockerfileを書いているなら、今すぐ直したまえ。Dockerのレイヤーキャッシュを極限までハックするのがプロの作法だ。
以下のマルチステージビルドかつ依存関係キャッシュを最大化するDockerfileを提示する。
=================================================================
Stage 1: 依存関係解決レイヤー (Dependency Caching Layer)
=================================================================
FROM maven:3.9.6-eclipse-temurin-21 AS dependency-resolver
WORKDIR /build
ルートのpom.xmlと、全子モジュールのpom.xmlだけを先にコピーする
（ソースコードはまだコピーしない。これにより、Javaコードを変更しても依存関係が変わらなければこのレイヤーはキャッシュされる）
COPY pom.xml .
COPY module-api/pom.xml module-api/
COPY module-core/pom.xml module-core/
COPY module-web/pom.xml module-web/
※実際にはfindコマンドなどで動的にpom.xml構造を保つか、全モジュールのpom配置を同期させる
依存関係を一括ダウンロード（オフラインビルドの準備およびリポジトリの温め）
RUN mvn dependency:go-offline -B
=================================================================
Stage 2: ビルドレイヤー (Incremental Build Layer)
=================================================================
FROM dependency-resolver AS builder
WORKDIR /build
ここで初めて全ソースコードをコンテナ内に転送
COPY . .
cleanを排除し、インクリメンタルコンパイルを活かしたパッケージング
テストはCIの別ステージで実行するため、ここではスキップ
RUN mvn package –offline -DskipTests=true -T 1C
=================================================================
Stage 3: 実行用ランタイムレイヤー (Runtime Image)
=================================================================
FROM eclipse-temurin:21-jre-jammy AS runtime
WORKDIR /app
ビルドステージから必要な成果物（JAR）のみを抽出
COPY –from=builder /build/module-web/target/module-web-exec.jar app.jar
セキュリティ担保のため非特権ユーザーで実行
USER 10001:10001
EXPOSE 8080
ENTRYPOINT [“java”, “-XX:+UseContainerSupport”, “-XX:MaxRAMPercentage=75.0”, “-jar”, “app.jar”]
このDocker設計の真髄：
Javaのソースコード（`.java`）を変更して `docker build` を走らせたとき、Stage 1（`dependency-resolver`）のレイヤーは完全にキャッシュからヒットする。
つまり、外部ライブラリ（Spring Boot、Hibernate、各種ドライバ等）のダウンロードという、ネットワークとI/Oに最も負荷がかかるプロセスが完全にバイパスされ、ビルド時間が劇的に短縮されるのだ。
—
6. JVMメモリとMaven内部プロセスの最適化ハック
最後に、Maven自体を動かすJVMのチューニングについてだ。大規模マルチモジュールを扱うMavenは、メモリを大量に消費し、GC（ガベージコレクション）の停止時間がビルドの足を引っ張る。
開発端末やCIサーバーの環境変数（`MAVEN_OPTS`）に、以下のフラグを必ず設定せよ。
export MAVEN_OPTS=”-Xms2g -Xmx4g -XX:+UseG1GC -XX:InitiatingHeapOccupancyPercent=45 -XX:MaxGCPauseMillis=50 -Djava.awt.headless=true”
各パラメータの技術的解説：
- `-Xms2g -Xmx4g`: ヒープログの拡張によるGC発生頻度の抑制。数百モジュールの依存関係グラフ（ASTやプロジェクトオブジェクトモデル）はJVMヒープ上に巨大なオブジェクトツリーを生成するため、初期ヒープを小さくしすぎるとリサイズオーバヘッドで失速する。
- `-XX:+UseG1GC`: 大規模ヒープ向けに最適化されたG1コレクタを採用し、Stop-the-World（STW）時間を最小化する。
- `-XX:MaxGCPauseMillis=50`: Mavenのビルドプロセスにおいて、GCによる微小なタイムラグが全体の並列処理（`-T` オプション）のディスパッチを乱すのを防ぐ。
—
総括
Mavenマルチモジュールの高速化は、単なる「おまじないのコマンド」ではなく、「ビルドパイプラインのデータフローと依存関係の物理的制約をコントロールする芸術」である。
1. `mvn clean` という悪習を捨て、インクリメンタルコンパイルを信じること。
2. API/SPIパターンでモジュール間結合を断ち、無駄な連鎖再ビルドを防ぐこと。
3. Dockerのレイヤーキャッシュ構造を逆算したファイル配置設計を行うこと。
4. 適切なJVMメモリチューニングでMavenのエンジンを限界まで唸らせること。
これらをあなたのチームのアーキテクチャに導入した瞬間から、待ち時間という名の無駄なコストは消え去り、極限まで洗練された開発エクスペリエンスが手に入るだろう。健闘を祈る。