1. ホーム /
  2. アプリ開発 /
  3. 【Maven 実践編】Maven依存関係マスターガイド：競合解決から効率的なバージョン管理まで徹底解説します！
  • 2026.01.03

【Maven 実践編】Maven依存関係マスターガイド：競合解決から効率的なバージョン管理まで徹底解説します！

プロジェクトにおけるMaven依存関係の課題

「昨日まで動いていたのに、なぜかビルドが通らない」、「新しいライブラリを追加したら、NoSuchMethodError が発生した」、「./mvnw dependency:tree の出力が長く、問題箇所が不明瞭」といった経験は、多くの開発者が直面するMaven依存関係の課題です。

Mavenはその強力な依存関係解決機能を持つ一方で、その複雑な仕組みが時に予期せぬ問題を引き起こすことがあります。本記事では、依存関係の競合が発生するメカニズムから、具体的な解決策、そして効率的な管理手法までを包括的に解説します。

これにより、開発者は依存関係の問題に確実に対処し、安定したビルド環境を構築するための知識を得ることができます。

目次

対象読者

  • Mavenプロジェクトで依存関係の競合に頻繁に遭遇する開発者
  • NoSuchMethodError や ClassNotFoundException などの実行時エラーの原因を特定し、解決したい開発者
  • Mavenの依存関係管理について、より深く理解し、効率的な管理手法を学びたい開発者
  • 大規模プロジェクトや複数のモジュールを持つプロジェクトで、依存関係の一貫性と安定性を確保したいチームリーダーやアーキテクト

1. なぜ「依存関係地獄」は発生するのか？

依存関係地獄の根本原因は、主に2つのキーワードで説明できます。

  1. 推移的依存関係 (Transitive Dependencies): 依存が依存を呼び、見えない依存関係が生まれる仕組み。
  2. バージョン競合 (Version Conflict): 推移的依存の結果、同じライブラリの複数バージョンがプロジェクトに入り込もうとする状態。

これらがどのように絡み合い、問題を引き起こすのかを順を追って見ていきましょう。

1.1. 推移的依存関係：利便性と潜在的リスク

まず、Mavenの便利な機能である「推移的依存関係」から解説します。

あなたがプロジェクトで Library-A を使いたいとします。そして、その Library-A が内部で Common-Lib という共通ライブラリを必要としている状況を想像してください。

<!-- あなたのpom.xml -->
<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>library-a</artifactId>
        <version>1.0</version>
    </dependency>
</dependencies>

このとき、あなたは pom.xml に Library-A を記述するだけで、Mavenが自動的に Library-A が必要とする Common-Lib も一緒にダウンロードしてクラスパスに追加してくれます。

この「依存関係の依存先」を自動で解決してくれる仕組みが推移的依存関係です。

推移的依存関係：「依存関係の依存先」を自動で解決してくれる仕組み

図の解説: あなたは Library-A を直接依存関係として指定するだけです。Library-A が依存している Common-Lib は、Mavenによって自動的に（推移的に）プロジェクトへ取り込まれます。この機能は非常に便利ですが、依存の階層が深くなるにつれて、「自分のプロジェクトが、最終的にどのライブラリのどのバージョンに依存しているのか」が見えにくくなるというリスクを内包しています。

これが「地獄」への入り口です。

1.2. バージョン競合：推移的依存が引き起こす問題

次に、推移的依存のリスクが顕在化する「バージョン競合」を見ていきましょう。

先の例に加え、あなたのプロジェクトが Library-B も利用したくなったとします。しかし、この Library-B は、Common-Lib の別のバージョンに依存していました。

  • Library-A は Common-Lib v1.0 に依存
  • Library-B は Common-Lib v2.0 に依存
推移的依存が引き起こすバージョン競合問題

図の解説: あなたのプロジェクトは、2つの異なるバージョンの Common-Lib (v1.0 と v2.0) を同時に必要とする状況に陥りました。Javaのクラスパスには、同じクラス（com.example.CommonLib）をバージョン違いで2つ含めることはできません。これがバージョン競合です。

Mavenは、この競合を解決するために、どちらか一方のバージョンだけを自動的に選択します。

この選択ルールを知らないと、意図しないライブラリが使われ、深刻なエラーを引き起こすことになるのです。

1.3. Mavenのバージョン解決ルール：「最近傍が優先」

このような競合が発生した場合、Mavenは「最近傍優先（Nearest Definition）」というルールに従って、どちらか一方のバージョンを自動的に選択します。

