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

2026年4月19日

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

スポンサードリンク

働き方から選べる

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

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

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

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

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

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

Beyond Careerに無料相談する

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

Contents

1 1. 公式サポート概要
2 2. 実行環境とビルド環境の整合性を保つ理由
- 2.1 2.1 バージョン不一致が招く典型的な障害
- 2.2 2.2 推奨構成
3 3. Maven / Gradle における Java 21 指定手順
4 4. Spring Boot 2.x → 3.x 移行の必須ポイント
5 5. テスト・CI/CD における Java 21 の組み込み
- 5.1 5.1 Maven Surefire と Toolchain の連携例
- 5.2 5.2 Gradle テストタスク（Kotlin DSL）
6 6. CI パイプライン例
- 6.1 6.1 GitHub Actions
- 6.2 6.2 Jenkins（Declarative Pipeline）
7 7. よくあるエラーと対策（Q&A）
8 8. Java 21 新機能の活用ヒント（任意）
9 9. 参考リンク（Markdown 統一）
10 まとめ

スポンサードリンク

1. 公式サポート概要

Spring Boot バージョン	サポートする JDK
3.0 – 3.2 (パッチ)	Java 17、Java 21（※Toolchain 等で明示的に利用）
3.3 以降	Java 21（最低要件かつデフォルト）

Spring Boot 3.3 のリリースノートは「Minimum required JDK version is now 21」と明記しています【Spring Boot 3.3 Release Notes】。
java.version プロパティのデフォルトが 21 に変更されたことは、同リリースノート内の「Default Java version: 21」でも確認できます。

ポイント：Java 8/11 はサポート対象外です（Spring Boot 3 系全体で非推奨）。

2. 実行環境とビルド環境の整合性を保つ理由

2.1 バージョン不一致が招く典型的な障害

障害例	発生原因
`java.lang.UnsupportedClassVersionError: ... major version 65`	ビルドは JDK 21、実行は JRE 17 以下
`NoClassDefFoundError: jakarta/servlet/ServletException`	依存ライブラリがまだ javax 系を使用している
JPMS のモジュール解決失敗	`module-info.java` が Jakarta EE モジュールを宣言していない

Java 21 のバイトコードは 65.0（class file version）で、JRE 17 以前では読み込めません。したがって 開発 → CI → 本番 のすべてのステージで同一 JDK バージョンを使用することが必須です。

2.2 推奨構成

フェーズ	推奨設定
ローカル IDE	`Project SDK` → JDK 21、`JAVA_HOME` を同バージョンに設定
ビルドツール (Maven / Gradle)	Toolchain 機能で JDK 21 を強制
Docker 本番イメージ	`eclipse-temurin:21-jre` などの JRE‑only イメージを使用し、コンパイル用 JDK はマルチステージビルドで分離

3. Maven / Gradle における Java 21 指定手順

3.1 Maven の Toolchains 設定例

&lt;!-- pom.xml --&gt;
&lt;properties&gt;
    &lt;!-- Spring Boot が期待するバージョン --&gt;
    &lt;java.version&gt;21&lt;/java.version&gt;
&lt;/properties&gt;

&lt;build&gt;
    &lt;plugins&gt;
        &lt;!-- Toolchains による JDK 自動選択 --&gt;
        &lt;plugin&gt;
            &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
            &lt;artifactId&gt;toolchains-maven-plugin&lt;/artifactId&gt;
            &lt;version&gt;3.1.1&lt;/version&gt;
            &lt;executions&gt;
                &lt;execution&gt;
                    &lt;phase&gt;initialize&lt;/phase&gt;
                    &lt;goals&gt;&lt;goal&gt;toolchain&lt;/goal&gt;&lt;/goals&gt;
                &lt;/execution&gt;
            &lt;/executions&gt;
            &lt;configuration&gt;
                &lt;toolchains&gt;
                    &lt;jdk&gt;
                        &lt;version&gt;${java.version}&lt;/version&gt;
                        &lt;vendor&gt;temurin&lt;/vendor&gt;
                    &lt;/jdk&gt;
                &lt;/toolchains&gt;
            &lt;/configuration&gt;
        &lt;/plugin&gt;

        &lt;!-- Spring Boot Maven Plugin（3.3.x） --&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;3.3.0&lt;/version&gt;
        &lt;/plugin&gt;
    &lt;/plugins&gt;
