spring-boot-4-migration

Spring Boot 4 移行スキル

Spring Boot 2.7.x アプリケーションを 3.5.x に移行し、続いて 3.5.x から 4.x に移行します。その後も、各移行段階における公式の Spring Boot 移行ガイドとリリースノートを基準に、4.x のマイナーバージョンを最新の状態に保ちます。

最新情報

最終確認：2026-07（Spring Boot 4.1.0／Framework 7.0.8 の時点）。ここに記載された情報は古くなる可能性があります。削除対象、管理対象の依存関係のバージョン、OpenRewrite のレシピ ID、「X で非推奨」といった記述など、バージョンに左右される情報に基づいて回答する場合は、上記の日付から時間が経っていれば、回答の前に最新のリリースノートやツールのソースを確認してください。最新のドキュメントとこのファイルの内容が食い違う場合は、ドキュメントを優先してください。そのうえで、このファイルの該当箇所が古いことを伝えてください。

対象範囲：2.7.x → 3.5.x → 4.x および 4.x のマイナーバージョン

このスキルでは、次の 3 つのシナリオを扱います。

1. レガシー移行（2.7.x → 3.5.x） — 前段階の移行です。references/spring-boot-2-to-3-migration.md で説明しています。Java 8/11 → 17 のベースライン、Jakarta EE の名前空間への移行（javax.* → jakarta.*）、Spring Security 5 → 6、Hibernate 5 → 6、Micrometer Tracing／Observation へのオブザーバビリティ移行、各ステップを自動化する OpenRewrite レシピを扱います。ここで Boot 3.5 の最新パッチに到達してから、次のシナリオに進みます。
2. メジャー移行（3.5.x → 4.0） — このスキルの中心となる内容です。以下の 9 つのフェーズ、段階的なアップグレード戦略、ブリッジシステムを扱います。
3. マイナーバージョンのアップグレード（4.0 → 4.1、4.1 → 4.2 など） — references/minor-version-changes.md で管理しています。マイナーバージョンでは API が非推奨になったり、互換性ブリッジが削除されたり、デフォルトが変更されたり、新機能が導入されたりすることがあります。新しい 4.x のマイナーバージョンに上げる前に、このファイルを確認してください。

プロジェクトが Boot 2.7.x 以前の場合は、まず下記の §「Spring Boot 2.7 から移行する場合」から始めてください。2 → 3 の移行を完了してから、ここに戻って 3 → 4 のフェーズに進んでください。

API を最新のドキュメントで確認する

この移行では多くの API が変わります。API、プロパティ、パターンが移行先のバージョンでも有効かどうかわからない場合は、モデルの知識に頼らず、調べて確認してください。

• ライブラリのドキュメントには Context7（mcp__claude_ai_Context7__resolve-library-id に続いて mcp__claude_ai_Context7__query-docs）を使用してください。
• 破壊的変更のお知らせ、CVE、コミュニティの移行事例には WebSearch／WebFetch を使用してください。
• リリースノートの確認には gh を使用してください（例：gh api repos/spring-projects/spring-boot/releases/latest）。

ツールチェーンのバージョン確認（最初に実施）

移行を始める前に、プロジェクトの Java、Kotlin、Maven、Gradle のバージョンを確認してください。移行先の Boot バージョンに必要な最小バージョンを下回るものがあれば、Boot を上げる前にアップグレードしてください。

最小バージョンと推奨バージョンの一覧、および各ツールのアップグレードコマンドについては、references/toolchain-versions.md を参照してください。

Spring Boot 2.7 から移行する場合は、ここから始めてください

プロジェクトが Spring Boot 2.7.x 以前の場合は、まず 2.7 → 3.5 の移行を完了してください。順序は Boot 2.7.x → Boot 3.5.x latest → Boot 4.x です。

references/spring-boot-2-to-3-migration.md を参照してください。ツールチェーンのアップグレード、2.7.18 の事前確認、OpenRewrite のレシピ（UpgradeSpringBoot_3_5 による一括移行またはマイナーバージョンごとの移行）、Jakarta 名前空間、Security 5 → 6、Hibernate 5 → 6、プロパティの移行、Micrometer Tracing へのオブザーバビリティ移行について説明しています。