上記の例では、Common-Lib へのパスはどちらも同じ深さ（2階層）なので、pom.xml 内で Library-A と Library-B のどちらが先に宣言されているかによって、採用されるバージョンが決まります。

これは、あなたのプロジェクトの pom.xml から見て、依存関係ツリーの階層が最も浅い（近い）バージョンが採用されるというルールです。

より具体的な例を以下の図で見てみましょう。

プロジェクトの pom.xml から見て、依存関係ツリーの階層が最も浅い（近い）バージョンが採用される

この図では、Your Project が Common-Lib の2つの異なるバージョン (v1.0 と v2.0) に依存する可能性を秘めていますが、パスの深さが異なります。

  • Common-Lib v2.0 へのパス: Your Project → Library-A v1.0 → Common-Lib v2.0 (深さ：2)
  • Common-Lib v1.0 へのパス: Your Project → Library-B v1.0 → Library-C v1.0 → Common-Lib v1.0 (深さ：3)

「最近傍が優先」ルールにより、より浅いパス（深さ2）にある Common-Lib v2.0 がMavenによって選択され、Common-Lib v1.0 は除外されます。

このように、依存関係のツリーにおいて、目的のライブラリまでのパスが最も短いものが優先的に採用されるのがMavenの動作です。

この自動解決は便利ですが、意図しないバージョンのライブラリが採用されることで NoSuchMethodError や ClassNotFoundException といった実行時エラーを引き起こす、諸刃の剣でもあるのです。

1.4. 具体的シナリオ：NoSuchMethodError の発生メカニズム

言葉だけではピンとこないかもしれません。具体的なコードと図で、何が起こるかを見ていきましょう。

ステップ1. Common-Lib のバージョンによるメソッドの有無

まず、共通ライブラリ Common-Lib に異なるバージョンが存在し、doSomethingAdvanced() メソッドの有無に違いがあるとします。

// Common-Lib v1.0 のコード
package com.example;

public class CommonLib {
    public void doSomethingSimple() {
        System.out.println("Doing something simple (v1.0)");
    }
    // doSomethingAdvanced() メソッドは存在しない
}
// Common-Lib v2.0 のコード
package com.example;

public class CommonLib {
    public void doSomethingSimple() {
        System.out.println("Doing something simple (v2.0)");
    }

    // v2.0 で追加された新しいメソッド
    public void doSomethingAdvanced() {
        System.out.println("Doing something advanced (v2.0)");
    }
}

ステップ2. Library-B は Common-Lib v2.0 に依存し、新機能を利用

Library-B は Common-Lib v2.0 を前提に開発され、新しく追加された doSomethingAdvanced() メソッドを呼び出しています。

Library-B がビルドされる際には、Library-BのプロジェクトにCommon-Lib v2.0 がクラスパスに存在するため、コンパイルは成功します。

// Library-B の内部コード
package com.example;

import com.example.CommonLib;

public class LibraryB_Processor {
    public void process() {
        CommonLib common = new CommonLib();
        // v2.0 で追加された新メソッドを意気揚々と使う
        common.doSomethingAdvanced();
    }
}

ステップ3. MyProject での依存関係の競合と解決

あなたのプロジェクト（MyProject）は、Library-A と Library-B の両方に依存しているとします。ここで問題が発生します。

  • Library-A は古い Common-Lib v1.0 に依存。
  • Library-B は新しい Common-Lib v2.0 に依存。

Mavenの「最近傍が優先」ルールにより、MyProject のクラスパスには、残念ながら古い Common-Lib v1.0 が採用されてしまいました。以下の図でこの状況を示します。

MyProject での依存関係の競合と解決

図の解説: MyProject から Common-Lib v1.0 と Common-Lib v2.0 への推移的依存のパスの深さが同じ場合、Mavenは pom.xml で先に宣言されている方の Common-Lib のバージョンを採用します。このシナリオでは、古い v1.0 が何らかの理由（pom.xmlでの宣言順や他の依存関係の深さなど）で「最近傍」と判断され、採用されてしまったとします。

ステップ4. MyProject のビルドは成功する

あなたの MyProject がビルドされる際、Library-B 自体は Common-Lib v2.0 を使って正常にコンパイルされた JAR ファイルとして既に存在しています。

MyProject は単に Library-B の JAR を参照するだけであり、Library-B が内部で doSomethingAdvanced() を呼び出していることを、この時点では検証しません。そのため、MyProject のビルドも一見問題なく成功してしまいます。

MyProject のビルドは成功する

ステップ5. 実行時に NoSuchMethodError が発生

しかし、アプリケーションを実行し、Library-B の process() メソッド（Common-Lib.doSomethingAdvanced() を呼び出す部分）が実行されると、問題が発生します。

