0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【Spring Boot 4】Spring Boot 3.5から4.0への移行:破壊的変更とチェックリスト

0
Last updated at Posted at 2026-11-22

はじめに

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の移行ガイドを確認した

安全に進める手順

一度にすべてを直そうとすると、どこで壊れたのか分からなくなります。次の順で少しずつ進めるのがおすすめです。

  1. 移行用の仕組みを入れて、まず動く状態にする
  2. テストを通しながら、技術ごとのスターターに置き換える
  3. Jackson 3の既定値に切り替える
  4. 最後に、移行用の依存と設定を外す

手順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つずつ見ると機械的に直せるものがほとんどです。チェックリストを使いながら、段階的に進めてみてください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?