Boot 3.5 の最新パッチで ./mvnw verify／./gradlew build が成功し、spring-boot-properties-migrator からの警告がなくなったら、ここに戻ってください。

前提条件

3.x → 4.0 の移行の場合：

• ツールチェーンのバージョンが最小要件を満たしていること（上記の「ツールチェーンのバージョン確認」を参照）
• 移行元プロジェクトが Spring Boot 3.5.x（最新パッチ）でコンパイルでき、テストに合格すること
• Java 17 以降を利用できること（Java 21 以降を推奨、Java 25 もサポート）
• 可能な範囲で、Boot 3.x の非推奨 API 呼び出しをすべて解消していること
• Boot 3.4 以前を使用している場合は、先に 3.5.x にアップグレードしてから進めること

4.x → 4.y のマイナーバージョンアップグレードの場合：

• 現在のマイナーバージョンの最新パッチ版を使用していること（例：4.0.x の最新）
• 対象バージョンの references/minor-version-changes.md を確認します
• 対象バージョンの公式リリースノートを確認します
• 現在のバージョンで発生している非推奨警告を解消します

移行戦略を選択する

戦略 1 — 段階的アップグレード（エンタープライズ／大規模なコードベースに推奨） まず references/gradual-upgrade-strategy.md をお読みください。この戦略では、移行を 依存関係グラフとして捉えます。互換性ブリッジを使った初日のベースラインを構築し、 その後、6 つの独立したトラック（スターター、Jackson 3、プロパティ、セキュリティ、テスト、 Framework 7）を自分のペースで完了します。主なブリッジ：

• spring-boot-starter-classic — 3.x のモノリシックな自動構成を復元します
• spring-boot-jackson2 — Boot 4 と併用しながら Jackson 2 のコードを動作させます
• spring-security-access — 従来の AccessDecisionManager/Voter を橋渡しします 次の場合に使用します：複数のチーム、多数のサービス、段階的なロールアウトがある場合、 または Jackson 3／Security 7 への完全な移行に 1 スプリント以上かかる場合。

戦略 2 — 一括アップグレード（以下を参照） 9 つのフェーズすべてを 1 回の作業で順番に実行します。新規プロジェクト、 小規模なコードベース、または単一チームで所有するプロジェクトに最適です。

OpenRewrite による自動移行

手動で移行する前に、OpenRewrite のレシピを使って機械的な変更を自動化することを検討してください。 まず OpenRewrite を実行して一括検索・置換を行い、その後、このスキルの各フェーズを使って、 残りの手動変更（Security DSL の書き換え、動作の違い、プロパティのセマンティクスなど）に対処します。

2.7 → 3.5 の移行（3 → 4 の作業を行う前に実行）：references/spring-boot-2-to-3-migration.md の § 3 にあるレシピ表を参照してください。UpgradeSpringBoot_3_5 の一括レシピですべての手順を実行できます。または、大規模なコードベースではマイナーバージョンごとに実行してください。

3.5 → 4.0 の移行：

レシピ ID	対応範囲
org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0（Community Edition 版も利用可能）	Boot 3.5 → 4.0
org.openrewrite.java.spring.kafka.UpgradeSpringKafka_4_0	Spring Kafka 3.x → 4.0（Boot 4 のレシピと併用してください。references/spring-kafka-4-migration.md を参照）
org.openrewrite.java.jackson.UpgradeJackson_2_3	Jackson 2 → 3 のパッケージ／インポートの移行
org.openrewrite.java.spring.boot4.ReplaceMockBeanAndSpyBean	@MockBean/@SpyBean → @MockitoBean/@MockitoSpyBean

参照先：moderne.ai/blog/spring-boot-4x-migration-guide。4.0 のレシピについては、こちらを参照してください：docs.openrewrite.org/recipes/java/spring/boot4/upgradespringboot_4_0-community-edition。

実行方法：./mvnw org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE -Drewrite.activeRecipes=<recipe-id>（Maven）または ./gradlew rewriteRun -Drewrite.activeRecipes=<recipe-id>（Gradle）。

移行ワークフロー（一括アップグレード）

これらのフェーズを順番どおりに実行します。次のフェーズに進む前に、各フェーズでコンパイルが成功し、テストに合格する必要があります。