MyProject の実行時クラスパスには、Common-Lib v1.0 しか存在しません。

この v1.0 には doSomethingAdvanced() メソッドは定義されていないため、JVMはそのメソッドを見つけることができず、NoSuchMethodError が発生してアプリケーションはクラッシュします。

実行時に NoSuchMethodError が発生

アプリケーションの実行コードは以下のようになります。ここで LibraryB_Processor の process() メソッドが呼び出されます。

// MyProject の Main クラス (簡略化)
package com.yourcompany.yourapp;

import com.example.LibraryB_Processor;

public class Main {
    public static void main(String[] args) {
        System.out.println("アプリケーション開始...");
        LibraryB_Processor processor = new LibraryB_Processor();
        processor.process(); // ここで NoSuchMethodError が発生！
        System.out.println("アプリケーション終了.");
    }
}

このコードを実行すると、次のような NoSuchMethodError が発生し、アプリケーションがクラッシュします。

# アプリケーション実行時のエラーログ
Exception in thread "main" java.lang.NoSuchMethodError: 'void com.example.CommonLib.doSomethingAdvanced()'
    at com.example.LibraryB_Processor.process(LibraryB_Processor.java:7)
    at com.yourcompany.yourapp.Main.main(Main.java:8)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77)
    at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.base/java.lang.reflect.Method.invoke(Method.java:568)
    at org.codehaus.mojo.exec.ExecJavaMojo$1.run(ExecJavaMojo.java:254)
    at java.base/java.lang.Thread.run(Thread.java:840)

これが、ビルドは成功するのに、実行するとクラッシュする典型的な「依存関係地獄」の症状です。

原因は、実行時にクラスパスにあるライブラリのバージョンが、開発時に想定されていたバージョンと異なっていることにあるのです。

それでは、この原因を特定するための、解決策を解説していきます。

2. 依存関係の可視化と問題の特定 (./mvnw dependency:tree)

問題解決の第一歩は、現状把握です。

./mvnw dependency:tree コマンドは、依存関係の全体像を可視化し、競合の根本原因を特定するための最も強力なツールです。

# プロジェクト全体の依存関係ツリーを表示
./mvnw dependency:tree

2.1. 便利なオプション

実際のプロジェクトでは出力が膨大になるため、以下のオプションを使いこなしましょう。

詳細表示 (-Dverbose):

競合によって除外された（omitted）依存関係も表示してくれます。バージョン競合の調査には必須です。

./mvnw dependency:tree -Dverbose

出力例：

[INFO] com.mycompany.app:my-app:jar:1.0-SNAPSHOT
[INFO] +- com.example:library-a:jar:1.0:compile
[INFO] |  \- (com.google.guava:guava:jar:30.1-jre:compile)
[INFO] \- com.example:library-b:jar:2.0:compile
[INFO]    \- (com.google.guava:guava:jar:28.2-jre:compile - omitted for conflict with 30.1-jre)

この omitted for conflict with 30.1-jre こそが、問題解決の最大のヒントとなります。

library-b が使おうとしていた guava の 28.2-jre は、よりプロジェクトに近い（あるいはpom.xmlで先に定義されている）library-a が依存する 30.1-jre との競合の結果、除外されたことがわかります。

特定ライブラリの追跡 (-Dincludes):

特定のライブラリが、どの直接依存ライブラリを通じてプロジェクトに取り込まれているのかを追跡したい場合に非常に便利です。

# guavaがどこから来たか調べる
./mvnw dependency:tree -Dincludes=com.google.guava:guava

出力例：

[INFO] com.mycompany.app:my-app:jar:1.0-SNAPSHOT
[INFO] \- com.example:library-a:jar:1.0:compile
[INFO]    \- com.google.guava:guava:jar:30.1-jre:compile

この出力から、guava ライブラリが my-app プロジェクトに library-a バージョン 1.0 を通じて 30.1-jre のバージョンで取り込まれていることが分かります。

このように、guava を含んでいる依存関係のパスだけがフィルタリングして表示されるため、巨大な依存関係ツリーの中から目的のライブラリを探し出す手間が大幅に省けます。

ファイルへの出力:

複雑なツリーをじっくり分析するために、結果をファイルに保存しましょう。

./mvnw dependency:tree -Dverbose > dependency-tree.txt

3. 明示的な依存関係の制御: <exclusions>

dependency:tree で問題のある推移的依存関係を特定したら、<exclusions> タグを使ってそれを明示的に除外できます。

