はじめに
Spring Boot 4.0では、3.xで非推奨だったAPIがすべて削除され、スターターの構成も変わりました。そのため、バージョンの数字を上げるだけでは動かないことがあります。
この記事では、Spring Boot 3.5から4.0へ移行するときの破壊的変更を領域ごとに整理し、最後に確認用のチェックリストと、安全に進めるための手順を紹介します。
- 対象読者:Spring Boot 3のアプリを4に上げようとしている方
- 前提バージョン:Spring Boot 4.0 / Java 25
- この記事で分かること:主な破壊的変更、移行のチェックリスト、段階的な進め方
結論
- まず3.5の最新版に上げ、非推奨の警告をすべて解消してから4.0に進める
- 影響が大きいのは「スターター」「テスト」「Jackson 3」「プロパティ名」の4つ
- 移行用の仕組み(classicスターターなど)で、まず動く状態にしてから少しずつ直すと安全
使えなくなったもの
次の機能は、Spring Boot 4で使えなくなりました。
- 組み込みサーバーのUndertow(Servlet 6.1に対応していないため)。TomcatかJettyに切り替える
- 実行可能jarの起動スクリプト。
java -jarで起動する - Spock連携、Spring SessionのHazelcast・MongoDB対応、旧形式のjarローダー
スターターと依存関係
名前が変わったスターター
| Spring Boot 3 | Spring Boot 4 |
|---|---|
| spring-boot-starter-web | spring-boot-starter-webmvc |
| spring-boot-starter-aop | spring-boot-starter-aspectj |
| spring-boot-starter-web-services | spring-boot-starter-webservices |
| spring-boot-starter-oauth2-client | spring-boot-starter-security-oauth2-client |
| spring-boot-starter-oauth2-resource-server | spring-boot-starter-security-oauth2-resource-server |
スターターが必須になったもの
Spring Boot 4では、自動設定が技術ごとのモジュールに分かれ、スターターがそのモジュールを連れてくる仕組みになりました。そのため、ライブラリだけを入れていると自動設定が効かなくなります。
- Flyway:
flyway-coreだけでは、マイグレーションが実行されなくなる。spring-boot-starter-flywayを追加する - RestClient / WebClient:
spring-boot-starter-webmvcには含まれなくなった。spring-boot-starter-restclientなどを追加する
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-webmvc'
implementation 'org.springframework.boot:spring-boot-starter-flyway'
implementation 'org.springframework.boot:spring-boot-starter-restclient'
}
そのほかの依存関係の変更
| 変更 | 対応 |
|---|---|
| war で外部Tomcatに載せる場合 | spring-boot-starter-tomcat を spring-boot-starter-tomcat-runtime に変える |
| @EntityScan の場所 | org.springframework.boot.persistence.autoconfigure から import する |
| Spring Retry | バージョン管理の対象外になった。使い続けるならバージョンを明示する |
テスト
テストは、移行で最も修正箇所が多くなりやすい部分です。
| 変更 | 対応 |
|---|---|
| @MockBean / @SpyBean の削除 | @MockitoBean / @MockitoSpyBean に置き換える |
| @MockitoBean は @Configuration クラスに置けない | テストクラスに置くか、合成アノテーションにまとめる |
| @SpringBootTest がMockMvcを自動設定しない | @AutoConfigureMockMvc を付ける |
| TestRestTemplate が自動で用意されない | RestTestClient(@AutoConfigureRestTestClient)に移る |
| テスト用スターター | 技術ごとの -test スターターを追加する |
置き換えの例です。
// Spring Boot 3
@SpringBootTest
class OrderServiceTest {
@MockBean
PaymentClient paymentClient;
}
// Spring Boot 4
@SpringBootTest
@AutoConfigureMockMvc // MockMvcを使う場合
class OrderServiceTest {
@MockitoBean
PaymentClient paymentClient;
}
@WebMvcTest などのテスト用アノテーションも、パッケージが変わっています。import文の修正が必要です。
Jackson 3
JSON処理のライブラリがJackson 3になり、パッケージ名や既定値が変わりました。
| 変更 | 内容 |
|---|---|
| パッケージ | com.fasterxml.jackson から tools.jackson へ(アノテーションは除く) |
| enumの変換 | toString() の戻り値が使われる |
| 項目の順番 | アルファベット順になる |
| 基本型へのnull | int などにnullが来るとエラーになる |
| Boot側のクラス | @JsonComponent は @JacksonComponent に変わった |
| プロパティ | spring.jackson.read.* は spring.jackson.json.read.* に変わった |
自分で ObjectMapper のBeanを定義している場合、Spring Boot 4では効かなくなります。JsonMapper のBeanとして定義し直します。
すぐに既定値を変えられない場合は、次の設定でJackson 2に近い動きにできます。
spring:
jackson:
use-jackson2-defaults: true
プロパティ名と既定値
名前が変わったプロパティは、エラーにならず黙って無視されます。気づきにくいので注意が必要です。
| Spring Boot 3 | Spring Boot 4 |
|---|---|
| spring.session.redis.* | spring.session.data.redis.* |
| spring.data.mongodb.host など | spring.mongodb.* |
| spring.dao.exceptiontranslation.enabled | spring.persistence.exceptiontranslation.enabled |
| management.tracing.enabled | management.tracing.export.enabled |
既定値が変わったものもあります。
- ヘルスチェックの liveness / readiness が、Kubernetes以外でも既定で有効になった
- DevToolsのLiveReloadが既定で無効になった
- Logbackのログファイルの文字コードが既定でUTF-8になった
移行中は、次の依存を一時的に入れておくと、古いプロパティ名を起動時に警告してくれます。
runtimeOnly 'org.springframework.boot:spring-boot-properties-migrator'
Spring Batch
spring-boot-starter-batch は、メモリ上で動くようになり、ジョブの実行履歴をDBに保存しなくなりました。
失敗したステップからの再開や、二重実行の防止など、DBの実行履歴を使う制御が必要な場合は、spring-boot-starter-batch-jdbc に切り替えます。そのまま上げると、履歴が残らないことに気づかないまま本番に出てしまうので、特に注意が必要です。
パッケージやAPIの移動
| 対象 | 変更 |
|---|---|
| ヘルスチェック | org.springframework.boot.actuate.health から org.springframework.boot.health.contributor へ |
| EnvironmentPostProcessor | org.springframework.boot.env から org.springframework.boot へ |
| HttpMessageConverters | 非推奨。ServerHttpMessageConvertersCustomizer などを使う |
自作の HealthIndicator がある場合は、importを変え、spring-boot-health の依存を追加します。
このほか、Spring Security 7やHibernate 7への更新に伴う変更もあります。Spring Securityを使っている場合は、Spring Security側の移行ガイドも確認してください。
移行チェックリスト
移行のときに確認する項目です。
- 3.5の最新版で、非推奨の警告をすべて解消した
- spring-boot-starter-web を spring-boot-starter-webmvc に変えた
- Flywayなど、ライブラリだけで入れていたものにスターターを追加した
- RestClient / WebClient のスターターを追加した
- @MockBean / @SpyBean を @MockitoBean / @MockitoSpyBean に置き換えた
- MockMvcを使うテストに @AutoConfigureMockMvc を付けた
- テスト用スターターを追加し、テスト用アノテーションのimportを直した
- JSONを文字列で比べるテストを、項目の順番に左右されない書き方にした
- spring.jackson.* などの名前が変わったプロパティを直した
- 自作の HealthIndicator のimportを直した
- Spring Batchを使っている場合、spring-boot-starter-batch-jdbc に切り替えた
- Spring Securityの移行ガイドを確認した
安全に進める手順
一度にすべてを直そうとすると、どこで壊れたのか分からなくなります。次の順で少しずつ進めるのがおすすめです。
- 移行用の仕組みを入れて、まず動く状態にする
- テストを通しながら、技術ごとのスターターに置き換える
- Jackson 3の既定値に切り替える
- 最後に、移行用の依存と設定を外す
手順1で使う移行用の仕組みは次のとおりです。
dependencies {
// すべての自動設定モジュールをまとめて入れる(一時的な橋渡し)
implementation 'org.springframework.boot:spring-boot-starter-classic'
testImplementation 'org.springframework.boot:spring-boot-starter-test-classic'
// 古いプロパティ名を警告する
runtimeOnly 'org.springframework.boot:spring-boot-properties-migrator'
}
spring:
jackson:
use-jackson2-defaults: true # Jackson 2に近い既定値で動かす
classicスターターは非推奨で、将来削除される予定です。あくまで移行中の一時的な手段として使い、手順2で技術ごとのスターターに置き換えます。
まとめ
- 移行は、3.5の最新版で非推奨の警告を解消してから始める
- スターター名の変更と、スターターが必須になったもの(Flyway、RestClientなど)に注意する
- テストは @MockBean の削除と、@SpringBootTest がMockMvcを自動設定しなくなった点を確認する
- Jackson 3の既定値の変更と、名前が変わったプロパティは、エラーにならずに動きが変わるので特に注意する
- Spring Batchは spring-boot-starter-batch-jdbc に切り替えないと、実行履歴がDBに残らない
- classicスターターなどの移行用の仕組みで、まず動く状態にしてから少しずつ直す
関連記事
破壊的変更は多く見えますが、1つずつ見ると機械的に直せるものがほとんどです。チェックリストを使いながら、段階的に進めてみてください。