Spring Boot 3.3 から 4.0 への移行ガイド｜段階的アップグレード戦略

pring Boot 3.3 の OSS サポートは既に終了しており、4.0 への移行を検討している方も多いのではないでしょうか。

この記事では、Spring Boot 3.3 から 4.0 へ移行する際に 何が変わるのか、そして どういう順番で進めるべきか を、実務者目線でまとめます。

2.x から 3.x への移行では javax.* → jakarta.* の全面変更や Java 17 対応、AWS SDK 対応で苦労した方も多いと思いますが、3.x → 4.x はそこまでの激変ではありません。

ただし、油断するとハマるポイントはいくつかあります。

Spring Boot 4.0 で何が変わるのか

Spring Boot 4.0 は 2025年11月20日に正式リリースされました。

2026年3月時点で 4.0.5 まで パッチがリリースされており、安定した状態です。

あわせて読みたい

Spring Boot はいつまで使える？サポート期限とバージョン選定の指針

基盤要件の変更

主な破壊的変更

1. Jackson 2 → Jackson 3（影響度：大）

JSON のシリアライズ・デシリアライズに使われる Jackson がメジャーバージョンアップします。

ほぼすべての Spring Boot アプリケーションに影響があります。

• グループID: com.fasterxml.jackson → tools.jackson
• パッケージ名変更: カスタム Serializer / Deserializer を書いている場合は修正が必要
• 設定プロパティ: spring.jackson.read.* → spring.jackson.json.read.*

移行期間用に spring-boot-jackson2 互換モジュールが提供されているので、一気に移行できない場合はこちらを利用できます。

外部連携ライブラリが内部で Jackson を使っている場合、Jackson 3 との互換性が問題になる可能性があるので注意してください。

2. モジュール構造の大幅再編（影響度：大）

Spring Boot 4.0 ではモジュールが細分化され、命名規則が統一されました。

• モジュール: spring-boot-<technology>
• パッケージ: org.springframework.boot.<technology>
• スターター: spring-boot-starter-<technology>

import 文の修正が広範囲に発生する可能性があります。

3. Spring Security 7（影響度：大）

• WebSecurityConfigurerAdapter が完全削除（3.x で非推奨だったもの）
• Spring Authorization Server が Security に統合
• OAuth2 系スターター名の変更

4. テスト関連（影響度：中）

• @MockBean / @SpyBean → @MockitoBean / @MockitoSpyBean に置き換え
• @SpringBootTest で MockMVC 等が自動提供されなくなる（明示的アノテーション必要）

5. データベース関連（影響度：中）

• MongoDB: spring.data.mongodb.* → spring.mongodb.*
• Elasticsearch: RestClient → Rest5Client
• Hibernate: hibernate-jpamodelgen → hibernate-processor
• Spring Batch: メモリ内モードがデフォルトに変更

6. 削除されたコンポーネント（影響度：中）

• Undertow サポート削除（Servlet 6.1 非対応のため）
• Spring Session Hazelcast / MongoDB 削除
• Spock テスト統合 削除
• 埋め込み実行可能 Jar スクリプト 廃止

7. その他の変更（影響度：小）

• Logback デフォルト charset が UTF-8 に統一
• DevTools Live Reload がデフォルト無効に
• BootstrapRegistry 等のパッケージ移動

2.x → 3.x と比較して、どのくらい大変？

結論から言うと、2.x → 3.x の半分以下の工数で済む可能性が高いです。

2.x → 3.x では javax.* → jakarta.* の全面書き換え、Java 8/11 → 17 の大ジャンプ、AWS SDK v1 → v2 の移行が同時期に重なりました。

3.x → 4.x では jakarta.* の移行は不要ですし、Java のベースライン引き上げも 17 → 21 と比較的穏やかです。

ただし、Jackson 3 やモジュール再編は IDE の一括置換だけでは済まないケースがあるので、非推奨 API をどれだけ使っているかで工数が変わります。

段階的移行のすすめ

一気に 3.3 → 4.0 にジャンプするのではなく、3段階に分けて進めることを強く推奨します。

各フェーズを独立したリリースとして切ることで、問題の切り分けが格段に楽になります。

Phase 1: Java 17 → 21（Boot はそのまま 3.3）

最初に取り組むべきは、Spring Boot のバージョンを変えずに Java 21 へ上げることです。

これが最大の鬼門になり得ます。

特に外部連携で使っている他社提供ライブラリが Java 21 で正常に動作するかどうかは、実際に動かしてみないとわかりません。

やること

• jdeps で内部 API 使用の洗い出し
• 他社通信ライブラリの動作検証
• CI/CD・本番ランタイムの Java バージョン更新

検証コマンド

# 依存ライブラリが JDK 内部 API を使っているか検出
jdeps --jdk-internals --multi-release 21 your-app.jar

Java 16 以降、JDK 内部 API への --add-opens なしのアクセスが制限されています。

古いライブラリが sun.misc.Unsafe などを触っている場合、実行時に InaccessibleObjectException が発生します。

Boot のバージョンとは無関係に進められるので、ここで地雷を踏むかどうかを早期に確認できます。

問題が見つかれば、代替ライブラリの調査やベンダーへの問い合わせの時間を確保しましょう。

Phase 2: Boot 3.3 → 3.5

Java 21 対応が完了したら、次は Boot 3.5 に上げます。

3.5 は 4.0 への「準備ステップ」として非常に重要です。

3.5 で出る deprecation warning が、4.0 で削除される対象そのものだからです。

やること

• Boot 3.5 へのバージョンアップ
• deprecation warning の洗い出しと修正
• @MockBean → @MockitoBean 等の先行対応
• Kotlin 2.2 対応（Kotlin を使っている場合）

3.5 のサポート期限は短いですが、この作業自体が 4.0 への移行準備なので無駄になりません。

Phase 3: Boot 3.5 → 4.0

ここまで来れば、残りの作業は比較的見通しが良くなっています。

やること

• Jackson 3 対応（グループID・パッケージ名の変更）
• モジュール構造・import の修正
• Spring Security 7 対応
• Spring Batch の動作検証
• Flyway の動作検証（Flyway を使っている場合）
• Gradle 9 対応（Gradle を使っている場合）

Flyway を使っている場合は、Boot 4.0 が要求する Flyway バージョンで既存のマイグレーションスクリプトが全件通るか、ステージング環境でテストしておくと安心です。

まとめ

Spring Boot 3.3 → 4.0 の移行は、2.x → 3.x ほどの激変ではありませんが、Jackson 3 やモジュール再編など、対応すべき点は確実にあります。

大切なのは以下の3つです。

1. Java 21 対応を先行する — Boot と切り離して検証でき、最大のリスクを早期に潰せる
2. 3.5 を経由する — deprecation warning = 4.0 で壊れる箇所。先に潰す
3. フェーズごとにリリースを切る — 問題の切り分けと手戻りの最小化

4.0 は既に 4.0.5 までパッチが出ており、十分に安定しています。

段階的に、着実に進めていきましょう。
(4.1 系のリリースも近いですが)

あわせて読みたい

Spring Boot はいつまで使える？サポート期限とバージョン選定の指針

参考リンク

• Spring Boot 4.0 Release Notes
• Spring Boot 4.0 Migration Guide
• Spring Boot サポート期限一覧（公式）

saratoga

フリーランスエンジニア

XYouTube

仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。