Spring Boot 4への移行は、pom.xmlやbuild.gradleのバージョン番号を一つ変えるだけの作業ではありません。Spring Framework 7、Jakarta EE 11、Servlet 6.1を土台とし、依存ライブラリ、設定プロパティ、組み込みサーバー、JSON処理、テスト基盤にも変更が及びます。安全に進めるには、現在のアプリを最新のSpring Boot 3.5系で正常化してから、実行環境と依存関係を棚卸しし、小さな単位で4.xへ移行することが重要です。
本記事では、既存アプリをSpring Boot 4へ更新する前の判断と準備に焦点を当てます。個々のエラーを場当たり的に直すのではなく、基準となる3.5系の状態を作り、変更点を分類し、同じテストで移行前後を比較できるようにします。2026年11月2日時点の最新安定版は4.1.2ですが、4.0の公式移行ガイドを出発点にし、採用する4.xの保守版に合わせて公式ドキュメントを再確認してください。
1. Spring Boot 4移行の出発点を決める
1.1 最新の3.5系を経由する
Spring Boot 4へ移行する前に、アプリを最新の3.5系へ更新します。公式移行ガイドも、古い3.xや2.xから4.0へ直接上げるのではなく、先に最新の3.5.xへ移行することを推奨しています。段階を分けると、3.5系までの変更と4.xで生じた変更を別々に調査できます。
たとえば2.7から4.xへ一度に更新すると、javaxからjakartaへの名前空間変更、Javaの最低バージョン、Spring Securityの設定、Spring Boot 4のモジュール再編が同時に現れる可能性があります。コンパイルエラーが50件出ても、どの世代の変更が原因か分かりにくくなります。まず2.7から3.x、次に最新3.5系、最後に4.xというように、各段階でビルドとテストを正常にしてください。
移行開始前には、3.5系で動く状態をコミットまたはタグとして残します。依存関係一覧、テスト結果、起動ログ、主要APIのレスポンス、使用中の設定値も保存すると、4.xで差が出たときに比較できます。「移行前から失敗していたテスト」を4.xの問題として追いかけないことが、調査時間の短縮につながります。
基準状態には、成功した情報だけでなく、既知の警告と除外しているテストも記録します。移行前から出ていた非推奨警告や一時的な外部サービス失敗を残さないと、4.xで新しく発生したものと区別できません。警告件数をゼロにできない場合も、内容、理由、解消予定を一覧にしておけば、新規警告だけを検出できます。
複数モジュールのプロジェクトでは、ルートだけでなく各モジュールのSpring Bootプラグイン、依存管理、Java設定を確認します。一部モジュールだけが古いBOMやJava設定を持つと、ルートのビルドは成功しても、個別実行やIDE上で異なる依存関係が選ばれることがあります。
1.2 移行先の保守版を固定する
「Spring Boot 4へ上げる」だけでは、再現可能な作業条件になりません。4.0.9と4.1.2では、依存ライブラリや修正内容が異なります。作業計画には、Spring Boot、Java、MavenまたはGradle、Spring Cloudなど主要な関連プロジェクトのバージョンを明記します。
新規移行では、原則として移行時点でサポートされる最新の安定保守版を候補にします。ただし、社内基盤や利用中のSpring Cloud、データベースドライバー、APMエージェントが4.1系へ対応していない場合は、互換性を確認して判断します。単に最新だから採用するのではなく、アプリ全体の組み合わせがサポートされるかを確認してください。
検証中にバージョンが自動で変わらないよう、親POM、Gradleプラグイン、BOMの指定を確認します。CIと開発端末で異なるJavaやGradle Wrapperを使っていると、同じソースでも結果が変わります。java -version、mvn -version、./gradlew --versionの出力を移行記録へ残します。
移行先を固定するときは、利用開始日だけでなくサポート期間も確認します。4.0系と4.1系がともに保守されていても、組織のリリース時期によっては、検証完了直後に次の更新が必要になる可能性があります。社内のJava更新周期、Spring Bootの保守期間、クラウドやAPM製品の対応予定を並べ、運用期間中に保守される系列を選びます。
ただし、公開前のRC版やSnapshot版を本番移行先にしません。新機能の事前検証と本番採用は分け、安定版の同じ座標で再検証します。検証用リポジトリを追加したままにすると、意図しないプレリリース版が解決されるおそれがあるため、POMやGradle設定から削除します。
2. 実行環境の要件を確認する
2.1 Java・Maven・Gradleの対応範囲をそろえる
Spring Boot 4.1.2はJava 17以上を必要とし、Java 27まで対応しています。公式ドキュメントでは、Maven 3.6.3以上、Gradle 8.14以上の8.xまたは9.xが明示されています。Java 17で起動できることと、現在のアプリがJava 17以上へ対応していることは別なので、アプリ独自コードと利用ライブラリも確認します。
本番がJava 21、開発端末がJava 25、CIがJava 17という状態では、コンパイル対象やテスト結果がずれることがあります。Mavenならmaven.compiler.release、GradleならJava Toolchainsを使い、コンパイル対象を明示します。CIのイメージタグもlatestのような可変値ではなく、検証したJDKの系列を指定してください。
Gradleを利用する場合は、Spring BootだけでなくGradle Wrapperも確認します。プロジェクトにgradlewがあるなら、開発者が各自インストールしたGradleではなくWrapperを使うことで、CIと端末の差を減らせます。独自プラグインや古い静的解析ツールがGradle 9へ未対応なら、まず対応範囲内のGradle 8.14以降で移行し、ビルドツール更新を別作業に分ける判断もあります。
Javaを同時に17から25へ上げる場合も、Spring Boot更新との二段階化を検討します。使用するJava言語機能、GC、TLS、文字コード、タイムゾーンデータなど、JDK更新だけで変わる要素があるためです。先に3.5系を新JDKで動かしてからSpring Bootを更新すれば、JDK由来とフレームワーク由来の問題を分けられます。
2.2 Servlet 6.1と組み込みサーバーを確認する
Spring Boot 4はJakarta EE 11とServlet 6.1を基準とします。公式のシステム要件では、Tomcat 11.0.xとJetty 12.1.xが対応する組み込みServletコンテナとして示されています。WARを外部コンテナへ配備する場合も、Servlet 6.1以上へ対応する環境が必要です。
Spring Boot 4.0では、Servlet 6.1へ対応していないことを理由にUndertowサポートが削除されました。spring-boot-starter-undertowを使うアプリは、バージョン番号を変える前にTomcatまたはJettyへ移行できるか、外部コンテナを利用するかを判断します。サーバー変更では、ポートだけでなく、アクセスログ、最大リクエストサイズ、文字コード、圧縮、TLS終端、プロキシヘッダーの設定も比較します。
Servlet APIを直接利用するフィルター、リスナー、独自サーブレットがある場合は、コンパイル成功だけで完了にしません。ログイン、ファイルアップロード、例外応答、Forwarded Header、セッションなど、サーバー実装やServlet世代の影響を受けやすい経路を結合テストへ含めます。
外部コンテナへWARを配備している場合は、アプリのビルド担当と実行基盤の担当を分けず、同じ対応表を共有します。アプリがServlet 6.1でコンパイルできても、配備先が古いServlet世代なら起動できません。開発環境の組み込みTomcatだけで確認を終えず、実際の配備方式でテストします。
リバースプロキシやロードバランサーの後ろで動くアプリでは、リダイレクトURL、HTTPS判定、クライアントIP、セキュアCookieも確認します。サーバー更新後にアプリ自体は正常でも、プロキシヘッダーの扱いが変わると、ログインループや誤ったURL生成につながる可能性があります。
3. 依存関係の影響範囲を可視化する
3.1 Spring Boot管理内と管理外を分ける
Spring BootのBOMが管理する依存関係は、Bootの更新に伴って対応するバージョンへ変わります。一方、アプリがバージョンを直接指定したライブラリ、社内ライブラリ、Spring Cloudなど別のBOMで管理するライブラリは、Spring Boot 4への互換性を個別に調べる必要があります。
Mavenでは次のコマンドで有効な依存関係と設定を確認できます。
./mvnw dependency:tree
./mvnw help:effective-pomGradleでは、全体の依存関係と特定ライブラリが選ばれた理由を分けて確認します。
./gradlew dependencies
./gradlew dependencyInsight --dependency spring-core出力は移行前後で保存します。バージョンが変わったライブラリを一覧化し、コンパイル時だけ使うもの、実行時に必要なもの、テストだけで使うものへ分類してください。依存関係の本数が多いことよりも、どの経路から入り、誰がバージョンを管理しているかが重要です。
依存差分は、更新された版、消えたライブラリ、新しく追加されたライブラリ、同じ版でも経路が変わったライブラリに分けます。消えたものをすべて元に戻す必要はありません。Spring Boot 4で不要になったものや別モジュールへ統合されたものもあるため、アプリが直接利用しているか、自動構成の条件になっているかを確認します。
脆弱性スキャンの結果も移行前後で比較します。新しい版で既知脆弱性が減ることもあれば、スキャナーのデータベース更新によって件数が増えることもあります。件数だけを比較せず、CVE、到達可能性、利用箇所、修正版の有無を記録してください。
3.2 社内ライブラリとSpring関連製品を先に調べる
社内共通starterや独自の自動構成は、Spring Boot内部のパッケージや条件判定へ依存している場合があります。アプリ本体を更新する前に、そのライブラリがSpring Boot 4へ対応しているかを確認します。対応版がないままアプリ側だけを上げると、ClassNotFoundException、Beanの未登録、設定プロパティの認識漏れなどが起きます。
Spring Cloud、Spring Security、Spring Batch、Spring Dataなども、Spring Bootと無関係に任意の版を組み合わせられるわけではありません。Spring Bootの依存管理表と各プロジェクトのリリースノートを確認し、互換性が明記された組み合わせを選びます。MavenやGradleが依存解決できたことは、その組み合わせの動作保証を意味しません。
移行をブロックするライブラリが見つかったら、先に対応版へ更新する、代替ライブラリへ切り替える、該当機能を一時的に分離するという選択肢を比較します。本番移行日を決めてから互換性調査を始めると、外部ライブラリの対応待ちが予定へ直結するため、棚卸しを最初に行います。
社内ライブラリの所有者が不明な場合は、移行作業の前に保守責任を明確にします。ソースを修正できても、リリース手順、互換性テスト、利用サービスの把握がなければ安全に更新できません。利用箇所をGitHubのコード検索や依存関係台帳で調べ、対応版を先行サービスだけのローカル修正にしないようにします。
4. 削除・非推奨・設定変更を洗い出す
4.1 3.xの非推奨警告を先に減らす
Spring Boot 4では、3.xで非推奨だったクラス、メソッド、設定が削除されることがあります。3.5系でコンパイル警告やIDEの非推奨表示を確認し、4.xへ上げる前に置き換えられるものは先に修正します。これにより、4.xで突然「シンボルが見つからない」となる箇所を減らせます。
コンパイラ警告をすべて同じ優先度で扱う必要はありません。Spring BootやSpring FrameworkのAPI、設定プロパティ、テスト注釈、独自自動構成が使う拡張点を優先します。単に警告を抑制するのではなく、代替APIと動作差を公式Javadocや移行ガイドで確認してください。
修正は、3.5系でも動く互換変更と、4.xでしかコンパイルできない変更に分けます。前者を先に3.5系へ反映すると、差分のレビューと障害時の切り戻しが容易になります。1コミットにJava更新、フレームワーク更新、業務仕様変更を混ぜないことも重要です。
非推奨APIを置き換えるときは、シグネチャが似ている代替を機械的に選ばず、既定値や例外、nullの扱いまで確認します。コンパイルが通る置換でも、呼び出し順や条件判定が変われば実行結果が変わります。該当コードを通る単体テストと結合テストを追加し、置換前後の期待値を固定します。
4.2 廃止機能を設定値だけで復活させない
Spring Boot 4.0の移行ガイドでは、Undertow、Pulsar Reactiveの自動構成、組み込み起動スクリプトなど、削除された機能が明記されています。削除機能は、設定プロパティ名を探しても有効にはなりません。まず「名称が変わった」のか「機能自体が削除された」のかを区別します。
設定プロパティの名称変更や削除については、後続の作業でspring-boot-properties-migratorを利用できます。ただし、migratorは外部ライブラリの互換性や削除されたサーバーを自動で置き換える道具ではありません。起動ログの診断を移行判断へ利用し、最終的には設定ファイルを正式なプロパティへ修正します。
廃止機能を使っている場合は、「同じものを何とか動かす」だけでなく、その機能が担っていた要件を整理します。たとえば実行可能JARの組み込み起動スクリプトなら、必要なのはUnixサービスとしての起動、PID管理、ログ転送のどれかを確認し、コンテナ、systemd、Gradle application pluginなど現在の配備方式に合う代替を選びます。
変更・削除された設定は、環境ごとに確認します。開発用application.ymlだけを直しても、本番の環境変数、Kubernetes ConfigMap、秘密情報管理サービス、起動引数に古い名前が残ることがあります。設定の優先順位を考慮し、最終的にどの値が採用されたかを確認してください。
5. 移行用のテスト基準を作る
5.1 外部仕様と内部実装を分けて確認する
移行テストでは、利用者や連携システムから見える外部仕様を最初に固定します。HTTPステータス、JSONのフィールド名と型、日付表現、エラーレスポンス、認証・認可、メッセージ形式、DB更新結果などです。内部クラスの呼び出し回数だけを確認するテストでは、フレームワーク更新による外部差分を見逃すことがあります。
Spring Boot 4ではJackson 3が標準となるため、JSONのシリアライズ結果やテストの文字列比較に差が出る可能性があります。ただし、この記事ではJackson 3の具体的な修正方法までは扱いません。移行前に代表的なレスポンスを保存し、4.xで同じ入力に対する差を検出できるようにすることが目的です。
全APIを手作業で確認するのではなく、売上、決済、権限変更など影響の大きい経路、利用頻度の高い経路、過去に障害があった経路を優先します。外部サービスとの通信は、タイムアウト、4xx・5xx、空レスポンスも含め、正常系だけで移行完了にしないでください。
定期バッチやメッセージ処理は、HTTP APIとは別の基準が必要です。処理件数、再実行時の重複、トランザクション境界、失敗メッセージの扱いを確認します。起動直後の疎通確認だけでは、深夜バッチや月次処理の問題を検出できないため、代表データを使った実行試験を移行計画へ含めます。
5.2 起動・テスト・実行時の失敗を分ける
失敗は発生段階で分類すると調べやすくなります。コンパイル時なら、削除API、パッケージ変更、Javaバージョンを確認します。起動時なら、依存関係、Bean生成、設定プロパティ、データベース接続を確認します。リクエスト実行時だけ失敗するなら、JSON変換、認証、トランザクション、外部通信など対象経路へ絞ります。
| 発生段階 | 主な症状 | 最初に確認するもの |
|---|---|---|
| 依存解決 | artifactが見つからない、版競合 | BOM、リポジトリ、対応版 |
| コンパイル | package・class・methodが見つからない | 削除API、パッケージ、JDK |
| テスト起動 | ApplicationContextの生成失敗 | test starter、プロファイル、Bean |
| アプリ起動 | 自動構成、設定、接続の失敗 | Conditions、設定差分、依存関係 |
| 実行時 | 特定APIだけ失敗、JSON差分 | 入出力、ログ、例外の根本原因 |
最初の例外だけでなく、スタックトレースのCaused byを最後まで確認します。ApplicationContext failed to startは結果であり、原因はその下にあるクラス不足、設定値、接続失敗などです。移行中に遭遇したエラーと解決方法を記録し、同じ構成を持つ別サービスへ横展開できるようにします。
エラー記録には、メッセージ全文、実行コマンド、対象コミット、JavaとSpring Bootの版、関連する設定、解決確認のテストを含めます。「依存を追加したら直った」だけでは、後から不要依存を判断できません。原因となった前提と、なぜその修正が必要なのかを残してください。
6. 小さく移行して本番へ出す
6.1 一度に変更する範囲を制限する
Spring Boot 4移行と同時に、業務機能追加、DBスキーマ変更、全面的なコード整形、クラウド基盤変更を行うと、不具合の原因を切り分けにくくなります。必要な互換修正と無関係な変更を分け、レビュー可能な単位にします。
現実的には、準備用の変更を先に3.5系へ反映し、その後に4.xへ上げる方法が有効です。たとえば非推奨APIの置換、テストの追加、依存バージョンの整理は3.5系で行えます。その状態を本番で安定させてから、Spring Boot 4固有のstarter再編やJackson 3へ進むと、差分を限定できます。
複数サービスを持つ場合は、業務影響が比較的小さく、テストと監視が整っているサービスを先行対象にします。最も単純なサービスだけを選ぶと、認証やDBなど共通の難所を通らず、後続へ知見を転用できないことがあります。代表性と影響度の両方で選んでください。
先行サービスで得た修正を、そのまま全サービスへ一括適用しないことも大切です。同じSpring Bootでも、Web MVC、バッチ、メッセージング、DBアクセスでは必要なstarterと試験項目が異なります。共通部分はテンプレート化し、サービス固有部分は所有者が確認する二段階にします。
6.2 ロールバック条件を事前に決める
本番反映前に、何が起きたら切り戻すかを決めます。起動失敗だけでなく、5xx率、p95・p99応答時間、認証失敗率、DBエラー、メッセージ滞留、業務上の不整合など、利用者影響へつながる指標を対象にします。
アプリだけを旧版へ戻せるかも確認します。同じリリースでDBスキーマやメッセージ形式を互換性なく変更すると、旧アプリへ戻せません。Spring Boot更新では、可能な限り外部契約とDB形式を維持し、フレームワーク移行とデータ移行を分離してください。
段階リリースが可能なら、一部インスタンスや限定利用者へ4.x版を出し、旧版と比較します。ログ量、メトリクス名、ヘルスチェックの変化も監視対象です。一定時間エラーがないだけで完了とせず、ピーク負荷、バッチ、日次処理など主要な運用周期を通過したことを確認します。
ロールバック手順は文書だけでなく、検証環境で実行します。旧イメージの取得、設定の復元、トラフィック切替、キャッシュやセッションの扱い、切戻し後の確認までにかかる時間を測ります。本番障害時に初めて手順を試すと、権限不足や古い成果物の欠落が見つかる可能性があります。
7. 移行前チェックリストを運用する
7.1 着手前の確認項目
着手前には、次の項目を満たしているか確認します。
- 最新のSpring Boot 3.5系でビルドとテストが成功する
- 移行前のコミットまたはタグを残している
- Java、Maven、Gradle、Servletコンテナの対象版を固定している
- Spring Cloud、Spring Security、社内starterの対応版を確認している
- MavenまたはGradleの依存関係一覧を保存している
- 3.xの非推奨APIと設定を洗い出している
- Undertowなど削除機能の利用有無を確認している
- 主要API、認証、DB更新、バッチの回帰テストがある
- JSONやエラーレスポンスの移行前基準を保存している
- 本番での監視項目とロールバック条件を決めている
チェックを「確認済み」の一語だけで終わらせず、確認したコマンド、公式資料、結果、担当者、日付を残します。ライブラリの対応状況は変わるため、数か月後に実施するサービスでは再確認が必要です。
7.2 完了条件をバージョン更新以外にも置く
pom.xmlで4.1.2になったことは、移行の開始条件であって完了条件ではありません。CIが同じ版で再現でき、主要な外部仕様が維持され、ログと監視が機能し、ロールバック手順が試されて初めて安全な移行といえます。
移行中に一時対応を入れた場合は、削除条件と期限を記録します。互換用のclassic starter、Jackson 2の暫定利用、警告抑制などを残したままにすると、次の更新で再び大きな課題になります。移行完了レビューでは、暫定依存や設定が残っていないかも確認してください。
最後に、遭遇した問題をサービス固有と共通問題へ分けます。共通starter、CIテンプレート、移行チェックリストへ反映できれば、後続サービスの調査量を減らせます。単発のバージョンアップではなく、組織内で繰り返せる移行手順として整えることが重要です。
まとめ
Spring Boot 4への移行は、最新の3.5系で正常な基準を作り、採用する4.xの保守版と実行環境を固定するところから始めます。Java 17以上、Spring Framework 7、Jakarta EE 11、Servlet 6.1、対応するMaven・Gradle・Servletコンテナを確認し、Spring Boot管理外のライブラリや社内starterを先に棚卸ししてください。
移行作業では、非推奨API、削除機能、依存関係、設定、外部仕様、テストを別々に確認します。一度に業務変更やDB変更を混ぜず、3.5系でも実施できる準備を先行させると、4.x固有の問題を絞り込めます。バージョン番号の更新ではなく、同じ条件で再現できるビルド、回帰テスト、段階リリース、ロールバックまでを完了条件にしてください。
