dependency-conflict-resolver

依存関係の競合解決

ソースマッピング：Kotlin_Spring_Developer_Pipeline.md（SK-05）から派生した、Tier 2 の高価値スキルです。

ミッション

実際にどのアーティファクトのバージョンが採用されるのか、その理由、そして最も限定的で安全な修正方法を特定します。 依存関係の競合解決は、当てずっぽうで推測するのではなく、バージョンの決定権を特定する問題として扱います。

最初に確認する項目

• ./gradlew dependencies またはモジュール単位の依存関係出力。
• 問題のライブラリファミリーに対する ./gradlew dependencyInsight --dependency <artifact>。
• ルートとモジュールのビルドファイル、バージョンカタログ、インポートされた BOM、プラグインのバージョン。
• 正確なランタイムまたはコンパイル時エラー：
  • NoSuchMethodError
  • ClassNotFoundException
  • NoClassDefFoundError
  • AbstractMethodError
  • バインディングの重複に関する警告

次の順に診断する

1. 問題のクラスまたはメソッドの所有元を特定します。
2. そのクラスを提供するアーティファクトを特定します。
3. 依存関係グラフ上にある候補バージョンをすべて特定します。
4. 採用されるバージョンと、その理由を特定します：
   • 直接依存関係
   • BOM またはプラットフォーム
   • バージョンカタログのエイリアス
   • 推移的依存関係
   • 競合解決ルール
5. ファミリーのバージョンを管理すべき、本来の決定元を特定します。

高度なクラスパスの落とし穴

• コンパイル時のビルドが成功しているのにランタイムでリンクエラーが発生する場合、通常はインポートの不足ではなく、解決されたアーティファクト間のバイナリ非互換性が原因です。
• Jackson、Netty、SLF4J、Logback、Kotlin stdlib、Hibernate の各ファミリーは、通常、個別のアーティファクトごとにパッチを当てるのではなく、ファミリー全体でバージョンを揃える必要があります。
• プラグインのクラスパスとアプリケーションのクラスパスは別のものです。プラグインのアップグレードでランタイムライブラリの競合が解決するとは限らず、その逆も同様です。
• テスト時のランタイムは、メインのランタイムと異なる場合があります。テストでのみ発生する競合は、テストフィクスチャ、モックライブラリ、またはテストコンテナのサポートに起因している可能性があります。
• enforcedPlatform、strictly、除外は競合を解決できますが、依存関係グラフを気づかないうちに脆弱な状態に固定することもあります。意図を持って使用してください。
• 複数のロギングバインディングは、深刻な障害が発生するずっと前から、起動時の挙動を分かりにくくすることがよくあります。
• 通常の Spring Boot アプリでは、シェーディングやリロケーションが最初の解決策になることはほとんどありません。クラスパスの分離が本当に必要な場合にのみ検討してください。

Gradle の解決に関する注意点

• バリアント対応の解決では、使用方法、JVM バージョン、ケイパビリティなどの属性に基づいてアーティファクトが選択される場合があります。依存関係が「存在」していても、誤ったバリアントに解決されることがあります。
• 宣言されたバージョンが妥当に見えても、BOM のインポート順や複数のプラットフォームによって、どのファミリーが採用されるかが微妙に変わることがあります。
• 共有モジュールでの api と implementation の漏出により、下流のコンシューマーでのみ競合が表面化することがあります。
• 再パッケージ化またはリロケーションされた JAR に含まれるクラスの重複は、ランタイムのクラスローディングや自動設定スキャンが行われるまで表面化しない場合があります。
• アノテーションプロセッサ、KSP、プラグインのクラスパスは、メインアプリケーションのランタイムとは別にバージョンを揃える必要がある場合があります。

エキスパート向けヒューリスティック

• 症状がランタイムでのみ発生する場合は、IDE の依存関係ツリーだけでなく、パッケージ化されたアーティファクトまたはランタイムクラスパスを調べます。
• ライブラリファミリーが Spring Boot によって管理されている場合は、ローカルでのバージョン指定を増やすのではなく、BOM に管理を戻すことを優先します。
• 同じ競合が複数のモジュールで再発する場合は、モジュールごとにパッチを当てるのではなく、プラットフォームまたは規約のレベルで解決します。
• 依存関係が使われていないように見える場合は、削除する前に、リフレクション、自動設定、またはサービスローダーによる使用を確認します。

推奨する解決方法

• BOM が互換性のあるバージョンをすでに管理している場合は、不要な明示的バージョン指定を削除することを優先します。
• 影響を受ける依存関係ファミリー全体でバージョンを揃えることを優先します。
• バージョンの上書きが本当に必要な場合は、隠れた除外ではなく、直接指定した文書化済みのバージョン上書きを優先します。
• 除外は、依存関係がそのモジュールにとって本当に不適切な場合にのみ使用し、単に扱いづらいという理由では使用しません。
• 次回のアップグレード後に競合が再発しないよう、選択したレイヤーがバージョンを管理すべき理由を説明します。

出力要件

次のセクションを返します。

• 競合の概要：何がどこで競合しており、どこに症状が現れるか。
• 採用される経路：解決されたアーティファクトのバージョンがどのように選択されるか。
• バージョンの管理元：修正を管理すべきファイルまたはプラットフォーム。
• 最小限の修正：最も小さく、安全な依存関係またはプラットフォームの変更。
• 検証：依存関係グラフが健全であることを確認する、コンパイル時と実行時のチェック。

ガードレール

• 既存の互換性モデルをたどらずに、バージョン番号をでっち上げないでください。
• 依存関係グラフが正常になるまで、除外設定をやみくもに追加しないでください。
• forceをデフォルトの解決策として使わないでください。
• ライブラリファミリー全体のバージョンが不整合なのに、目に見えて失敗しているアーティファクトだけを修正しないでください。

品質基準

このスキルの適切な実行では、競合の経路を説明し、適切な管理レイヤーで解決します。 不適切な実行では、今日のコンパイルは通るものの、次のブランチで同じ競合を再発させる場当たり的なバージョン固定を行います。