<dependency>
    <groupId>com.example</groupId>
    <artifactId>library-a</artifactId>
    <version>1.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.example</groupId>
            <artifactId>common-lib</artifactId>
        </exclusion>
    </exclusions>
</dependency>

これにより、library-a 自体はプロジェクトの依存関係に残しつつも、library-a が推移的に持ち込むはずだった common-lib をクラスパスから明示的に除外し、バージョン競合の発生を回避します。

具体的に、これは以下のように問題解決します。

  1. 古いバージョンの排除:
    • 元々、あなたのMyProjectのクラスパスには、Library-Aが持ち込む古いCommon-Lib v1.0が採用されてしまい、これによってNoSuchMethodErrorが発生していました。
    • <exclusions>を使うことで、このv1.0がクラスパスから完全に排除されます。
  2. 正しいバージョンの採用:
    • Common-Lib v1.0が排除されることで、Library-Bが推移的に持ち込むCommon-Lib v2.0が唯一のCommon-Libのバージョンとしてクラスパスに残ります。
  3. NoSuchMethodErrorの解消:
    • Common-Lib v2.0にはdoSomethingAdvanced()メソッドがきちんと存在するため、Library-Bがこのメソッドを呼び出しても、実行時エラーは発生しなくなります。

このように、<exclusions>は、意図しないバージョンのライブラリがクラスパスに混入することを防ぎ、NoSuchMethodErrorのような実行時エラーの根本原因を解決する強力な手段となります。

<exclusions>適用前後の dependency:tree 比較

<exclusions> タグの効果は、dependency:tree の出力で確認できます。適用前と後でどのように変化するかを見てみましょう。

状況: library-a が common-lib:1.0 を、library-b が common-lib:2.0 を持ち込み、Mavenが（pom.xmlの宣言順により）1.0 を採用してしまっている。

<exclusions> 適用前

dependency:tree -Dverbose を実行すると、競合によって common-lib:2.0 が除外されていることが分かります。

[INFO] com.mycompany.app:my-app:jar:1.0-SNAPSHOT
[INFO] +- com.example:library-a:jar:1.0:compile
[INFO] |  \- com.example:common-lib:jar:1.0:compile
[INFO] \- com.example:library-b:jar:2.0:compile
[INFO]    \- (com.example:common-lib:jar:2.0:compile - omitted for conflict with 1.0)

<exclusions> 適用後

library-a の pom.xml 定義に <exclusions> を追加した後、再び dependency:tree を実行します。

[INFO] com.mycompany.app:my-app:jar:1.0-SNAPSHOT
[INFO] +- com.example:library-a:jar:1.0:compile
[INFO] |  \- (com.example:common-lib:jar:1.0:compile - excluded) <-- ここに注目！
[INFO] \- com.example:library-b:jar:2.0:compile
[INFO]    \- com.example:common-lib:jar:2.0:compile <-- v2.0が採用された！

library-a からの common-lib:1.0 が excluded となり、競合相手がいなくなったことで library-b が依存する common-lib:2.0 が無事にクラスパスへと採用されました。

このように、dependency:tree を使うことで、<exclusions> の効果を確実に検証できます。

解決後の依存関係図

この変更により、依存関係は以下のように整理されます。

解決後の依存関係図

ITアーキテクトの視点：<exclusions> はいつ使うべきか？

<exclusions> は強力ですが、乱用は禁物です。以下のような、やむを得ない状況での利用を推奨します。

  1. ライブラリ間の深刻な非互換性: Library-A が Common-Lib v1.0 を、Library-B が Common-Lib v2.0 を持ち込み、両バージョンに互換性がなく、どちらか一方に統一する必要がある場合。
  2. セキュリティ脆弱性の緊急回避: 推移的依存関係のライブラリに緊急の脆弱性が発見されたが、直接の依存先ライブラリの修正版がまだリリースされていない場合。脆弱性のあるライブラリを一時的に除外し、安全なバージョンを直接依存に追加します。

4. プロジェクト全体のバージョン管理: <dependencyManagement>

最も推奨される、プロアクティブな依存関係管理手法が <dependencyManagement> です。

これは、プロジェクト全体で利用する依存関係のバージョンを一元的に宣言し、そのバージョンを「支配」するための強力な仕組みです。この「支配」とは、プロジェクトのどこかでその依存関係が登場した際に、ここで宣言されたバージョンが強制的に適用されることを意味します。

それでは、その具体的な動作とメリットを見ていきましょう。

4.1. <dependencyManagement> の基本的な役割

<dependencyManagement> セクション内に記述された依存関係は、それだけでは直接プロジェクトにライブラリが追加されることはありません。

