Gradleの依存関係管理を徹底解説！バージョン確認・変更からカタログ活用まで

Gradleの依存関係とは？基本の仕組みとConfigurationの種類

Gradleの依存関係管理は、Javaプロジェクトで必要になる外部ライブラリの取得と管理を自動化する仕組みです。依存関係とは、プロジェクトが利用する外部ライブラリやモジュールのことを指し、Gradleはこれらをリポジトリから自動的にダウンロードして解決します。依存関係は「設定（Configuration）」と呼ばれる用途別のカテゴリに宣言することが基本です。

Gradleがサポートする依存関係には、モジュール依存関係、プロジェクト依存関係、ファイル依存関係の3種類があります。最も一般的なのはMaven Centralなどの外部リポジトリから取得するモジュール依存関係で、依存関係はデフォルトで推移的に解決されます。つまり、あるライブラリが内部的に依存している別のライブラリも自動的に取得されます。（出典：Gradle公式「Declaring Dependencies」）

設定（Configuration）は、依存関係を「いつ・どこで使うか」を定義するグループです。Javaプロジェクトでは、コンパイル用、テスト用、ランタイム用など、ビルドの各段階に応じた設定が用意されています。これにより、本番コードには不要な依存関係をテスト時にだけ含めるといった細かい制御が可能になります。

Java Libraryプラグインが提供する主要な設定

GradleのJava開発では、Java Libraryプラグインが主要な設定を提供します。設定の選択はビルドの速度と成果物の構成に直接影響するため、用途を正確に理解することが重要です。

各設定の使い分けで迷った場合は、まずimplementationを選ぶのが基本です。apiはライブラリを公開する場合のみ使用し、多用すると再コンパイル範囲が広がりビルドが遅くなります。（出典：Gradle公式「Dependency Configurations」）

推奨される依存関係の表記方法

依存関係の宣言は、「group:name:version」形式の文字列表記が公式推奨です。Gradle 9.1.0以降、マップ形式（group: '..', name: '..', version: '..'）は非推奨となり、Gradle 10ではビルドエラーになる予定です。

• 文字列表記（推奨）：implementation 'com.google.guava:guava:32.1.2-jre'
• マップ表記（非推奨）：implementation group: 'com.google.guava', name: 'guava', version: '32.1.2-jre'

文字列表記は簡潔で読みやすく、ビルドスクリプトの可読性を高めます。新規プロジェクトでは必ず文字列表記を採用してください。既存プロジェクトでマップ表記を使用している場合は、Gradle 10への移行を見据えて早めに書き換えることをお勧めします。（出典：Gradle公式「Declaring and Managing Dependencies」）

リポジトリの指定と注意点

Gradleはデフォルトではリポジトリを定義していないため、外部依存関係を使う場合はrepositories {}ブロックで取得先を明示する必要があります。最も一般的なのはMaven Central（mavenCentral()）で、Java向けOSSの主要リポジトリです。

リポジトリは宣言された順にチェックされ、最初に見つかったモジュールから取得されます。また、依存関係は宣言されたリポジトリからのみ取得され、Maven POM内で参照されている追加リポジトリはGradleでは無視されます。これは再現性とセキュリティ保護のためです。

要点：依存関係は設定（Configuration）に分類して宣言し、通常はimplementationを使用する。文字列表記が推奨され、リポジトリはMaven Centralを明示的に指定する。

依存関係を宣言する方法：implementationとapiの使い分け

implementationとapiの使い分けは、Gradle依存関係管理の最重要ポイントです。この2つの設定はどちらもコンパイルとランタイムの両方で依存関係を利用可能にしますが、他のモジュールへの公開範囲が大きく異なります。使い分けを誤ると、ビルド速度の低下や不必要な依存関係の露出につながります。

implementationは依存関係を自分のモジュール内に閉じ込める設定です。他のモジュールから参照されるAPIに依存ライブラリの型が現れない場合、implementationを使うことで、そのライブラリの変更による再コンパイル範囲を自モジュール内に限定できます。通常のアプリケーションや内部モジュールでは、implementationが推奨されます。

一方、apiは依存関係を推移的に他のモジュールへ公開する設定です。公開APIのシグネチャにライブラリの型が含まれる場合に使用します。ただしapiを多用すると、依存関係の変更がプロジェクト全体に波及し、ビルド時間が増大する原因になります。（出典：Android Developers「Add build dependencies」）

implementationがビルド時間を短縮する仕組み

implementationを使用すると、依存関係のAPI変更時に再コンパイルされるモジュールが減少します。Gradleは各モジュールの公開APIと内部実装を区別し、公開APIが変更されない限り依存元モジュールの再コンパイルをスキップできるためです。