フェーズ 1：ビルドファイルの移行

Boot／Framework のバージョンとビルドプラグインを更新し、非推奨の スターターをモジュール化された同等のものに置き換えます。テストで使用する各 テクノロジーに対応するモジュール化されたテストスターターを追加します。必要に応じて、 一時的な対処としてクラシックスターターを使用してください。

スターターの完全な対応表、ビルドプラグインの変更点、手順については references/build-and-dependencies.md をお読みください。

プロジェクトで Spring for Apache Kafka を使用している場合は、 references/spring-kafka-4-migration.md もお読みください。Spring Kafka 4 では テストスターターの座標が変更され（spring-kafka-test → spring-boot-starter-kafka-test）、UpgradeSpringBoot_4_0 と併せて実行すべき専用の OpenRewrite レシピが付属しています。

コンパイルチェック：mvn compile または gradle compileJava を実行し、続行する前に 依存関係の解決エラーを修正します。

フェーズ 2：プロパティの移行

すべての application.properties、application.yml、プロファイル固有の バリアント、および @SpringBootTest(properties = ...) アノテーションを 確認します。変更されたプロパティキー（Jackson、MongoDB、セッション、Actuator、Hibernate）を 変更してください。

プロパティの完全なマッピングについては、references/property-changes.md を お読みください。

フェーズ 3：Jackson 3 への移行

Boot 4 では Jackson 3 がデフォルトです。グループ ID、パッケージ、および 名前が変更された Boot クラス（@JsonComponent → @JacksonComponent など）を 移行してください。必要に応じて、一時的な回避策として spring-boot-jackson2 ブリッジを使用してください。

詳細については、references/jackson3-migration.md をお読みください。 プロジェクトで Spring Kafka の JSON シリアライザー／デシリアライザーや ヘッダーマッパーを使用している場合は、 references/spring-kafka-4-migration.md の Jackson セクションもお読みください。Kafka のシリアライザーコードは tools.jackson.* パッケージツリーに移動します。

フェーズ 4：パッケージと API の移転

移転されたインポート（@EntityScan、BootstrapRegistry など）、削除された API（PropertyMapper.alwaysApplyingNotNull、パスマッチングオプション）、および 非推奨のコンバーターを修正してください。該当する場合は、HTTP クライアントのコードも移行してください。

移転されたパッケージと削除された API の全一覧については、 references/api-changes.md をお読みください。 プロジェクトで RestClient、 WebClient、@HttpExchange、または Feign を使用している場合は、 references/http-clients.md もお読みください。

フェーズ 5：オブザーバビリティの移行

Micrometer／OTel の個別の依存関係を、統合された spring-boot-starter-opentelemetry スターターに置き換え、OTLP プロパティを更新し、オブザーバビリティモジュールの名前を変更してください。Actuator は OTel のエクスポートに必須ではなくなりました。

詳細については、references/observability-migration.md をお読みください。

フェーズ 6：Spring Security 7 への移行

Security 7 DSL（ラムダのみ、and() は使用不可）に移行し、削除された AuthorizationManager#check を置き換え、PathPatternRequestMatcher に切り替え、Jackson／SAML の統合を更新してください。レガシーな AccessDecisionManager／Voter のコードをすぐに移行できない場合は、spring-security-access ブリッジを使用してください。

詳細については、references/spring-security7.md をお読みください。

フェーズ 7：テストインフラストラクチャの移行

@MockBean／@SpyBean（非推奨になっただけではなく、削除されています）を @MockitoBean／@MockitoSpyBean に置き換えてください。テスト用 HTTP クライアントには、明示的な自動構成アノテーションを追加してください。Testcontainers 2 のモジュール名／パッケージを移行し、JUnit 6 を採用してください。各テクノロジーに対応したモジュール式のテストスターターを追加してください。

詳細については、references/testing-migration.md をお読みください。 プロジェクトで @EmbeddedKafka または EmbeddedKafkaZKBroker を使用している場合は、 references/spring-kafka-4-migration.md もお読みください。Spring Kafka 4 では ZooKeeper のコードパス（KRaft のみ）と、それに対応する @EmbeddedKafka の属性が削除されます。

フェーズ 8：Spring Framework 7 固有の変更