ここはあくまで、特定のライブラリに対して「このプロジェクトではこのバージョンを使う！」というバージョンの規定（ひな形）を定義する場所だと考えてください。

この仕組みを、我々のシナリオで考えてみましょう。MyProject で Common-Lib のバージョン競合を解決するために、<dependencyManagement> で Common-Lib のバージョンを v2.0 に明示的に固定する例です。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>common-lib</artifactId>
            <version>2.0</version> <!-- Common-Libのバージョンをここで2.0に固定 -->
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>library-a</artifactId>
        <version>1.0</version>
        <!-- Common-Lib v1.0への推移的依存は、dependencyManagementで上書きされるため、ここでは除外しない -->
    </dependency>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>library-b</artifactId>
        <version>2.0</version>
        <!-- Common-Lib v2.0への推移的依存は、dependencyManagementで定義されたバージョンと一致 -->
    </dependency>
</dependencies>

この設定により、Library-A が Common-Lib v1.0 を、Library-B が Common-Lib v2.0 をそれぞれ推移的に持ち込もうとしても、MyProject 内では <dependencyManagement> で宣言された Common-Lib v2.0 が強制的に適用されます。これにより、ビルド時・実行時の両方で Common-Lib v2.0 が使用されることが保証され、NoSuchMethodError の問題を根本的に解決することができます。

4.2. バージョンの「強制適用」メカニズム

<dependencyManagement> でバージョンが定義されているライブラリを、実際の依存関係としてプロジェクトに追加する際は、<dependencies> セクションでバージョン番号を省略して記述することができます。

我々の MyProject のシナリオでは、<dependencyManagement> で Common-Lib のバージョンが 2.0 に固定されています。この状況で、MyProject の <dependencies> セクションは以下のようになります。

<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>library-a</artifactId>
        <version>1.0</version>
    </dependency>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>library-b</artifactId>
        <version>2.0</version>
    </dependency>
    <!-- MyProjectでCommon-Libを直接利用する場合、バージョン指定を省略できる -->
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>common-lib</artifactId>
        <!-- ここでバージョンを省略すると、dependencyManagementで定義された2.0が強制適用される -->
    </dependency>
</dependencies>

このとき、たとえ Library-A が Common-Lib v1.0 を推移的に持ち込もうとしても、<dependencyManagement> で Common-Lib は v2.0 であると宣言されているため、MyProject の最終的なクラスパスには常に Common-Lib v2.0 が採用されます。これは、Mavenの「最近傍優先」ルールよりも、<dependencyManagement> での明示的な定義が優先されるためです。

このメカニズムにより、MyProject は常に意図したバージョンの Common-Lib (v2.0) を使用することが保証され、開発者はバージョン競合に悩まされることなく、安定した開発を進めることができます。

4.3. なぜ <dependencyManagement> を使うべきか？

  1. バージョンの一貫性:
    • 複数のモジュールや推移的依存関係を通じて同じライブラリが異なるバージョンで登場する「バージョン競合」を未然に防ぎ、プロジェクト全体で常に同じバージョンを使用することを保証します。
  2. 依存関係管理の簡素化:
    • 実際に依存関係を宣言する<dependencies>セクションではバージョン指定が不要になるため、pom.xmlが簡潔になり、管理が容易になります。
  3. 信頼性の向上:
    • 特に大規模プロジェクトや複数のサブモジュールを持つプロジェクトでは、各所で異なるバージョンが使われることによる予期せぬ実行時エラー（NoSuchMethodErrorなど）のリスクを大幅に低減します。
  4. プロアクティブな問題回避:
    • 依存関係の問題が発生してから対処するのではなく、あらかじめ使用するバージョンを「支配」することで、問題を未然に防ぐことができます。

このように、<dependencyManagement>はプロジェクトの依存関係を健全に保ち、安定したビルドを実現するための要となる機能です。

4.4 応用: BOM (Bill of Materials) のインポート

この <dependencyManagement> の仕組みを最大限に活用するのが BOM (Bill of Materials) です。

BOMとは、「特定のプロダクト（例: Spring Boot）を構成する、互換性がテストされたライブラリのバージョンリスト」 が定義された、特別なPOMファイルです。

これを scope=import を使って <dependencyManagement> に取り込むことで、その膨大なバージョン定義を自分のプロジェクトに一括で適用できます。

いわば、ライブラリのバージョン選定という複雑な作業を、Springのようなフレームワークの専門チームに「おまかせ」できる仕組みです。

例: Spring Boot 3.5.9 BOM のインポート

