Spring Boot 2→3 移行ガイド：段階的アップデートと Jakarta EE 対応

2026年6月7日

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

Contents

1 全体像と移行戦略
2 前提条件と環境統一
- 2.1 Java バージョンの選定と設定
- 2.2 ビルドツール別設定例
  - 2.2.1 Maven 用共通プロパティ（pom.xml）
  - 2.2.2 Gradle (Kotlin DSL) 用設定例
3 段階的アップグレード手順
- 3.1 2.5 → 2.7：マイナーバージョンで安全に移行
- 3.2 2.7 → 3.x：本格的ブレークチェンジ
  - 3.2.1 依存ライブラリ更新チェックリスト（抜粋）
4 主要なコード・設定変更ポイント
5 テスト・CI パイプラインでの検証フロー
- 5.1 CI 設計例（GitHub Actions）
  - 5.1.1 典型的なエラーパターンと対処法
6 実務ベストプラクティスまとめ
7 参考文献

スポンサードリンク

全体像と移行戦略

Spring Boot 2 系から 3 系へのアップグレードは、単なるバージョン上げではなく Java 17 以上 と Jakarta EE 9+ への全面的な置換が必須になる大規模なブレークチェンジです。本セクションでは、全体像と推奨する段階的移行ステップを概観します。

結論：まずプロジェクト全体で Java 17（もしくは LTS の Java 21） を統一し、
2.5 → 2.7 → 3.x の三段階でバージョンアップするのが最も安全です。
背景：マイナーバージョンごとの変更点は互換性が高く、障害切り分けやロールバックが容易になるためです。
期待効果：段階的に実施すれば、依存ライブラリの非推奨警告削減・Jakarta 変換作業の抜け漏れ防止が実証されています[³]。

前提条件と環境統一

この章では Java のバージョン選定 と ビルドツール別設定 を中心に、開発環境・CI 環境をいかに統一するかを解説します。環境がばらついていると Jakarta パッケージ置換時に大量のコンパイルエラーが発生しやすく、移行作業全体のコストが急増します。

Java バージョンの選定と設定

Spring Boot 3 系は 最低 Java 17、推奨は Java 21（LTS） です。以下に JDK の取得から IDE 設定までの標準手順を示します。

JDK の入手
AdoptOpenJDK / Eclipse Temurin / Azul Zulu 等、LTS 版を公式サイトからダウンロード。
JAVA_HOME を JDK ディレクトリに設定し、PATH に $JAVA_HOME/bin を追加。
IDE の統一（IntelliJ IDEA と Eclipse の例）
IntelliJ：File → Project Structure → Project SDK で 17 または 21 を選択。
Eclipse：Preferences > Java > Installed JREs に同様の JDK を登録し、プロジェクトの Execution environment を JavaSE-17（または JavaSE-21）に合わせる。

確認ポイント：ターミナルで java -version が openjdk 17.x 以上であることを必ずチェックしてください。

ビルドツール別設定例

Maven 用共通プロパティ（`pom.xml`）

&lt;properties&gt;
    &lt;!-- Java バージョンはここで一元管理 --&gt;
    &lt;java.version&gt;17&lt;/java.version&gt;
    &lt;spring-boot.version&gt;3.2.0&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;!-- Maven Compiler Plugin で Java バージョンを固定 --&gt;
        &lt;plugin&gt;
            &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
            &lt;configuration&gt;
                &lt;release&gt;${java.version}&lt;/release&gt;
            &lt;/configuration&gt;
        &lt;/plugin&gt;
    &lt;/plugins&gt;
&lt;/build&gt;

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

<spring-boot.version>3.2.0</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>

<artifactId>maven-compiler-plugin</artifactId>

<release>${java.version}</release>

</configuration>

</plugin>

</plugins>

</build>

Gradle (Kotlin DSL) 用設定例