JSpecify の null 可能性（Kotlin への影響）、非推奨の AntPathMatcher、MVC XML 設定の削除、SpringExtension のスコープ変更、Hibernate 7.1 のエンティティマッピングの変更、および Spring Retry から Framework コアのリトライへの移行に対応してください。

詳細については、references/spring-framework7.md をお読みください。 プロジェクトで Spring Retry、@Retryable、@ConcurrencyLimit、または Resilience4j を使用している場合は、 references/resilience-migration.md もお読みください。 プロジェクトで Spring for Apache Kafka を使用している場合は、 references/spring-kafka-4-migration.md もお読みください。Spring Kafka 4 では Spring Retry への依存が削除され、Framework 7 コアのリトライが採用されます。また、 BackOffValuesGenerator では BackOffPolicy の代わりに BackOff が使われるようになりました。 必要に応じて、Framework 7 で導入された新しい API バージョニング機能について、 references/api-versioning.md もお読みください。

フェーズ 9：最終確認

検証スクリプトがあれば実行し、ない場合は手動で確認します。

1. mvn clean verify または gradle clean build — コンパイルとテストをすべて実行します
2. アプリケーションの起動を確認します：mvn spring-boot:run または gradle bootRun
3. Actuator のヘルスチェックを確認します：curl localhost:8080/actuator/health
4. ライブネス／レディネスプローブを確認します（デフォルトで有効になっています）
5. 構造化ログの出力形式を確認します
6. 有効な Spring プロファイルごとに統合テストを実行します
7. buildpacks または Jib を使用している場合は、Docker イメージがビルドされることを確認します

AOT 処理、GraalVM ネイティブイメージ、または新しい AOT キャッシュ機能の導入を予定している場合は、references/aot-native.md もお読みください。

マイナーバージョン間のアップグレード（4.0 → 4.1、4.1 → 4.2 など）

Spring Boot 4.x のマイナーバージョン間でアップグレードする場合は、次の手順に従ってください。

1. 変更点を確認する

対象バージョンの references/minor-version-changes.md をお読みください。また、公式のリリースノートも参照してください。

• https://github.com/spring-projects/spring-boot/wiki （バージョンごとのリリースノート）
• https://docs.spring.io/spring-boot/upgrading.html

2. ブリッジの削除に注意する

互換性ブリッジはマイナーバージョンで削除されます。アップグレードする前に、依存しているブリッジが削除される予定かどうかを確認してください。

ブリッジ	導入バージョン	削除予定
spring-boot-jackson2	4.0	4.3.0（Javadoc の forRemoval による）
spring-boot-starter-classic	4.0	5.0
spring-boot-starter-test-classic	4.0	5.0
非推奨のスターター名	4.0	5.0

対象バージョンで削除されるブリッジをまだ使用している場合は、アップグレードする前に、対応する移行トラックを完了してください。

3. アップグレード手順

1. ビルドファイル内の Spring Boot のバージョンを、対象マイナーバージョンの最新パッチリリースに更新します。
2. mvn compile ／ gradle compileJava を実行し、新たに発生したコンパイルエラーを修正します。
3. テストスイート全体を実行し、テストの失敗を修正します。
4. ビルド出力とアプリケーションログの両方で、非推奨警告を確認します。これらは次のマイナーバージョンで問題になる箇所を示します。
5. verify_migration.sh を実行して、移行状況を確認します。

4. 新機能

各マイナーバージョンでは、新機能と自動設定が導入されます。これらはオプトイン方式で、対応は必須ではありませんが、導入を検討してもよいでしょう。各リリースのノートにある「新機能と注目点」のセクションを確認してください。

トラブルシューティング

よくあるコンパイルエラー

エラー	原因	修正方法
ClassNotFoundException: ...autoconfigure...	モジュール化されたスターターが必要です	該当する spring-boot-starter-X を追加します
NoSuchMethodError: PropertyMapper.alwaysApplyingNotNull	API が削除されました	代わりに always() を使用します
Cannot resolve symbol JsonComponent	名前が変更されました	@JacksonComponent を使用します
Package com.fasterxml.jackson does not exist	Jackson 3 のパッケージです	tools.jackson に変更します
Cannot resolve symbol MockBean	非推奨または削除されました	@MockitoBean を使用します
ClassNotFoundException: RestClientBuilderCustomizer	Elasticsearch の変更です	Rest5ClientBuilderCustomizer を使用します