2025年現在、Spring Boot 3.5.xはJava 17をベースとしており、その依存関係管理はこれまで以上に洗練されています。

<dependencyManagement>
    <dependencies>
        <!-- Spring Boot 3.5.9 が提供するBOMをインポート -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.5.9</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- BOMをインポートしたので、バージョン指定は不要！ -->
    <!-- Spring Bootチームがテストした最適なバージョンが自動で使われる -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- jackson-databindもバージョン指定不要 -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

このBOMの恩恵は、我々の MyProject のようなアプリケーションでも享受できます。

例えば MyProject が spring-boot-starter-web に依存しているとします。spring-boot-starter-web は内部的に jackson-databind など多くのライブラリに推移的に依存しています。

MyProjectが以下のように spring-boot-starter-web に依存する場合：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- MyProjectが直接的にjackson-databindを必要とする場合でも、バージョン指定は不要 -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

<dependencyManagement> で spring-boot-dependencies BOM をインポートしておけば、上記のように spring-boot-starter-web や jackson-databind のバージョンを個別に指定する必要はありません。Spring Bootチームがテスト済みの互換性のあるバージョンが自動的に適用されるため、Common-Lib の例で経験したようなバージョン競合の問題を、Spring関連ライブラリ全体で未然に防ぐことができます。

これは、Common-Lib のバージョン管理を <dependencyManagement> で行うのと同様に、より広範なライブラリ群に対して、一貫性のあるバージョンを保証する強力な手法となります。

BOMによるバージョン管理の確認

spring-boot-starter-web は内部で jackson-databind に依存していますが、BOMをインポートしておけば、自分でバージョンを気にする必要はありません。dependency:tree で確認してみましょう。

[INFO] com.mycompany.app:my-app:jar:1.0-SNAPSHOT
[INFO] +- org.springframework.boot:spring-boot-starter-web:jar:3.5.9:compile
[INFO] |  +- org.springframework.boot:spring-boot-starter-json:jar:4.0.1:compile
[INFO] |  |  \- com.fasterxml.jackson.core:jackson-databind:jar:2.17.1:compile
...

jackson-databind に 2.17.1 という具体的なバージョンが、spring-boot-dependencies:3.5.9 BOM に基づいて自動的に設定されていることがわかります。これにより、開発者は互換性を気にすることなく、必要なライブラリを追加するだけで済むのです。

なぜBOMが重要か？

spring-boot-starter-parent を <parent> に指定できないプロジェクト（例: 会社独自の親POMを継承する必要がある場合）でも、BOMをインポートすれば、Spring Bootの優れた依存関係管理の恩恵を享受できます。これは、より柔軟で堅牢なプロジェクト構成を可能にする、非常に強力なテクニックです。

独自のBOMを作成する

Spring Bootのような大規模フレームワークだけでなく、独自のBOMを作成して、社内ライブラリや特定のプロジェクト群で利用するライブラリのバージョンを一元管理することも可能です。

これは、複数のマイクロサービスやモジュールを持つ大規模なプロジェクトにおいて、特定の依存関係セットのバージョン統一を強制するのに非常に役立ちます。

例えば、MyProject が常に Common-Lib v2.0 と Library-A v1.0 を互換性のあるバージョンとして利用したい場合を考えます。

このために、my-project-bom というMavenモジュールを別途作成し、その pom.xml でこれらのバージョンを定義します。

my-project-bom/pom.xml の例:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.yourcompany</groupId>
    <artifactId>my-project-bom</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging> <!-- BOMであることを示す -->

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.example</groupId>
                <artifactId>common-lib</artifactId>
                <version>2.0</version>
            </dependency>
            <dependency>
                <groupId>com.example</groupId>
                <artifactId>library-a</artifactId>
                <version>1.0</version>
            </dependency>
            <!-- MyProjectで利用する他のライブラリのバージョンをここで定義 -->
        </dependencies>
    </dependencyManagement>
</project>

次に、MyProject 本体では、この my-project-bom を <dependencyManagement> セクションでインポートします。

MyProject/pom.xml (BOMインポート後) の例：

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.yourcompany</groupId>
    <artifactId>my-project</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <dependencyManagement>
        <dependencies>
            <!-- 独自のBOMをインポート -->
            <dependency>
                <groupId>com.yourcompany</groupId>
                <artifactId>my-project-bom</artifactId>
                <version>1.0.0-SNAPSHOT</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>library-a</artifactId>
            <!-- バージョン指定はmy-project-bomから継承される -->
        </dependency>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>library-b</artifactId>
            <version>2.0</version> <!-- BOMに含まれない依存は引き続きバージョン指定が必要 -->
        </dependency>
        <!-- common-libを直接利用する場合もバージョン指定は不要 -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>common-lib</artifactId>
        </dependency>
    </dependencies>