例えば、モジュールAが内部でGuavaを使用し、モジュールBがAに依存している場合を考えます。AがGuavaをimplementationで宣言していれば、GuavaのバージョンアップやAの内部実装変更はBの再コンパイルを引き起こしません。これにより、大規模なマルチモジュールプロジェクトほどimplementationのメリットが大きくなります。

逆にapiで宣言した場合、Guavaの変更はAの公開APIの一部とみなされ、Bも再コンパイルが必要になります。ライブラリの公開APIに現れない依存関係は、すべてimplementationを使うのが基本方針です。

apiを使うべき具体的なケース

apiを使用するのは、公開APIに依存ライブラリの型が含まれる場合に限定されます。代表的なケースは以下の通りです。

• 公開メソッドの戻り値や引数に依存ライブラリの型を使用する
• 公開インターフェースや抽象クラスが依存ライブラリの型を継承・実装する
• 公開アノテーションが依存ライブラリに含まれる

Java Libraryプラグインは、apiで宣言された依存関係のみを消費者モジュールのコンパイルクラスパスに公開します。ライブラリ開発では、公開APIに現れる型を含む依存関係だけをapiにし、それ以外はimplementationを使うことで、消費者側のビルドを軽量化できます。

なお、apiはJava Libraryプラグインでのみ利用可能です。通常のJavaプラグインではimplementationと同等の扱いになるため、プラグインの選択も意識してください。（出典：Gradle公式「Dependency Configurations」）

compileOnlyとruntimeOnlyの活用シーン

implementationとapi以外にも、compileOnlyとruntimeOnlyを使い分けることで依存関係を最適化できます。compileOnlyはコンパイル時のみ必要でランタイムには含めない依存関係に使用し、runtimeOnlyはコンパイルには不要だが実行時に必要な依存関係に使用します。

compileOnlyの典型例はLombokのようなアノテーションプロセッサです。コンパイル時にコード生成を行いますが、生成後のバイトコードにはLombok自体は不要です。runtimeOnlyの典型例はJDBCドライバで、コードはJDBCの標準APIに対して記述し、実際のドライバ実装は実行時にのみ必要になります。

要点：implementationは依存関係を自モジュール内に閉じ込めてビルドを高速化する。apiは公開APIに依存ライブラリの型が現れる場合のみ使用する。

依存関係ツリーの確認方法：dependenciesとdependencyInsightコマンド

Gradleプロジェクトの依存関係管理で最も実用的なスキルが、依存関係ツリーの確認と問題の切り分けです。複数のライブラリを導入すると、推移的依存関係によって意図しないライブラリが含まれたり、バージョン衝突が発生したりします。Gradleが提供する2つのコマンドを使いこなせば、これらの問題を効率的に特定できます。

まず基本となるのが./gradlew dependenciesコマンドです。このコマンドはプロジェクトのすべての設定（Configuration）ごとに、宣言された依存関係と推移的に解決された依存関係をツリー形式で表示します。ツリーを見れば、どのライブラリがどのバージョンで、どの依存関係から引き込まれたのかを一目で把握できます。

より詳細な調査には./gradlew dependencyInsight --dependency ライブラリ名を使用します。このコマンドは特定の依存関係が「どの設定で」「どの経路で」「どのバージョンで」解決されたのか、さらにそのバージョンが選ばれた理由まで表示します。バージョン衝突の原因調査に非常に有効です。

dependenciesコマンドの実践的な使い方

dependenciesコマンドは、そのまま実行するとすべての設定の情報が表示されて膨大な出力になります。実務では特定の設定に絞って確認するのが効率的です。

1. 全設定の依存関係を確認：./gradlew dependencies
2. コンパイルクラスパスを確認：./gradlew dependencies --configuration compileClasspath
3. ランタイムクラスパスを確認：./gradlew dependencies --configuration runtimeClasspath
4. テスト用クラスパスを確認：./gradlew dependencies --configuration testRuntimeClasspath

出力では、直接宣言した依存関係と推移的依存関係がインデントで区別されます。「(*)」マークが付いているものは、すでに別の経路で解決済みのため重複表示を省略された依存関係です。矢印（→）はバージョン解決の結果、異なるバージョンが選択されたことを示します。

dependencyInsightコマンドで解決理由を調査する

dependencyInsightは、特定の依存関係がそのバージョンになった理由を逆引きで調査するコマンドです。バージョン衝突が発生したとき、どの依存関係が高いバージョンを要求しているのかを特定できます。

./gradlew dependencyInsight --dependency commons-lang3 --configuration runtimeClasspath

このコマンドの出力には、以下の情報が含まれます。