簡単な修正方法

• バージョンを更新した後、ビルドがまったくコンパイルできない場合は、spring-boot-starter-classic と spring-boot-starter-test-classic を使用して起動できる状態にしてから、段階的にモジュール化されたスターターへ移行します。初日の完全なベースラインについては、references/gradual-upgrade-strategy.md を参照してください。
• Jackson 3 への移行が妨げになっている場合は、一時的に spring-boot-jackson2 を追加します。これは正式にサポートされているブリッジです。段階的な移行戦略のトラック B を参照してください。
• Spring Security の変更が広範囲にわたる場合は、spring-security-access ブリッジを追加し、まず Security 6.5 の準備手順に従ってアップグレードします（これらの手順では、7.0 の破壊的変更を回避するフラグが提供されます）。段階的な移行戦略のトラック D を参照してください。
• 多数のサービスを対象とするエンタープライズ展開では、references/gradual-upgrade-strategy.md のウェーブ 1〜4 のアプローチを使用し、影響範囲を最小限に抑えます。

リファレンスファイル一覧

ファイル	読むタイミング
references/toolchain-versions.md	ツールチェーンの確認 — Java／Kotlin／Maven／Gradle の最小バージョンと、ツールごとのアップグレードコマンド
references/spring-boot-2-to-3-migration.md	Boot 2.7.x → 3.5.x への準備 — Java のベースライン、Jakarta への移行、Hibernate 5 → 6、Security 5 → 6、OpenRewrite のレシピ、マイナーバージョンごとの主な変更点
references/gradual-upgrade-strategy.md	最初に読む（3 → 4 の場合）— 移行の依存関係グラフ、ブリッジ、独立したトラック、エンタープライズでの展開
references/build-and-dependencies.md	フェーズ 1／トラック A — スターターの完全な対応表、ビルドプラグインの変更
references/property-changes.md	フェーズ 2／トラック C — すべてのプロパティキーの名称変更と値の変更
references/jackson3-migration.md	フェーズ 3／トラック B — Jackson 3 のパッケージ、API、互換モード
references/api-changes.md	フェーズ 4 — パッケージの移動、削除された API、名称変更されたクラス
references/observability-migration.md	フェーズ 5 — OpenTelemetry スターター、OTLP プロパティ、モジュールの名称変更、Actuator の分離
references/spring-security7.md	フェーズ 6／トラック D — Security 7 の破壊的変更と DSL の移行
references/testing-migration.md	フェーズ 7／トラック E — 2.7→3 のテスト移行（JUnit 4→5、javax→jakarta のテスト）、続いて 3.5→4：MockBean、Testcontainers 2、JUnit 6、RestTestClient
references/spring-framework7.md	フェーズ 8／トラック F — Framework 7 の変更、JSpecify、パスマッチング
references/http-clients.md	HTTP クライアント — RestClient、WebClient、@HttpExchange、Feign の移行、RestTestClient
references/api-versioning.md	API のバージョン管理 — 戦略、セマンティック範囲、クライアント側、非推奨化、テスト
references/resilience-migration.md	レジリエンス — Spring Retry → Framework 7、@Retryable、@ConcurrencyLimit、Resilience4j
references/spring-kafka-4-migration.md	Spring for Apache Kafka 4 — Apache Kafka 4 クライアント（KRaft のみ）、EmbeddedKafkaZKBroker の削除、spring-boot-starter-kafka-test、Jackson 3 シリアライザー、Spring Retry の削除、KIP-848／KIP-932、OpenRewrite のレシピ
references/aot-native.md	AOT／ネイティブ — BeanRegistrar、RuntimeHints、Spring Data AOT、GraalVM 25、AOT Cache
references/minor-version-changes.md	4.x のマイナーバージョンアップグレード — マイナーバージョンごとの変更、ブリッジの削除、新機能
scripts/verify_migration.sh	フェーズ 9 — ブリッジを考慮した PASS／FAIL／WARN／BRIDGE による検証

各移行段階の信頼できる外部ソースは、対応するリファレンスファイルの末尾に記載されています。