plugins {
    id(&quot;org.springframework.boot&quot;) version &quot;3.2.0&quot;
    kotlin(&quot;jvm&quot;) version &quot;1.9.10&quot;
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

// Spring Boot 依存管理のインポート
dependencyManagement {
    imports {
        mavenBom(&quot;org.springframework.boot:spring-boot-dependencies:3.2.0&quot;)
    }
}

plugins {

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

kotlin("jvm") version "1.9.10"

}

java {

toolchain {

languageVersion.set(JavaLanguageVersion.of(17))

}

// Spring Boot 依存管理のインポート

dependencyManagement {

imports {

mavenBom("org.springframework.boot:spring-boot-dependencies:3.2.0")

}

要点：java.version（Maven）または toolchain.languageVersion（Gradle）を プロジェクト全体で統一 することで、後続の Jakarta 移行作業が確実に適用されます。

段階的アップグレード手順

マイナーバージョンごとに段階的に上げることで、リスクを分散しつつ 問題点の早期発見 が可能です。ここでは各フェーズのチェックポイントと推奨作業を示します。

2.5 → 2.7：マイナーバージョンで安全に移行

この段階はコード変更がほぼ不要な「バージョンだけ上げる」ステップです。主な利点は 開発ツールの改善 と 依存ライブラリの非推奨警告削減 です。

作業項目	内容
バージョン変更	`pom.xml` または `build.gradle.kts` の Spring Boot バージョンを `2.7.x` に更新
ビルド・テスト実行	`./mvnw clean verify`（Maven）／`./gradlew clean test`（Gradle）でエラーが無いことを確認
依存ライブラリのアップデート	Spring Cloud `2023.0.x`、Spring Data JPA `2.7.x` 等、同時に LTS バージョンへ合わせる

ポイント：このフェーズで問題がなければ、次段階の大規模変換に進む準備が整ったと判断できます。

2.7 → 3.x：本格的ブレークチェンジ

Spring Boot 3 系では Jakarta EE パッケージ置換 と 新しい API（SecurityFilterChain 等） が導入されます。以下の表に主要な変更点をまとめました。

項目	2.7 系 (javax)	3.x 系 (jakarta)
Java バージョン	任意（11〜17）	最低 17、推奨 21
パッケージ	`javax.*`	`jakarta.*`
Spring Security	`WebSecurityConfigurerAdapter`	`SecurityFilterChain`
Auto‑configuration 登録	`spring.factories`	`AutoConfiguration.imports`

依存ライブラリ更新チェックリスト（抜粋）

Spring Cloud → 2023.0.x 以上
Hibernate ORM → 6.4.x（Jakarta Persistence 対応）
Tomcat → 10.1.x（Servlet API が jakarta.servlet に置換）

参考：公式 Migration Guide の「依存バージョン対応表」[^4] を必ず参照し、プロジェクト固有のライブラリも同様に確認してください。

主要なコード・設定変更ポイント

Spring Boot 3 系への移行で最も頻出する変更は Jakarta パッケージ置換、Security のリファクタリング、そして AutoConfiguration 登録方式の変更 です。以下に具体的な実装例と自動化ツールを紹介します。

Jakarta EE パッケージ置換と自動化ツール

手作業で javax.* → jakarta.* を書き換えると抜け漏れが発生しやすいため、OpenRewrite のレシピ JavaxToJakarta を利用します。

&lt;plugin&gt;
    &lt;groupId&gt;org.openrewrite&lt;/groupId&gt;
    &lt;artifactId&gt;rewrite-maven-plugin&lt;/artifactId&gt;
    &lt;version&gt;5.33.0&lt;/version&gt;
    &lt;executions&gt;
        &lt;execution&gt;
            &lt;goals&gt;&lt;goal&gt;run&lt;/goal&gt;&lt;/goals&gt;
            &lt;configuration&gt;
                &lt;!-- Jakarta 変換レシピを有効化 --&gt;
                &lt;activeRecipes&gt;
                    &lt;recipe&gt;org.openrewrite.java.migration.JavaxToJakarta&lt;/recipe&gt;
                &lt;/activeRecipes&gt;
            &lt;/configuration&gt;
        &lt;/execution&gt;
    &lt;/executions&gt;
&lt;/plugin&gt;

<groupId>org.openrewrite</groupId>

<artifactId>rewrite-maven-plugin</artifactId>

<recipe>org.openrewrite.java.migration.JavaxToJakarta</recipe>

</activeRecipes>

</configuration>

</execution>

</executions>

</plugin>

# Maven プロジェクトでの実行例
./mvnw rewrite:run

# Maven プロジェクトでの実行例

./mvnw rewrite:run

プラグインは変換レポートを出力し、未変換箇所が残っている場合は CI で失敗させる 設定も可能です。

Spring Security の新構成：`SecurityFilterChain` への移行

WebSecurityConfigurerAdapter が削除されたため、関数型 DSL に置き換えます。以下は典型的な設定例です。

@Configuration(proxyBeanMethods = false)
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -&gt; csrf.disable())
            .authorizeHttpRequests(authz -&gt; authz
                .requestMatchers(&quot;/admin/**&quot;).hasRole(&quot;ADMIN&quot;)
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());

        return http.build();
    }
}

@Configuration(proxyBeanMethods = false)

public class SecurityConfig {

@Bean

public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

http

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

.authorizeHttpRequests(authz -> authz

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

.anyRequest().authenticated()

)

.httpBasic(Customizer.withDefaults());

return http.build();

}

重要ポイント
- @Configuration(proxyBeanMethods = false) により起動時のコンテキスト生成が高速化。
- DSL が直接 HttpSecurity を返すため、従来の configure() メソッドは不要。

`spring.factories` の廃止と代替設定

Spring Boot 3 系では自動構成クラスを列挙するファイルが AutoConfiguration.imports に変更されました。既存プロジェクトでの移行手順は次の通りです。

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports を作成
旧 spring.factories に記載していたクラスを同ファイルに列挙

# AutoConfiguration.imports の例
com.example.MyCustomAutoConfiguration
org.springframework.boot.actuate.autoconfigure.security.servlet.SecurityEndpointAutoConfiguration

# AutoConfiguration.imports の例

com.example.MyCustomAutoConfiguration

org.springframework.boot.actuate.autoconfigure.security.servlet.SecurityEndpointAutoConfiguration

個別にインポートしたい場合は @ImportAutoConfiguration アノテーションで明示的に指定できます。

@ImportAutoConfiguration(MyCustomAutoConfiguration.class)
public class MyApplication { }

@ImportAutoConfiguration(MyCustomAutoConfiguration.class)

public class MyApplication { }

要点：spring.factories が読み込まれなくなるため、必ず新形式へ置き換えてください。

テスト・CI パイプラインでの検証フロー

移行後は ビルド・テスト・デプロイ を自動化し、旧環境と新環境の差分を継続的に比較します。以下は GitHub Actions を用いた典型的なワークフローです。

CI 設計例（GitHub Actions）

name: CI - Spring Boot 3 Migration

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        java-version: [17, 21]

    steps:
      - uses: actions/checkout@v4

      # JDK のセットアップ
      - name: Set up JDK ${{ matrix.java-version }}
        uses: actions/setup-java@v3
        with:
          distribution: temurin
          java-version: ${{ matrix.java-version }}

      # Maven キャッシュ
      - name: Cache Maven packages
        uses: actions/cache@v3
        with:
          path: ~/.m2/repository
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
          restore-keys: |
            ${{ runner.os }}-maven-

      # OpenRewrite による Jakarta 変換チェック（レポート生成）
      - name: Run OpenRewrite migration check
        run: ./mvnw rewrite:run -Drewrite.activeRecipes=org.openrewrite.java.migration.JavaxToJakarta

      # ビルド &amp; テスト実行
      - name: Build with Maven
        run: ./mvnw clean verify -B

      # Docker イメージ作成（任意）
      - name: Build Docker image
        if: success()
        run: |
          docker build -t myapp:${{ github.sha }} .

name: CI - Spring Boot 3 Migration

on:

push:

branches: [ main ]

pull_request:

jobs:

build:

runs-on: ubuntu-latest

strategy:

matrix:

java-version: [17, 21]

steps:

- uses: actions/checkout@v4

# JDK のセットアップ

- name: Set up JDK ${{ matrix.java-version }}

uses: actions/setup-java@v3

with:

distribution: temurin

java-version: ${{ matrix.java-version }}

# Maven キャッシュ

- name: Cache Maven packages

uses: actions/cache@v3

with:

path: ~/.m2/repository

key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

restore-keys: |

${{ runner.os }}-maven-

# OpenRewrite による Jakarta 変換チェック（レポート生成）

- name: Run OpenRewrite migration check

run: ./mvnw rewrite:run -Drewrite.activeRecipes=org.openrewrite.java.migration.JavaxToJakarta

# ビルド & テスト実行

- name: Build with Maven

run: ./mvnw clean verify -B

# Docker イメージ作成（任意）

- name: Build Docker image

if: success()

run: |

docker build -t myapp:${{ github.sha }} .

典型的なエラーパターンと対処法

エラー例	原因	推奨対策
`ClassNotFoundException: jakarta.servlet.Filter`	`javax.servlet.*` が残存	OpenRewrite のレポートで未変換クラスを抽出し、手動修正
`NoSuchBeanDefinitionException: SecurityFilterChain`	旧 `WebSecurityConfigurerAdapter` が残っている	新しい `SecurityConfig` クラスに置き換え、`@EnableWebSecurity` を削除
`Failed to load ApplicationContext`（自動構成が無効）	`spring.factories` が読み込まれない	`AutoConfiguration.imports` に対象クラスを列挙、または `@ImportAutoConfiguration` を使用

ベストプラクティス：CI で Java バージョンごとのマトリックスビルド と OpenRewrite の自動チェック を組み合わせると、移行漏れや互換性問題を早期に検出できます。

実務ベストプラクティスまとめ

以下は公式ガイドと実務事例から抽出した、Spring Boot 2 → 3 移行で最も効果的な手順です。

環境統一
JAVA_HOME と IDE の JDK を Java 17/21 に固定。ビルドツールのプロパティでも同様に設定することで、全開発者・CI が同一バージョンを使用します。
段階的アップデート
2.5 → 2.7（安全マイナーバージョン）→ 3.x（ブレークチェンジ）の順に実施。各フェーズでビルド・テストを必ず走らせ、問題が無いことを確認してから次へ進む。
自動変換ツール活用
OpenRewrite の JavaxToJakarta レシピでパッケージ置換を一括実行。CI でレポートの有無をチェックし、手作業の抜け漏れを防止。
新 API へのリファクタリング
SecurityFilterChain と AutoConfiguration.imports に置き換えるだけで、非推奨警告がほぼゼロになることが実証されています[^5]。
CI での検証自動化
Java バージョンマトリックス + OpenRewrite のチェックを標準パイプラインに組み込み、ビルド失敗時は即座に PR をブロック。

以上の手順とチェックポイントを守れば、安全かつ確実に Spring Boot 3 系へ移行でき、最新エコシステムの恩恵（パフォーマンス向上・長期サポート）をすぐに享受できます。

参考文献

[^1]: Spring Official Migration Guide, Spring.io, 2024‑10. https://spring.io/
[^2]: 「Spring Boot 2→3 移行実務レポート」, MizuCoffee Blog, 2025‑04‑24. https://springboot-123.mizucoffee.com/ja/blog/spring-boot-2-to-3-migration-guide/
[^3]: 株式会社TechBridge 社内事例（2025 年度）―「Spring Boot 2.7 にアップデートした結果、非推奨警告が 80% 削減」※社外公開情報に基づく。
[^4]: Spring Official Dependency Compatibility Matrix, Spring.io, 2024‑10. https://spring.io/
[^5]: 「Spring Boot 3 移行ベストプラクティス」, Tatsujin Tech Blog, 2023‑12‑09. https://app-tatsujin.com/spring-boot-migration-2-to-3/

スポンサードリンク

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

-JAVA

comment コメントをキャンセル

: JAVA

2026年リリースの Java JDK21/22 セキュリティパッチ取得と自動適用ガイド

JDK21 LTS と JDK22 の2026年セキュリティパッチ概要、公式取得方法、SDKMAN!・apt/yumでの更新、CVE自動取得、CI/CDでの自動適用手順をまとめました。

: JAVA

Spring Boot と Java 21 の公式サポートと移行ガイド

Spring Boot 3.3 から Java 21 が最低要件となり、Maven/Gradle の toolchain 設定や Docker イメージでの JRE 統一方法、2.x から 3.x への破壊的変更ポイントを網羅しています。

: JAVA

Java向けAIライブラリ比較：TensorFlow JavaとDeeplearning4jの選び方

Java環境でディープラーニングを選ぶ際の基準と、TensorFlow Java API と Deeplearning4j の特徴・ベンチマーク・エンタープライズ統合方法を解説します。

: JAVA

Spring Boot 3.xでマイクロサービス構築・Docker/Kubernetesデプロイ完全ガイド

Spring Boot 3.x と Java 17 を組み合わせ、DDD に沿ったレイヤ構成でマイクロサービスを実装し、Docker のマルチステージビルドと Kubernetes デプロイまでを一貫して解説します。

: JAVA

Java 17 LTS 完全ガイド：サポート期間・新機能と移行手順

Java 17は2029年までの商用LTSサポートが提供され、Switch式やRecord、Sealed classなど多数の新機能を備えています。本稿ではサポート概要と実務向けコード例、移行手順を詳しく紹介します。

Zapier AI 2026年導入実績と業界別自動化効果

Java 22新機能で開発効率アップ！企業向け活用戦略と実装例

Spring Boot 2→3 移行ガイド：段階的アップデートと Jakarta EE 対応

全体像と移行戦略

前提条件と環境統一

Java バージョンの選定と設定

ビルドツール別設定例

Maven 用共通プロパティ（pom.xml）

Gradle (Kotlin DSL) 用設定例

段階的アップグレード手順

2.5 → 2.7：マイナーバージョンで安全に移行

2.7 → 3.x：本格的ブレークチェンジ

依存ライブラリ更新チェックリスト（抜粋）

主要なコード・設定変更ポイント

Jakarta EE パッケージ置換と自動化ツール

Spring Security の新構成：SecurityFilterChain への移行

spring.factories の廃止と代替設定

テスト・CI パイプラインでの検証フロー

CI 設計例（GitHub Actions）

典型的なエラーパターンと対処法

実務ベストプラクティスまとめ

参考文献

Maven 用共通プロパティ（`pom.xml`）

Spring Security の新構成：`SecurityFilterChain` への移行

`spring.factories` の廃止と代替設定