• 選択されたバージョンと、それを要求した依存関係の経路
• 選択されなかったバージョンと、それを要求した依存関係の経路
• バージョン選択の理由（衝突解決、制約、強制など）

「どのライブラリが特定のバージョンを要求しているか」を特定できるため、excludeやバージョン制約を追加する際の判断材料が得られます。問題の依存関係が複数の経路から引き込まれている場合、それぞれの経路が別々に表示されます。

依存関係ツリーでよくある問題パターン

依存関係ツリーを確認する際に遭遇しやすい問題パターンを理解しておくと、調査がスムーズになります。最も一般的なのはバージョン衝突による意図しないアップグレードです。

例えば、モジュールAがcommons-lang3:3.1を要求し、モジュールBがcommons-lang3:3.2を要求する場合、Gradleはデフォルトで最も高いバージョンである3.2を選択します。ツリー上では「3.1 -> 3.2」と表示され、dependencyInsightで調べると選択理由が確認できます。

その他、excludeが効いていない場合は、除外したい依存関係が複数の経路から引き込まれている可能性があります。excludeは特定の経路にしか適用されないため、ツリーで全経路を確認し、必要に応じて各経路でexcludeを宣言するか、グローバルな除外ルールを設定する必要があります。（出典：Gradle公式「Resolution Rules」）

要点：dependenciesコマンドは全体像の把握、dependencyInsightは特定依存関係の解決理由の調査に使う。ツリーの「→」と「(*)」の意味を理解すると問題特定が容易になる。

Gradleのバージョン管理：カタログ・BOM・ロックの活用法

Gradleのバージョン管理には、大きく分けて「宣言の一元管理」「解決の制御」「再現性の確保」という3つの目的があります。それぞれに対応する機能がバージョンカタログ、プラットフォーム（BOM）、依存関係ロックです。プロジェクトの規模や要件に応じて適切に組み合わせることが重要です。

バージョンカタログは、Gradle 7.0以降で利用できる公式推奨の一元管理機能です。デフォルトのファイルgradle/libs.versions.tomlにすべての依存関係とバージョンを集約し、ビルドスクリプトからエイリアスで参照します。複数モジュールで構成されるプロジェクトでは、バージョンの記述を1箇所にまとめられます。

ただし、バージョンカタログは「宣言されたバージョン」にのみ影響し、「解決されたバージョン」には影響しない点を理解しておく必要があります。推移的依存関係が別バージョンを要求した場合、Gradleは解決時に別バージョンを選ぶ可能性があります。（出典：Gradle公式「Using a Catalog with Platforms」）

バージョンカタログの基本構成と参照方法

バージョンカタログはTOML形式で記述し、versions、libraries、bundles、pluginsの4つのセクションで構成します。

[versions]
guava = "32.1.2-jre"
junit = "5.10.0"

[libraries]
guava = { module = "com.google.guava:guava", version.ref = "guava" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[bundles]
testing = ["junit-jupiter", "mockito"]

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version = "2.0.0" }

ビルドスクリプトでは、libs.エイリアス名の形式で参照します。Groovyではimplementation libs.guava、Kotlin DSLではimplementation(libs.guava)と記述します。bundlesを使えば関連する複数のライブラリを一括で参照でき、テスト関連の依存関係をまとめるのに便利です。

依存関係の更新には、バージョンカタログ内のバージョン番号を1箇所変更するだけで済みます。また、nl.littlerobots.version-catalog-updateのようなプラグインを使えば、最新バージョンへの更新を自動化できます。（出典：Gradle Plugin Portal「nl.littlerobots.version-catalog-update」）

BOMとplatform()によるバージョン整合性の確保

複数のライブラリが密接に関連するフレームワークでは、BOM（Bill of Materials）を使ってバージョンの整合性を保つのが効果的です。BOMは、一連のライブラリの互換性のあるバージョンの組み合わせを定義したMavenの仕組みです。

