Mavenでバージョン地獄を避ける設計の考え方 - Web開発における知見共有系ページ

Mavenで起きがちな「バージョン地獄」とは何か
Mavenの依存解決ルールを最低限理解する
バージョン地獄を招く設計パターン
バージョン地獄を避けるための基本設計
実際にやるとこうなる：設計後の変化
注意点とリスク
それでもMavenで設計する価値はあるのか
まとめ：バージョンを管理するのは、結局「人」

Mavenでバージョン地獄を避けるために一番大切なのは、「個々の依存関係をどう指定するか」よりも、「バージョンをどこに集約し、誰が決め、どう変更されるか」を設計として先に決めておくことです。依存関係の衝突や意図しないアップデートは、ツールの癖というよりも、設計の曖昧さから生まれることがほとんどです。

この記事では、Mavenを長く使っている現場でよく見る失敗パターンと、それを避けるための設計の考え方を、具体例を交えて整理します。単なる設定テクニックではなく、「なぜそうするのか」を中心に書いていきます。

Mavenで起きがちな「バージョン地獄」とは何か

Mavenを使っていると、次のような状況に心当たりが出てくることがあります。

依存関係を1つ追加しただけなのに、別のライブラリの挙動が変わる
ローカルでは動くが、CIではテストが落ちる
チームメンバーによってビルド結果が微妙に違う
バージョンアップが怖くて、何年も古い依存関係を使い続けている

これらは総称して「バージョン地獄」と呼ばれることが多いですが、正体はそれほど神秘的なものではありません。Mavenの依存解決ルールと、人間側の設計判断が噛み合っていないだけ、というケースが大半です。

特に問題になりやすいのは、「どのバージョンが最終的に使われているのかが、ぱっと見で分からない」状態です。Mavenは賢く自動解決してくれますが、その結果を人間が把握できなくなった瞬間に、トラブルの芽が育ち始めます。

Mavenの依存解決ルールを最低限理解する

設計の話に入る前に、Mavenの依存解決の前提を軽く整理しておきます。細かい仕様を全部覚える必要はありませんが、次の点は知っておかないと設計判断を誤りやすくなります。

依存関係は「近いもの」が優先される

Mavenでは、依存関係のツリー上でより近い位置にある依存が優先されます。いわゆる「nearest wins」のルールです。同じライブラリが複数の経路から引き込まれた場合、ルートからの距離が短いものが使われます。

これは一見シンプルですが、裏を返すと「pom.xmlの書き方次第で結果が変わる」ということでもあります。

transitive dependencyは自動で入ってくる

Mavenでは、依存関係がさらに依存しているライブラリ（transitive dependency）も自動で解決されます。便利ではありますが、何も考えずに使うと、知らないうちに大量のライブラリとバージョンを抱え込むことになります。

バージョンを省略すると上位定義に従う

dependencyManagementでバージョンを定義している場合、個々のdependencyではバージョンを省略できます。この仕組み自体は非常に強力ですが、使い方を誤ると「どこで決まっているのか分からない」状態を作りがちです。

バージョン地獄を招く設計パターン

ここからは、実際によく見る「やってしまいがちな設計」を整理します。どれも珍しい話ではありません。

各dependencyに直接バージョンを書く

一番ありがちなパターンです。

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-context</artifactId>
  <version>5.3.30</version>
</dependency>

一見すると分かりやすいのですが、依存関係が増えるほど、バージョン管理が分散します。同じライブラリ群なのに微妙にバージョンがズレている、という状況が簡単に生まれます。

後からまとめようとしても、「どれを基準にすればいいのか」が分からなくなりがちです。

親POMをなんとなく継承している

spring-boot-starter-parentなど、有名な親POMをそのまま継承するケースは多いです。これは決して悪いことではありませんが、「中で何が定義されているかを把握していない」まま使うと危険です。

親POMが管理しているバージョンと、自分たちが明示的に指定しているバージョンが衝突し、意図しない結果になることがあります。

exclusionを場当たり的に追加する

依存関係の衝突が起きたときに、次のようなexclusionでとりあえず解決することがあります。

