Spring Boot 2.7から3.0への段階的マイグレーション完全ガイド

2026年6月24日

Contents

1 移行計画の全体像と段階的マイグレーション戦略
- 1.1 フェーズ別チェックリスト
2 基盤環境の更新（Java バージョン・ビルドツール・依存関係）
3 コードレベルの変更ポイント
4 テスト・デプロイ環境と実践的トラブルシューティング
5 次のアクション：チェックリスト PDF のダウンロードとサンプルプロジェクト検証

スポンサードリンク

移行計画の全体像と段階的マイグレーション戦略

Spring Boot 2.7 から 3.0 への移行は、「事前準備 → コード修正 → ビルド更新 → 検証・デプロイ」 の4つのフェーズに分けて実施すると安全です。各フェーズで成果物を確実に確認しながら進めることで、リグレッションや大規模ロールバックのリスクを最小限に抑えられます。本節では、全体像と具体的な作業項目を表形式で示します。

フェーズ別チェックリスト

フェーズ	主な作業内容	推奨ツール・資料
事前準備	JDK 17/21 の導入、IDE 設定の更新、CI 環境の Java バージョン統一	OpenJDK 17 LTS／Oracle JDK 21、IntelliJ IDEA / Eclipse
コード修正	`javax → jakarta` 名前空間置換、Security の API 書き換え、AutoConfiguration の移行	`jakarta-transformer`、Spring Migration Guide
ビルド更新	Gradle 7.5+／Maven 3.9+ へのアップデート、プラグインバージョン指定変更	`spring-boot-gradle-plugin` v3.x、`spring-boot-maven-plugin` v3.x
検証・デプロイ	JUnit5 移行、Docker イメージ更新、Native Image ビルド確認	`eclipse-temurin:21-alpine`、Spring Native 1.0

ポイント：各フェーズの完了時に必ず成果物（ビルド結果やテストレポート）を保存し、次工程へ進む前にレビューすることが重要です。

基盤環境の更新（Java バージョン・ビルドツール・依存関係）

Spring Boot 3.0 は Java 17 以上 を必須とし、JDK 21 も完全サポートしています。まずは JDK の入れ替え、続いて Gradle／Maven のバージョン統一、そして主要スターターのバージョン合わせを行います。本節ではそれぞれの手順と注意点を詳述します。

JDK 17/21 のインストールと IDE 設定

JDK を新バージョンに置き換える作業は、環境全体の互換性確保の第一歩です。以下の手順で導入してください。

公式サイトからダウンロード
OpenJDK 17 LTS（Adoptium）または Oracle JDK 21 を取得します。
環境変数を設定
bash export JAVA_HOME=/path/to/jdk-17 export PATH=$JAVA_HOME/bin:$PATH
IDE のプロジェクト SDK を更新
IntelliJ IDEA: Project Structure → Project で「Project SDK」を新しい JDK に変更。
Eclipse: Preferences → Java → Installed JREs に追加し、デフォルトに設定。

理由：Spring Boot 3.0 はモジュールシステムと record・sealed といった最新言語機能を前提に設計されているため、古い JDK ではコンパイルエラーが頻発します。

Gradle と Maven のバージョン要件とプラグイン設定

ビルドツールのバージョンが古いと Spring Boot 3.0 が提供する自動構成やデフォルト依存関係を正しく解決できません。ここでは推奨される最小バージョンと、実務で安定している組み合わせを示します。

Gradle の設定例（Kotlin DSL）

plugins {
    id(&quot;org.springframework.boot&quot;) version &quot;3.0.8&quot;
    kotlin(&quot;jvm&quot;) version &quot;1.9.10&quot; // Kotlin を使用する場合のみ
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17)) // JDK 17 を明示
    }
}

plugins {

id("org.springframework.boot") version "3.0.8"

kotlin("jvm") version "1.9.10" // Kotlin を使用する場合のみ

}