&lt;/build&gt;

<java.version>21</java.version>

</properties>

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>toolchains-maven-plugin</artifactId>

<phase>initialize</phase>

<goals><goal>toolchain</goal></goals>

</execution>

</executions>

<jdk>

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

<vendor>temurin</vendor>

</jdk>

</toolchains>

</configuration>

</plugin>

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

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

</plugin>

</plugins>

</build>

Toolchains が有効になると、JAVA_HOME の値に関わらず Maven は必ず JDK 21 を使用します。

3.2 Gradle（Kotlin DSL）での Toolchain 設定例

plugins {
    id(&quot;org.springframework.boot&quot;) version &quot;3.3.0&quot;
    java
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
        vendor.set(JvmVendorSpec.TEMURIN)
    }
}

// コンパイルバイトコードを 21 に固定（release オプションは JDK 17 以降で推奨）
tasks.withType&lt;JavaCompile&gt; {
    options.release.set(21)
}

plugins {

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

java

}

java {

toolchain {

languageVersion.set(JavaLanguageVersion.of(21))

vendor.set(JvmVendorSpec.TEMURIN)

}

// コンパイルバイトコードを 21 に固定（release オプションは JDK 17 以降で推奨）

tasks.withType<JavaCompile> {

options.release.set(21)

}

Gradle は java.toolchain が自動的にテストタスクや実行タスクへも伝播するため、CI 環境で JDK 21 がインストールされていればローカルと同一条件が保証されます。

3.3 主要プロパティまとめ

ツール	プロパティ/設定	推奨値
Maven	`<java.version>` (POM)	`21`
Gradle	`java.toolchain.languageVersion`	`JavaLanguageVersion.of(21)`
Spring Boot Plugin (Maven/Gradle)	バージョン `3.3.x`	`-`

4. Spring Boot 2.x → 3.x 移行の必須ポイント

4.1 Jakarta EE 名前空間への置換

Spring Boot 3 系は Jakarta EE 9 に合わせて、すべての javax.* パッケージが jakarta.* に変更されました。代表的な変換表は以下です。

旧パッケージ	新パッケージ
`javax.servlet`	`jakarta.servlet`
`javax.persistence`	`jakarta.persistence`
`javax.validation`	`jakarta.validation`

実践的な置換手順
1. IDE の Replace in Path で javax. → jakarta. を一括置換。
2. pom.xml / build.gradle の依存バージョンを 3.x 系（例: spring-boot-starter-web → 3.3.0）に更新し、transitive で取得される Jakarta 対応ライブラリへ自動切り替えさせます。
3. jdeps -summary target/classes を実行し、残存する javax. 参照が無いか最終確認。

4.2 Spring Security 6 の設定刷新

WebSecurityConfigurerAdapter が削除され、代わりに SecurityFilterChain Bean が推奨されています。

// Spring Boot 2.x（非推奨）
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests().anyRequest().authenticated();
    }
}

// Spring Boot 2.x（非推奨）

@EnableWebSecurity

public class SecurityConfig extends WebSecurityConfigurerAdapter {

@Override

protected void configure(HttpSecurity http) throws Exception {

http.authorizeRequests().anyRequest().authenticated();

}

// Spring Boot 3.x（標準スタイル）
@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -&gt; auth.anyRequest().authenticated())
            .httpBasic(Customizer.withDefaults())
            .build();
    }
}

// Spring Boot 3.x（標準スタイル）

@Configuration