<exclusions>
  <exclusion>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
  </exclusion>
</exclusions>

これ自体は正しい手段ですが、理由や背景を整理せずに積み重ねると、「なぜ除外しているのか誰も分からない」状態になります。後から別のライブラリを入れた途端に再発することも珍しくありません。

バージョン地獄を避けるための基本設計

ここからが本題です。Mavenでバージョン地獄を避けるための設計は、突き詰めると次の考え方に集約されます。

バージョンはできるだけ一箇所に集める
依存関係の意図を明示する
Mavenの自動解決に「任せすぎない」

順番に見ていきます。

dependencyManagementを「バージョンの台帳」として使う

dependencyManagementは、「使うライブラリとそのバージョンの一覧表」と割り切って使うのがコツです。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-context</artifactId>
      <version>5.3.30</version>
    </dependency>
  </dependencies>
</dependencyManagement>

実際に使うかどうかは別として、「このプロジェクトではこのバージョンを標準とする」という宣言の場として使います。こうしておくことで、dependency側ではバージョンを書かずに済みます。

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-context</artifactId>
</dependency>

結果として、「どのバージョンを使っているのか」を一目で追えるようになります。

親POMを使うなら役割を限定する

マルチモジュール構成や複数プロジェクトで共通化したい場合は、親POMを用意するのが有効です。ただし、親POMは「何でもかんでも入れる場所」ではありません。

おすすめなのは、次のような役割分担です。

親POM：バージョン管理、プラグインの基本設定
子POM：そのモジュール固有の依存関係

親POMにアプリケーション固有の依存関係まで入れ始めると、後で再利用しづらくなります。

BOMを理解した上で使う

BOM（Bill of Materials）は、dependencyManagementをまとめたものです。SpringやAWS SDKなど、大規模なライブラリ群ではBOMが提供されています。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.2.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

BOMを使うことで、ライブラリ間の整合性を自分で考えなくて済むというメリットがあります。一方で、「BOMが決めた世界」に乗っかることになるため、独自にバージョンを上げ下げする場合は注意が必要です。

実際にやるとこうなる：設計後の変化

設計を見直したプロジェクトでは、次のような変化がよく見られます。

pom.xmlを見れば、採用している技術スタックが分かる
依存関係の追加・削除が怖くなくなる
バージョンアップ時の影響範囲を見積もりやすくなる
チーム内で「なぜこのバージョンなのか」を説明できる

特に大きいのは、「問題が起きたときに原因を追いやすくなる」点です。完全にトラブルがなくなるわけではありませんが、少なくとも闇雲に悩む時間は減ります。

注意点とリスク

ここまで読んで、「こうすれば絶対安心」と思われるかもしれませんが、注意点もあります。

dependencyManagementに集約しすぎると、pom.xmlが肥大化する
BOMの更新に追従しないと、逆に古い依存を抱え続ける
Mavenの仕様変更やプラグイン更新の影響はゼロにはならない

特に、設計を整えたことで「分かった気になる」ことが一番のリスクです。mvn dependency:treeなどで、実際にどう解決されているかを定期的に確認する習慣は欠かせません。

それでもMavenで設計する価値はあるのか

Gradleや他のビルドツールが注目される中で、「Mavenは古い」と言われることもあります。ただ、Mavenは依存関係管理の考え方が非常に明文化されたツールでもあります。

バージョン地獄を避ける設計を通して見えてくるのは、「ツールが何を自動化し、何を人間に委ねているか」です。そこを理解できれば、Mavenに限らず、どのツールを使っても同じ失敗を繰り返しにくくなります。

まとめ：バージョンを管理するのは、結局「人」

結局のところ、Mavenでバージョン地獄を避ける設計とは、「バージョン管理の責任を曖昧にしないこと」です。ツールに任せきりにせず、人が決め、人が把握できる形に整える。そのための仕組みがdependencyManagementであり、親POMであり、BOMです。

設定を増やすことが目的ではありません。将来の自分やチームメンバーが、pom.xmlを見たときに安心できるかどうか。その視点で設計を見直すことが、結果的に一番の近道になるはずです。