dependencies {
    implementation platform('org.springframework.boot:spring-boot-dependencies:3.3.0')
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

GradleではBOMをplatform()またはenforcedPlatform()でインポートします。両者の違いは以下の通りです。

enforcedPlatform()は「最後の手段の重いハンマー」とされ、通常はplatform()とstrictlyバージョンの組み合わせで制御することが推奨されます。（出典：Gradle公式「Importing Version Recommendations from a Maven BOM」）

依存関係ロックで再現性のあるビルドを実現する

依存関係ロック（Dependency Locking）は、推移的依存関係を含むすべての解決済みバージョンをロックファイルに記録する機能です。動的バージョンやスナップショットを使用する場合でも、一度ロックを生成すれば後続のビルドで同じバージョンが使用されます。

// build.gradle
dependencyLocking {
    lockAllConfigurations()
}

# ロックファイルを生成・更新
./gradlew dependencies --write-locks

ロックファイル生成後は、推移的依存関係のバージョンが変わるとビルドが失敗するため、意図しないバージョン変更を検知できます。バージョンを意図的に変更する場合は、--write-locksでロックファイルを再生成します。バージョンカタログと組み合わせることで、「宣言は一元管理、解決は固定」という強固な構成になります。（出典：Gradle公式「Dependency Locking」）

要点：バージョンカタログは宣言の一元管理、BOMはフレームワーク内のバージョン整合性、ロックは解決結果の固定に使う。3つは補完関係にあり、目的に応じて組み合わせる。

バージョン衝突を解決する：動的バージョンとstrictlyの使い方

Gradleの依存関係管理で多くの開発者が直面するのがバージョン衝突です。複数のライブラリが同じ依存関係の異なるバージョンを要求するケースは珍しくありません。Gradleはデフォルトで「楽観的アップグレード」と呼ばれる戦略を採用し、衝突した場合は最も高いバージョンを自動選択します。

この動作は通常は安全ですが、互換性のないバージョンが選択されて実行時エラーになることもあります。バージョン衝突を制御するには、衝突を検知して失敗させる方法、特定バージョンを強制する方法、あるいは動的バージョンの使用を控えて再現性を高める方法があります。

バージョン指定の方法は、単純な固定バージョンに加えて、動的バージョンとリッチバージョン制約があります。動的バージョンは柔軟性を提供しますが再現性を損ない、リッチバージョン制約はバージョン選択を細かく制御できます。それぞれの特性を理解して使い分けることが、依存関係管理の安定性につながります。

動的バージョンの問題点と対策

動的バージョンとは、バージョン番号の一部または全部をワイルドカードやキーワードで指定する方法です。例えば30.+は30系の最新版、latest.releaseは最新安定版を意味します。

implementation 'com.google.guava:guava:30.+'
implementation 'com.google.guava:guava:latest.release'

動的バージョンは利便性がありますが、ビルドの再現性を損なう重大なデメリットがあります。同じビルドスクリプトでも、実行するタイミングによって異なるバージョンが解決され、ビルド結果が変わってしまうためです。

対策としては、以下の方法があります。

• 動的バージョンを避け、固定バージョンを使用する
• 依存関係ロックと併用して解決結果を固定する
• resolutionStrategy.failOnDynamicVersions()で動的バージョンの使用を禁止する

公式は動的バージョンを使用する場合、依存関係ロックとの併用を推奨しています。（出典：Gradle公式「Resolution Strategy Tuning」）

strictlyとリッチバージョン制約の使い方

リッチバージョン制約は、バージョン選択のルールを詳細に指定できる機能です。単純なバージョン番号に加えて、strictly、require、prefer、rejectの4つの制約を組み合わせて使用します。

strictlyは最も強力な制約で、他の依存関係が異なるバージョンを要求していても、指定したバージョンが強制的に選択されます。バージョン衝突を確実に解決したい場合に有効ですが、過度な使用は依存関係の解決を難しくする可能性があります。

implementation('commons-codec:commons-codec:1.9') {
    version {
        strictly('1.9')
    }
}

通常はrequireやpreferを使って緩やかに制御し、どうしても必要な場合にのみstrictlyを使用するのが良いアプローチです。（出典：Gradle公式「Preventing Accidental Dependency Upgrades」）

バージョン衝突を検知して制御する実践的手法

バージョン衝突に気づかずビルドが進むことを防ぐには、衝突を明示的に検知してビルドを失敗させる設定が有効です。デフォルトの楽観的アップグレードに任せるのではなく、衝突が発生した時点でエラーにすることで、問題を早期に発見できます。

configurations.all {
    resolutionStrategy {
        failOnVersionConflict()  // バージョン衝突時にビルドを失敗させる
    }
}

また、特定のバージョンを強制する別の方法としてforceがありますが、公式はforceよりも依存関係制約（constraints）やstrictバージョンの使用を推奨しています。forceはすべての設定に一律に適用されるため、意図しない影響範囲が大きくなりがちです。

実践的には、まずdependencyInsightコマンドで衝突の原因を特定し、その上で以下の優先順位で対処するのがおすすめです。

1. excludeで不要な推移的依存関係を除外する
2. require/preferで緩やかにバージョンを誘導する
3. strictlyで厳密にバージョンを固定する
4. 最終手段としてforceやenforcedPlatform()を使用する

要点：動的バージョンは再現性を損なうため避けるか、ロックと併用する。バージョン衝突はまず原因を特定し、緩やかな制約から段階的に対処する。

“`