public class SecurityConfig {

@Bean

public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {

return http

.authorizeHttpRequests(auth -> auth.anyRequest().authenticated())

.httpBasic(Customizer.withDefaults())

.build();

}

4.3 その他の主要変更点

項目	主な変更	移行時の対策
Actuator エンドポイント	デフォルトベースパスは `/actuator/**` のみ	`management.endpoints.web.base-path` を必要に応じて上書き
WebMvc のハンドラ引数	`HandlerMethodArgumentResolver` が Jakarta 系へ	インポート文を `jakarta.*` に置換
ConfigurationProperties バインディング	アノテーションが `jakarta.validation.constraints.*` へ移行	`@Validated` と併せて `jakarta.validation` のアノテーションを使用

4.4 移行支援ツール

Spring Initializr（https://start.spring.io/）で同一依存構成の Spring Boot 3 プロジェクトを生成し、差分比較に利用。
jdeps コマンドで残りの javax. 参照を検出：
bash jdeps --module-path target/classes -summary target/classes | grep javax

5. テスト・CI/CD における Java 21 の組み込み

5.1 Maven Surefire と Toolchain の連携例

&lt;plugin&gt;
    &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
    &lt;artifactId&gt;maven-surefire-plugin&lt;/artifactId&gt;
    &lt;version&gt;3.1.2&lt;/version&gt;
    &lt;configuration&gt;
        &lt;!-- Toolchains が提供する JDK を使用 --&gt;
        &lt;useSystemClassLoader&gt;false&lt;/useSystemClassLoader&gt;
    &lt;/configuration&gt;
&lt;/plugin&gt;

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-surefire-plugin</artifactId>

<useSystemClassLoader>false</useSystemClassLoader>

</configuration>

</plugin>

Toolchain が有効な状態であれば、surefire は自動的に JDK 21 へ切り替わります。

5.2 Gradle テストタスク（Kotlin DSL）

tasks.test {
    useJUnitPlatform()
}

tasks.test {

useJUnitPlatform()

}

Gradle の java.toolchain 設定が継承され、テストも同一 JDK 21 で実行されます。

6. CI パイプライン例

6.1 GitHub Actions

name: Build &amp; Test (Java 21)

on:
  push:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 21
        uses: actions/setup-java@v3
        with:
          distribution: temurin
          java-version: '21'
          cache: maven   # Maven 用キャッシュを有効化
      - name: Build &amp; Verify
        run: ./mvnw verify

name: Build & Test (Java 21)

on:

push:

pull_request:

jobs:

build:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Set up JDK 21

uses: actions/setup-java@v3

with:

distribution: temurin

java-version: '21'

cache: maven # Maven 用キャッシュを有効化

- name: Build & Verify

run: ./mvnw verify

6.2 Jenkins（Declarative Pipeline）

pipeline {
    agent any
    tools { jdk 'jdk-21' }   // 管理画面で登録した JDK 名称
    stages {
        stage('Compile') {
            steps { sh './mvnw clean compile -DskipTests' }
        }
        stage('Test') {
            steps { sh './mvnw test' }
        }
        stage('Package') {
            steps { sh './mvnw package -DskipTests' }
        }
    }
}

pipeline {

agent any

tools { jdk 'jdk-21' } // 管理画面で登録した JDK 名称

stages {

stage('Compile') {

steps { sh './mvnw clean compile -DskipTests' }

}

stage('Test') {

steps { sh './mvnw test' }

}

stage('Package') {

steps { sh './mvnw package -DskipTests' }

}

ポイント：Jenkins の「Global Tool Configuration」で jdk-21 を登録し、Maven/Gradle の Toolchain と合わせて使用するとローカルと完全に同一環境が保証されます。

7. よくあるエラーと対策（Q&A）

質問	現象	原因	解決策
`java.lang.UnsupportedClassVersionError: major version 65`	アプリ起動時に例外	実行 JRE が 21 未満	本番コンテナを `*-jre:21` 系イメージへ差し替える
`NoClassDefFoundError: jakarta/servlet/ServletException`	Spring 起動直後に失敗	依存ライブラリが `javax.*` のまま	すべての `spring-boot-starter-` と外部ライブラリを 3.3.x* に更新
JPMS のモジュール解決エラー	`module-info.java` が不足	Jakarta EE モジュールを `requires` していない	`requires jakarta.servlet;` 等の宣言を追加し、`java --add-modules=...` オプションで補完
仮想スレッド使用時に `IllegalStateException: Cannot create a virtual thread`	`Thread.startVirtualThread(...)` が失敗	JDK 21 のプレビューオプションが無効（古い JDK）	実行環境を JDK 21.0.2+ に統一し、`-Djdk.virtualThreadScheduler=...` を付与

8. Java 21 新機能の活用ヒント（任意）

機能	主な利点	Spring Boot での利用例
仮想スレッド (Project Loom)	数十万規模の軽量スレッドでブロッキング I/O を非同期化	`Executors.newVirtualThreadPerTaskExecutor()` → `TaskExecutor` に登録し、`@Async` と組み合わせる
CRaC（Coordinated Restore at Checkpoint）	アプリ起動時間を数秒に短縮できるチェックポイント復元機能	`spring-boot-maven-plugin` の `build-image` ゴールで `--crac` フラグを付与し、GraalVM Native Image と併用

注意：仮想スレッドは JDK 21.0.2 以降で正式に有効です。CRaC は OS のサポートが必要（例: Ubuntu 22.04+）なので、本番環境の要件を事前に確認してください。

9. 参考リンク（Markdown 統一）

まとめ

公式サポートは Spring Boot 3.3 以降で Java 21 が最低要件です。
Toolchain を用いることで、IDE・ローカル・CI・本番すべてのステージで JDK 21 が統一されます。
移行時は Jakarta EE への名前空間変更 と Spring Security 6 の設定刷新 に注意し、jdeps で残存参照を検出してください。
CI/CD（GitHub Actions / Jenkins）と Docker マルチステージビルドを組み合わせれば、実行時に JDK が混入するリスクはゼロになります。

上記手順を踏めば、安全かつスムーズに Spring Boot と Java 21 の統合が完了し、最新の仮想スレッドや CRaC などの先進機能も活用できるようになります。 Happy coding!

スポンサードリンク

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

スポンサードリンク

働き方から選べる

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

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

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

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

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

Beyond Careerに無料相談する

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

-JAVA

comment コメントをキャンセル

: JAVA

Java 17 LTS導入ガイド:環境確認とメリット

Java 17 LTSへの移行手順をステップバイステップで解説。環境確認、ダウンロード方法、PATH設定、動作検証のポイントを網羅。

: JAVA

Java 22 の主要変更点と Java 21 との比較 – 移行チェックリスト

本記事では Java 22 の主要な変更点と Java 21 との差分を詳しく解説し、実務導入に役立つチェックリストやベストプラクティスをご紹介します。

: JAVA

Spring Boot と Java 21 の対応表・移行ガイド – バージョンと機能のベストプラクティス

Spring Boot 3 系列の各バージョンが対応する JDK を一覧化し、Java 21 の仮想スレッドや pattern matching、sealed interface など新機能を Spring アプリに組み込む具体例と、実測ベースのパフォーマンス向上効果、段階的な移行手順とチェックリストをご提供します。

: JAVA

Java 17 の LTS と長期サポート、主要機能と移行ベストプラクティス

Java 17 は2029年までの長期サポートとSealed Classes・Record拡張など実務に直結する機能が充実しています。

: JAVA

Javaバイトコード可視化ツール比較と導入ガイド

バイトコード可視化は設計把握・デバッグ支援・セキュリティ診断に有効で、JDBG と JIG が代表的なツールです。

2026年版 Instagram アルゴリズム変更とビジネス対策

2026年最新 JavaScript SEO完全ガイド：SSR・SSG・INP対策

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

1. 公式サポート概要

2. 実行環境とビルド環境の整合性を保つ理由

2.1 バージョン不一致が招く典型的な障害

2.2 推奨構成

3. Maven / Gradle における Java 21 指定手順

3.1 Maven の Toolchains 設定例

3.2 Gradle（Kotlin DSL）での Toolchain 設定例

3.3 主要プロパティまとめ

4. Spring Boot 2.x → 3.x 移行の必須ポイント

4.1 Jakarta EE 名前空間への置換

4.2 Spring Security 6 の設定刷新

4.3 その他の主要変更点

4.4 移行支援ツール

5. テスト・CI/CD における Java 21 の組み込み

5.1 Maven Surefire と Toolchain の連携例

5.2 Gradle テストタスク（Kotlin DSL）

6. CI パイプライン例

6.1 GitHub Actions

6.2 Jenkins（Declarative Pipeline）

7. よくあるエラーと対策（Q&A）

8. Java 21 新機能の活用ヒント（任意）

9. 参考リンク（Markdown 統一）

まとめ

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

3. Maven / Gradle における Java 21 指定手順

4. Spring Boot 2.x → 3.x 移行の必須ポイント

4.2 Spring Security 6 の設定刷新

5. テスト・CI/CD における Java 21 の組み込み