java {

toolchain {

languageVersion.set(JavaLanguageVersion.of(17)) // JDK 17 を明示

}

最低バージョン：7.5
実務推奨：7.6.1（プラグイン互換性が高く、CI 環境でも安定）

Maven の設定例

&lt;properties&gt;
    &lt;java.version&gt;17&lt;/java.version&gt;
    &lt;spring.boot.version&gt;3.0.8&lt;/spring.boot.version&gt;
&lt;/properties&gt;

&lt;dependencyManagement&gt;
    &lt;dependencies&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
            &lt;artifactId&gt;spring-boot-dependencies&lt;/artifactId&gt;
            &lt;version&gt;${spring.boot.version}&lt;/version&gt;
            &lt;type&gt;pom&lt;/type&gt;
            &lt;scope&gt;import&lt;/scope&gt;
        &lt;/dependency&gt;
    &lt;/dependencies&gt;
&lt;/dependencyManagement&gt;

&lt;build&gt;
    &lt;plugins&gt;
        &lt;plugin&gt;
            &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
            &lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
            &lt;version&gt;${spring.boot.version}&lt;/version&gt;
        &lt;/plugin&gt;
    &lt;/plugins&gt;
&lt;/build&gt;

<java.version>17</java.version>

<spring.boot.version>3.0.8</spring.boot.version>

</properties>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-dependencies</artifactId>

<version>${spring.boot.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<build>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

<version>${spring.boot.version}</version>

</plugin>

</plugins>

</build>

最低バージョン：3.9
実務推奨：3.9.5 以上（依存解決の改善が含まれる）

主要スターターの一括更新と互換性表

Spring Boot の BOM (spring-boot-dependencies) を利用すれば、バージョン衝突を防ぎつつ一括管理できます。以下は 2.7 系から 3.0 系へ移行する際に推奨されるスターターのバージョンです。

スターター	移行前（2.7 系）	推奨バージョン（3.0 系）
`spring-boot-starter-web`	2.7.x	3.0.8
`spring-boot-starter-data-jpa`	2.7.x	3.0.8
`spring-boot-starter-actuator`	2.7.x	3.0.8
`spring-boot-starter-security`	2.7.x	3.0.8
`spring-boot-starter-test`	2.7.x	3.0.8

互換性チェックポイント

Spring Data JPA：リポジトリインターフェースのシグネチャは変更なし。JpaRepository はそのまま使用可能です。
Actuator：エンドポイントパスは従来通り /actuator/** ですが、デフォルトで非推奨となっていた設定項目が削除されています。公式互換性表を確認し、必要に応じて management.endpoint.* のプロパティを追加してください。
Spring Security：WebSecurityConfigurerAdapter が廃止されたため、必ず SecurityFilterChain Bean に置き換えることが必須です。

まとめ：JDK とビルドツールの統一は移行作業の土台となります。BOM で依存関係を管理し、互換性表に基づくバージョン揃えを徹底してください。

コードレベルの変更ポイント

Spring Boot 3.0 では Jakarta EE 名称空間への全面移行と、Security・AutoConfiguration の API 改変が中心となります。本節では自動化ツールと手作業で対応すべき箇所を段階的に解説します。

`javax → jakarta` 名前空間置換ツールと手動修正

jakarta-transformer は javax.* を一括で jakarta.* に変換できる便利な CLI ツールです。以下のコマンドでソースコード全体を対象に実行できます。

java -jar jakarta-transformer.jar \
    --source src/main/java \
    --target src/main/java-transformed

java -jar jakarta-transformer.jar \

--source src/main/java \

--target src/main/java-transformed

注意：自動変換だけではリフレクションや文字列ベースの API 呼び出しは置換されません。変換後に grep -R "javax\." で残存箇所を検索し、手作業で修正してください。

手動で確認すべき代表的なパッケージ

パッケージ	変更前例	変更後例
Servlet API	`javax.servlet.http.HttpServletRequest`	`jakarta.servlet.http.HttpServletRequest`
JPA アノテーション	`javax.persistence.Entity`	`jakarta.persistence.Entity`
WebSocket	`javax.websocket.OnMessage`	`jakarta.websocket.OnMessage`

Spring Security のリファクタリング（SecurityFilterChain への移行）

Spring Boot 3.0 では WebSecurityConfigurerAdapter が削除され、代わりに SecurityFilterChain Bean を定義する方式が推奨されています。以下は最小構成のサンプルです。

@Configuration(proxyBeanMethods = false)
public class SecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -&gt; csrf.disable())
            .authorizeHttpRequests(auth -&gt;
                auth.requestMatchers(&quot;/admin/**&quot;).hasRole(&quot;ADMIN&quot;)
                    .anyRequest().permitAll()
            )
            .httpBasic(Customizer.withDefaults())
            .build();
    }
}

@Configuration(proxyBeanMethods = false)

public class SecurityConfig {

@Bean

SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {

return http

.csrf(csrf -> csrf.disable())

.authorizeHttpRequests(auth ->

auth.requestMatchers("/admin/**").hasRole("ADMIN")

.anyRequest().permitAll()

)

.httpBasic(Customizer.withDefaults())

.build();

}

requestMatchers が新しい URL パターン指定メソッドです。
@EnableWebSecurity は不要となり、proxyBeanMethods = false にすることで起動時のコンテキスト負荷が軽減します。

`spring.factories` 廃止と `AutoConfiguration.imports` への移行手順

Spring Boot 3.0 では自動構成情報を META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports に集約します。以下のステップで置き換えてください。

ファイル作成
src/main/resources/META-INF/spring/ └─ org.springframework.boot.autoconfigure.AutoConfiguration.imports
自動構成クラス名を列挙（改行区切り）

text com.example.autoconfig.MyFeatureAutoConfiguration org.springframework.boot.actuate.autoconfigure.metrics.MetricsAutoConfiguration

既存の spring.factories が残っている場合は削除し、ビルド後に警告が出ないことを確認します。

ポイント：テストコードで @ImportAutoConfiguration を使用している場合も同様にインポート先を書き換える必要があります。

Web MVC / WebFlux の URL マッチング変更と `PathPatternParser` 対策

Spring Boot 3.0 ではデフォルトのパスマッチャが PathPatternParser に切り替わります。この変更により Ant パターンとの微妙な挙動差が顕在化します。

デフォルト設定を明示的に有効化する例

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        // PathPatternParser を明示的に使用（デフォルト true）
        configurer.setPatternParser(new PathPatternParser());
    }
}

@Configuration

public class WebConfig implements WebMvcConfigurer {

@Override

public void configurePathMatch(PathMatchConfigurer configurer) {

// PathPatternParser を明示的に使用（デフォルト true）

configurer.setPatternParser(new PathPatternParser());

}

レガシーモードでの一時回避策

高度な正規表現や * の多重マッチングが必要な場合は、以下の設定で Ant パターン互換モードに切り替えられます。

configurer.setUseRegisteredSuffixPatternMatch(true);

1 2	configurer.setUseRegisteredSuffixPatternMatch(true);

注意：レガシーモードは将来的に削除される可能性があるため、根本的なパス設計の見直しを推奨します。

テスト・デプロイ環境と実践的トラブルシューティング

コード変更後はテストフレームワークとコンテナ環境の整合性を確認することが重要です。本節では JUnit5 の設定例、Docker イメージ更新手順、そして頻出エラーへの対処法をまとめます。

JUnit5 と MockMvc の互換性確認

Spring Boot 3.0 はデフォルトで JUnit 5（Jupiter）を使用します。spring-boot-starter-test を最新版に更新すれば、以下のようにシンプルなテストが記述できます。

@ExtendWith(SpringExtension.class)
@SpringBootTest
@AutoConfigureMockMvc
class SampleControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void helloReturns200() throws Exception {
        mockMvc.perform(get(&quot;/hello&quot;))
               .andExpect(status().isOk());
    }
}

@ExtendWith(SpringExtension.class)

@SpringBootTest

@AutoConfigureMockMvc

class SampleControllerTest {

@Autowired

private MockMvc mockMvc;

@Test

void helloReturns200() throws Exception {

mockMvc.perform(get("/hello"))

.andExpect(status().isOk());

}

@RunWith(SpringRunner.class) は JUnit 4 のアノテーションであり、使用できません。必ず @ExtendWith に置き換えてください。
MockMvc の取得方法は従来通り WebApplicationContext からでも問題ありませんが、@AutoConfigureMockMvc を付与すれば自動注入されます。

Docker イメージ更新と Native Image 対応チェックリスト

Spring Boot 3.0 は JDK 17/21 のベースイメージを推奨しています。以下はマルチステージビルドの典型例です（eclipse-temurin:21-alpine を使用）。

# ---------- Build stage ----------
FROM eclipse-temurin:21-alpine AS build
WORKDIR /app
COPY . .
RUN ./gradlew bootJar --no-daemon

# ---------- Runtime stage ----------
FROM eclipse-temurin:21-alpine
EXPOSE 8080
COPY --from=build /app/build/libs/*.jar app.jar
ENTRYPOINT [&quot;java&quot;,&quot;-jar&quot;,&quot;/app.jar&quot;]

# ---------- Build stage ----------

FROM eclipse-temurin:21-alpine AS build

WORKDIR /app

COPY . .

RUN ./gradlew bootJar --no-daemon

# ---------- Runtime stage ----------

FROM eclipse-temurin:21-alpine

EXPOSE 8080

COPY --from=build /app/build/libs/*.jar app.jar

ENTRYPOINT ["java","-jar","/app.jar"]

Spring Native（Native Image）チェックリスト

org.springframework.experimental:spring-native を 3.0.x 系に合わせて追加。
ビルド時は GraalVM 22.3+ をインストールし、Gradle の nativeCompile タスクを有効化。
必要なリフレクション設定 (reflect-config.json) とリソース設定が欠如していないか、--report-unsupported-elements-at-runtime オプションで実行時に検証。

ポイント：Dockerfile のベースイメージは OS と JDK バージョンの組み合わせが CI パイプラインと一致するよう管理し、ローカル環境との差分を最小化してください。

典型的なコンパイル／起動エラー例と対処法

エラー	主な原因	推奨対策
`ClassNotFoundException: jakarta.servlet.Filter`	JDK が 11 のままで `jakarta.*` クラスが存在しない	JDK 17+ に切り替え、IDE とビルドツールの Java バージョンを統一
`IllegalStateException: Cannot resolve configuration property 'spring.datasource.url'`	`application.yml` のプロパティ名が旧形式（`datasource.*`）のまま	プロパティ名を `spring.datasource.*` に修正し、`@ConfigurationProperties` のバインド対象クラスも更新
`Failed to instantiate [org.springframework.boot.autoconfigure.security.servlet.SecurityFilterChain]`	`WebSecurityConfigurerAdapter` が残存しているか、Bean 定義が二重になっている	すべての `extend WebSecurityConfigurerAdapter` クラスを削除し、`SecurityFilterChain` Bean に置き換える

デバッグ手順（共通フロー）

スタックトレース上位のクラス を確認し、欠損パッケージやクラス名を特定。
依存ツリーの検査：./gradlew dependencies --configuration runtimeClasspath または mvn dependency:tree -Dverbose で重複バージョンを洗い出す。
IDE キャッシュのクリア とフルリビルド（IntelliJ の場合 File → Invalidate Caches / Restart）。
問題が解決しない場合は、最小構成のサンプルプロジェクトで同様の設定を再現し、差分を比較する。

まとめ：JUnit5 と Docker 更新は比較的シンプルですが、javax → jakarta 置換に起因する ClassNotFoundException が最頻出です。エラーメッセージを手掛かりに JDK・依存関係の整合性を点検し、必要ならばビルドツールのキャッシュも削除してください。

次のアクション：チェックリスト PDF のダウンロードとサンプルプロジェクト検証

本記事で提示した段階的マイグレーション手順は PDF 形式のチェックリスト としてまとめました。実務に即座に適用できるよう、以下のアクションを推奨します。

PDF チェックリストを入手
社内ポータルまたは担当者から配布されるリンクをクリックし、最新版（2024‑2026 年版）をダウンロードしてください。
サンプルプロジェクトをクローン
bash git clone https://github.com/example/spring-boot-migration-sample.git cd spring-boot-migration-sample
README.md に各フェーズごとの実行手順が記載されています。
ローカル環境で検証
JDK 21、Gradle 7.6.1、Spring Boot 3.0.8 をインストールした状態で ./gradlew clean build を実行し、テストがすべて成功することを確認します。
CI パイプラインへ反映
GitHub Actions または Jenkins のビルド定義に、上記の Dockerfile と Native Image ビルドタスクを組み込み、マージ時に自動検証が走るよう設定してください。

注意点：PDF とサンプルプロジェクトは随時更新されます。リポジトリの release ブランチを定期的にチェックし、最新バージョンへの置き換えを忘れないようにしましょう。

本稿は 2024‑2026 年間に収集されたベストプラクティスと公式ガイドラインを統合しています。読者のプロジェクト規模や使用技術スタックに合わせて、適宜カスタマイズして活用してください。