</project>

このように独自のBOMを導入することで、MyProject 内の複数のモジュールや、関連する別のプロジェクトが、common-lib や library-a のバージョンを個別に管理することなく、my-project-bom で定義された一貫性のあるバージョンを強制適用できるようになります。

これにより、大規模なプロジェクトでの依存関係管理がよりシンプルかつ堅牢になります。

5. 適切なスコープ設定による最適化

依存関係の「スコープ」を正しく設定することは、不要なライブラリの混入を防ぎ、ビルドを最適化するための基本かつ重要なテクニックです。

スコープは、依存関係がどのビルドフェーズ（コンパイル、テスト、実行）で有効であるか、そして最終的な成果物（JAR/WARファイル）に含まれるべきかを定義します。

主要なスコープの役割を以下の表にまとめました。

スコープ説明推移的依存成果物に含まれるか主な利用例
compile(デフォルト) すべてのクラスパスで利用可能。コンパイル、テスト、実行の全てで必要。はいはいspring-context, guava など、常に必要なライブラリ
providedコンパイルとテストでは必要だが、実行環境（例: サーブレットコンテナ）が提供するため、成果物には含めない。いいえいいえjakarta.servlet-api, lombok
runtime実行時とテストでのみ必要。コンパイル時には不要。はいはいJDBCドライバ (mysql-connector-java)
testテストのコンパイルと実行でのみ必要。本番のクラスパスには一切影響しない。いいえいいえjunit, mockito, assertj
import<dependencyManagement> セクションでのみ使用。BOM (Bill of Materials) をインポートするために使う。––spring-boot-dependencies

常に意識すべき最重要ルール:
テストにしか使わないライブラリ（JUnit, Mockito, AssertJなど）には、必ず <scope>test</scope> を設定してください。

これを怠ると、テスト用のライブラリが本番環境の成果物に紛れ込み、以下のような問題を引き起こす可能性があります。

  • 不要なファイル肥大化: アプリケーションのサイズが不必要に大きくなる。
  • 予期せぬ競合: 本番環境のライブラリとテスト用ライブラリが競合を起こす。
  • セキュリティリスク: テスト用ライブラリに含まれる脆弱性が、本番環境に持ち込まれてしまう。
<!-- 良い例: scopeを必ず指定する -->
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.32</version>
    <scope>provided</scope> <!-- コンパイル時にのみ必要 -->
</dependency>

特に provided と test スコープは、推移的依存を伝播させない性質を持つため、意図しないライブラリがクラスパスに紛れ込むのを防ぐ上で非常に効果的です。

6. ビルドプロセスでの規律強制: maven-enforcer-plugin

これまでの解決策は問題が発生した後の対処や、規律ある手動管理に焦点を当てていました。

さらに一歩進んで、ビルドの仕組みそのものに「規律」を強制するのが maven-enforcer-plugin です。

このプラグインは、定義されたルールに違反する依存関係がプロジェクトに含まれることを検知し、ビルドを失敗させてくれます。

ルール1: requireUpperBoundDeps – 常に新しいバージョンを要求

推移的依存関係でバージョンが競合した際に、Mavenは「最近傍優先」でバージョンを決定しますが、これが常に最新バージョンであるとは限りません。

requireUpperBoundDeps は、依存関係ツリー上で要求されている最も高い（新しい）バージョンが常に使われることを強制します。

これにより、古いAPIを持つライブラリが意図せず使われて NoSuchMethodError が発生する、といった事故を未然に防ぎます。

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-enforcer-plugin</artifactId>
            <version>3.4.1</version> <!-- 2025年時点での安定版を確認して設定 -->
            <executions>
                <execution>
                    <id>enforce-versions</id>
                    <goals>
                        <goal>enforce</goal>
                    </goals>
                    <configuration>
                        <rules>
                            <requireUpperBoundDeps/>
                        </rules>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

