1
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?

@narunaru-uhchan

Spring Boot 4.0 で新規プロジェクトを作る際の3つの落とし穴：テスト・Flyway・JPA設定

1
Posted at

はじめに

対象読者: 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では、テスト関連のパッケージ構成が大幅に変更されました：

  1. テストアノテーションのパッケージ移動
  2. @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 に置き換えられた（より明示的なネーミング）
  • テスト用の細分化されたスターター依存関係が提供されている

参考資料:

問題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

起動時の処理順序：

  1. Hibernate がスキーマ検証を実行（ddl-auto: validate）
  2. テーブルが存在しない → 検証エラーで起動失敗
  3. 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 に修正してアプリケーションは正常に起動するようになったものの：

  1. Flywayのログが全く出力されない
  2. flyway_schema_history テーブルが作成されない
  3. マイグレーションファイル（V1__create_bakens_table.sql）が実行されない
  4. アプリケーションを動かした時に 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の自動設定を正しく活用できる

参考資料

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

1
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
Sign upLogin
1
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?