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

2026年4月19日

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

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!

スポンサードリンク

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

-JAVA

comment コメントをキャンセル

: JAVA

Java 21 LTSのメリットと企業向け導入ガイド

Java 21はLTS版として8年間の保守が約束され、企業向けにコスト削減とパフォーマンス向上をもたらす主要機能を備えています。

: JAVA

Java 25 LTSと新機能完全ガイド – サポート・IOクラス・並行処理

Java 25は2025年9月に登場したLTSリリースで、8年のサポートとStable Values・Scoped Valuesの正式化、IOクラス追加など多数の改善が含まれます。

: JAVA

2025‑2026年版無料Java IDE比較：IntelliJ IDEA CE・Eclipse・NetBeans徹底解説

最新の無料Java IDEとして注目されるIntelliJ IDEA CE、Eclipse、NetBeansを機能・性能・プラグインなど5つの観点から比較し、最適な選択を提案します。

: JAVA

Java 17 の概要・新機能とアップグレード手順ガイド

Java 17 は LTS版で、Java 8/11 に比べ言語機能や標準ライブラリが大幅に進化しています。本稿では主要JEP7選と実務への移行手順を詳しく解説します。

: JAVA

Windows10でJava JDKを確認・ダウンロード・インストール手順

Windows10に最新Java JDK 22を安全に導入する手順と、JDKとJREの違い、インストーラ選択、環境変数設定、よくあるトラブルへの対処法をまとめました。

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 の組み込み