はじめに

対象読者: Spring Boot 4.0 で新規プロジェクトを作成する開発者、または 3.x から 4.0 へ移行する開発者

Spring Boot 4.0 で新規プロジェクトを立ち上げた際、テスト実行とFlyway関連の設定で予想外のトラブルに遭遇しました。

本記事で扱う問題は以下の2種類です：

Spring Boot 4.0で変更された仕様（テスト関連のパッケージ構成）
今回遭遇したFlywayとJPA設定の問題（3.x系でも発生すると思われる）

実際に遭遇した問題とその解決策を共有します。

環境

Spring Boot: 4.0.2
Java: 25
Flyway: 11.x
PostgreSQL: 16
ビルドツール: Maven
IDE: IntelliJ IDEA

問題1: テストが実行できない - パッケージ構成の変更

遭遇したエラー

テストコードで以下のようなインポートエラー：

import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.mock.mockito.MockBean;

原因

Spring Boot 4.0では、テスト関連のパッケージ構成が大幅に変更されました：

テストアノテーションのパッケージ移動
@MockBean の廃止

解決策

依存関係の修正

<!-- pom.xml -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc-test</artifactId>
    <scope>test</scope>
</dependency>

インポートの変更

Before (Spring Boot 3.x):

import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;

After (Spring Boot 4.0):

import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.test.context.bean.override.mockito.MockitoBean;

アノテーションの変更

Before (Spring Boot 3.x):

@WebMvcTest(BakenController.class)
@AutoConfigureMockMvc
class BakenControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private BakenApplicationService bakenApplicationService;

    @Test
    void testGetBakens() throws Exception {
        // テストロジック
    }
}

After (Spring Boot 4.0):

@WebMvcTest(BakenController.class)
@AutoConfigureMockMvc
class BakenControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private BakenApplicationService bakenApplicationService;

    @Test
    void testGetBakens() throws Exception {
        // テストロジック（変更なし）
    }
}

学び

Spring Boot 4.0 では、WebMVC関連のテストパッケージが boot.test.autoconfigure.* から boot.webmvc.test.autoconfigure.* に移動
@MockBean は廃止され、@MockitoBean に置き換えられた（より明示的なネーミング）
テスト用の細分化されたスターター依存関係が提供されている

参考資料:

Spring Boot 4.0 Migration Guide - Module Dependencies（公式）
Spring Boot 4.0でテスト周りが変わった話（Zenn）

問題2: ddl-auto=validate による初回起動エラー

注: 今回はSpring Boot 4.0の新規プロジェクトで遭遇しました。3.x系でも同様に発生する可能性がありますが、未検証です。

遭遇したエラー

アプリケーション起動時に以下のエラーが発生：

org.springframework.beans.factory.BeanCreationException:
Error creating bean with name 'entityManagerFactory'
...
nested exception is org.hibernate.tool.schema.spi.SchemaManagementException:
Schema validation: missing table [bakens]

原因

実行順序の問題

spring:
  jpa:
    hibernate:
      ddl-auto: validate  # ← ここが問題
  flyway:
    enabled: true

起動時の処理順序：

Hibernate がスキーマ検証を実行（ddl-auto: validate）
テーブルが存在しない → 検証エラーで起動失敗
Flyway の実行まで到達しない（起動が失敗しているため）

解決策

Flywayにスキーマ管理を完全に委任：

spring:
  jpa:
    hibernate:
      ddl-auto: none  # validate → none
    show-sql: true
  flyway:
    enabled: true
    baseline-on-migrate: true
    locations: classpath:db/migration
    validate-on-migrate: true

ddl-auto の選択肢と動作

設定値	動作
`none`	Hibernateはスキーマに対して何もしない。テーブルの作成・更新・削除は行わない。
`validate`	起動時にエンティティとDBスキーマの整合性を検証する。不整合があればエラーで起動失敗。スキーマの変更は行わない。
`update`	起動時にエンティティに合わせてスキーマを更新する。テーブルやカラムの追加は行うが、削除は行わない。
`create`	起動時に既存のスキーマを削除し、エンティティから新規作成する。データは全て失われる。
`create-drop`	起動時に`create`と同じ動作をし、アプリケーション終了時にスキーマを削除する。

参考: Spring Data JPAのddl-auto設定について - Qiita

学び

Flywayを使う場合、ddl-auto: none が正解
validate は「既にテーブルが存在する」ことを前提とする
初回起動時は none にしないと、Flywayの実行前に検証エラーで停止する

問題3: Flywayが全く実行されない

注: 今回はSpring Boot 4.0の新規プロジェクトで遭遇しました。3.x系でも同様に発生する可能性がありますが、未検証です。

遭遇した問題

ddl-auto: none に修正してアプリケーションは正常に起動するようになったものの：

Flywayのログが全く出力されない
flyway_schema_history テーブルが作成されない
マイグレーションファイル（V1__create_bakens_table.sql）が実行されない
アプリケーションを動かした時に ERROR: relation "bakens" does not exist エラー

設定は正しいのに動かない

# application.yml
spring:
  flyway:
    enabled: true
    baseline-on-migrate: true

マイグレーションファイルも正しく配置：

backend/src/main/resources/db/migration/
└── V1__create_bakens_table.sql

原因

Spring Boot では flyway-core だけでは自動設定が動作しない

Flyway統合を使うには spring-boot-starter-flyway が必要です。flyway-core だけでは FlywayAutoConfiguration が動作しません。

<!-- これだけでは動かない -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

解決策

spring-boot-starter-flyway を使用する：

<!-- Before: Spring Boot 3.x -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

<!-- After: Spring Boot 4.0 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-flyway</artifactId>
</dependency>

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

検証方法

起動ログで以下のメッセージが表示されることを確認：

Flyway Community Edition 11.x.x by Redgate
Creating Schema History table "public"."flyway_schema_history" ...
Current version of schema "public": << Empty Schema >>
Migrating schema "public" to version "1 - create bakens table"
Successfully applied 1 migration to schema "public"

学び

Spring Boot 4.0 では、Flyway統合に starterパッケージが必須
flyway-core のみでは FlywayAutoConfiguration が動作しない
デバッグログ（--debug）を有効にすると、自動設定の動作状況を確認できる

参考: Flywayを導入する（SpringBoot + Maven） - Qiita

おわりに

本記事で扱った問題を振り返ると：

問題1: テスト関連のパッケージ構成変更（Spring Boot 4.0で変更された仕様）
問題2・3: Flyway・JPA設定の問題（3.x系でも発生すると思われる）

特に厄介だったのは、エラーメッセージだけでは原因が分かりにくいケースです。例えばFlywayが「静かに失敗」する問題は、デバッグログ（--debug）を有効にして初めて原因が見えました。

本記事が同じ問題に遭遇した方の助けになれば幸いです。

教訓:

メジャーバージョンアップ時は、公式の移行ガイドを必ず確認する
Spring Boot 4.0 は 3.x系からの「アップグレード」だけでなく、「新規プロジェクト」でも注意が必要
エラーが出ない場合は、デバッグログ（--debug）を有効にすると原因が見えやすい
Starter依存関係を使うことで、Spring Bootの自動設定を正しく活用できる

参考資料

本記事の執筆にあたり、以下の資料を参考にしました。