もし下位バージョンの依存関係が解決されようとすると、ビルドは以下のような明確なエラーメッセージと共に失敗します。

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-enforcer-plugin:3.4.1:enforce (enforce-versions) on project my-app: 
[ERROR] Rule 0: org.apache.maven.enforcer.rules.RequireUpperBoundDeps failed with message:
[ERROR] Failed while enforcing RequireUpperBoundDeps. The error(s) are [
[ERROR] Require upper bound dependencies error for com.google.guava:guava:jar:28.2-jre paths to dependency are:
[ERROR] +-com.mycompany.app:my-app:1.0-SNAPSHOT
[ERROR]   \-com.example:library-b:2.0
[ERROR]     \-com.google.guava:guava:28.2-jre
[ERROR] and
[ERROR] +-com.mycompany.app:my-app:1.0-SNAPSHOT
[ERROR]   \-com.example:library-a:1.0
[ERROR]     \-com.google.guava:guava:30.1-jre

ルール2: bannedDependencies – 特定ライブラリの使用禁止

セキュリティ脆弱性が発見されたライブラリや、社内ルールで使うべきでないとされているライブラリを、プロジェクトから完全に排除するためのルールです。

例えば、過去に深刻な脆弱性が問題となった log4j の古いバージョンが、何かの推移的依存によって紛れ込んでしまうのを防ぎたいとします。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <version>3.4.1</version>
    <executions>
        <execution>
            <id>enforce-banned-dependencies</id>
            <goals>
                <goal>enforce</goal>
            </goals>
            <configuration>
                <rules>
                    <requireUpperBoundDeps/>
                    <bannedDependencies>
                        <excludes>
                            <!-- log4j 1.x系の使用を全面的に禁止 -->
                            <exclude>log4j:log4j:[1.0, 2.0)</exclude>
                            <!-- commons-loggingの使用も禁止 (jcl-over-slf4jへの移行を促す) -->
                            <exclude>commons-logging:commons-logging</exclude>
                        </excludes>
                        <message>
                        プロジェクトで禁止されているライブラリが検出されました。
                        - log4j 1.x は使用できません。Log4j2 または Logback を使用してください。
                        - commons-logging は使用できません。SLF4Jブリッジ (jcl-over-slf4j) を使用してください。
                        </message>
                    </bannedDependencies>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

この設定により、誰かが誤って古いライブラリに依存するモジュールを追加しても、ビルドが即座に失敗するため、問題がリポジトリにマージされるのを防ぐことができます。これは、プロジェクトの健全性とセキュリティを維持するための非常に強力な門番となります。

まとめ：依存関係を支配し、安定したビルドを

この記事では、Mavenの「依存関係地獄」の発生メカニズムをMyProjectでの具体的な NoSuchMethodError のシナリオを通じて詳細に解説し、そこから脱却してプロジェクトをクリーンに保つための以下の実践的なアプローチを深掘りしました。

  1. 依存関係の可視化と問題の特定 (./mvnw dependency:tree):
    • -Dverbose や -Dincludes を駆使し、コンパイル時と実行時それぞれの状況をMermaid図で視覚化しながら、問題の根本原因を正確に特定する方法を学びました。
  2. 明示的な依存関係の制御 (<exclusions>):
    • やむを得ない場合に、問題のある推移的依存をピンポイントで排除する具体的な方法と、その効果をdependency:treeの出力比較で確認しました。
  3. プロジェクト全体のバージョン管理 (<dependencyManagement> と BOM):
    • プロジェクトで使うライブラリのバージョンを宣言的に、一元的に管理する強力な仕組みを、MyProjectの例を交えながら解説しました。
    • さらに、Spring Boot BOMのインポートだけでなく、独自のBOMを作成して社内ライブラリのバージョンを管理する応用例についても考察しました。
  4. 適切なスコープ設定による最適化:
    • 不要なライブラリの混入を防ぎ、ビルドを最適化するための基本かつ重要なテクニックであるスコープの正しい使い方を確認しました。
  5. ビルドプロセスでの規律強制 (maven-enforcer-plugin):
    • ビルドプロセスにルールを組み込み、問題のある依存関係の混入を自動的に阻止することで、より堅牢な開発環境を構築する方法を解説しました。

これらのテクニックは、依存関係の問題に場当たり的に対処するのではなく、構造的に理解し、プロアクティブに管理するために有効です。

MyProjectの具体例とMermaid図による視覚化は、複雑な依存関係の挙動を明確に理解する一助となるでしょう。

本記事で紹介した管理術をプロジェクトに適用することで、将来的な「なぜか動かない」といった問題を防ぎ、クリーンで安定したビルド環境の維持に貢献します。

参考資料

免責事項

本記事の内容は、執筆時点での情報に基づいています。技術仕様やプラクティスは将来的に変更される可能性があるため、常に最新の公式ドキュメントや信頼できる情報源を参照し、各自の責任においてご活用ください。本記事の情報を利用したことで生じたいかなる損害についても、当ブログおよび著者は一切の責任を負いません。

Post Views: 3

SNSでもご購読できます。

コメントを残す

*