java-add-graalvm-native-image-support

GraalVM Native Image のサポート

フレームワークを問わず、Java プロジェクトに GraalVM Native Image を追加するための唯一の信頼できる情報源です。反復的に作業します。設定し、ビルドし、エラーを読み、修正して、ネイティブビルドが成功し、実行ファイルが正しく動作するまで再ビルドします。

詳細は references/ にあります。プロジェクトに必要なものだけを読み込んでください。

トピック	ファイル
Maven / Gradle のネイティブプラグイン設定	references/build-tools.md
リーチャビリティメタデータとトレーシングエージェント	references/reachability-metadata.md
よくあるビルド時／実行時エラーと修正方法	references/troubleshooting.md
Spring Boot（AOT、-Pnative、nativeCompile、build-image）	references/spring-boot.md
Quarkus	quarkus-native-and-container スキルに引き継いでください。references/quarkus.md に簡単な案内があります
Micronaut	references/micronaut.md

ステップ 1：プロジェクトを分析する

1. ビルドツール：pom.xml（Maven）または build.gradle / build.gradle.kts（Gradle）を確認します。ラッパー（./mvnw、./gradlew）がある場合は、そちらを優先してください。
2. 依存関係／プラグインからフレームワークを特定します。
   • Spring Boot：spring-boot-starter-parent、spring-boot-maven-plugin、または Gradle プラグイン org.springframework.boot
   • Quarkus：io.quarkus BOM／プラグイン、または quarkus-* 依存関係
   • Micronaut：io.micronaut 親／プラグイン、または micronaut-* 依存関係
   • それ以外は通常の Java
3. 既存のネイティブ設定：native-build-tools プラグイン、META-INF/native-image/、ネイティブプロファイル、application.properties のネイティブ関連キーを確認します。
4. ツールチェーン：java -version と native-image --version を実行します。ローカルでネイティブコンパイルするには、ビルドに使用する JDK として GraalVM JDK（native-image を含む）が必要です。コンテナまたはビルドパックによるビルド（bootBuildImage／spring-boot:build-image を使った Spring Boot ビルドパック、Quarkus コンテナビルド）はコンテナ内でコンパイルするため、ローカルの GraalVM は不要で、コンテナランタイムのみが必要です。プロジェクトの Java バージョンがインストール済みの GraalVM バージョンに対応しているか確認してください。

フレームワークが Quarkus の場合は、ここで作業を止めて quarkus-native-and-container スキルに引き継いでください。Quarkus のコンテナビルドにはローカルの GraalVM は不要です。

対象範囲と JVM のベースライン

• ネイティブ対応の追加は、JDK、フレームワーク、ライブラリ、ビルドツール、ラッパーのアップグレードを許可するものではありません。既存の BOM／親 POM で管理されているバージョンとテスト規約を維持し、ネイティブ互換性を解決するためにバージョンを変更する場合は、事前に確認してください。
• 編集前に、プロジェクトの既存の JVM ビルドとテストを実行します。既存の失敗は、チェックを弱めて隠すのではなく記録してください。ネイティブ対応と併せて、JVM のパッケージ化／実行経路も引き続き動作するようにします。
• 承認済みの依存関係またはフレームワークの変更後は、ネイティブビルドを続ける前に JVM のベースラインを再実行してください。JVM とネイティブの両方の経路で、同じ関連動作を確認してください。
• CI ワークフローの作成や変更、ネイティブ用 CI ジョブの追加、またはランナーのリソース変更を行う前に、確認してください。CI の変更が依頼されていない場合は、コマンドを個別に提案してください。

ステップ 2：GraalVM ツールチェーンを用意する

• Oracle GraalVM（GraalVM Free Terms and Conditions に基づき無料）と GraalVM Community Edition のビルドには、native-image が含まれています。プロジェクトの Java バージョンに対応するリリースを使用してください（たとえば、JDK 21 以降向けの GraalVM。Spring Boot 3.x／4.x には Java 17 以上のベースラインが必要です。Spring のリファレンスを参照してください）。
• SDKMAN（sdk list java を実行し、一覧にある識別子を使って sdk install java <identifier> を実行）、ベンダーのダウンロード、または graalvm/setup-graalvm などの CI アクションを使ってインストールします。特定のバージョンをハードコードせず、ベンダーの最新のダウンロードページからバージョンを選んでください。
• Linux では C ツールチェーンと zlib ヘッダー（build-essential、zlib1g-dev）が必要です。macOS では Xcode コマンドラインツール、Windows では Visual Studio Build Tools が必要です。GraalVM の最新の「Native Image prerequisites」ページを確認してください。

ステップ 3：ネイティブサポートを追加する

フレームワークごとの手順：

• Spring Boot：Maven の場合、spring-boot-starter-parent は native プロファイルでネイティブプラグインのバージョンと設定を管理するだけなので、存在しない場合は <build><plugins> に native-maven-plugin と spring-boot-maven-plugin を宣言します（バージョンの指定は不要です）。Gradle の場合は、org.springframework.boot と並べて org.graalvm.buildtools.native を適用します。カスタムの親では、プラグインを手動で追加する必要があります。親がすでに提供している設定を重複して追加しないでください。references/spring-boot.md を参照してください。
• Quarkus：quarkus-native-and-container スキルに引き継ぎます。
• Micronaut：Micronaut ビルドプラグインに組み込まれています。references/micronaut.md を参照してください。
• プレーン Java（またはフレームワークプラグインのないプロジェクト）：GraalVM Native Build Tools プラグインを追加します。references/build-tools.md を参照してください。実行時に Maven Central（org.graalvm.buildtools:native-maven-plugin）または Gradle Plugin Portal（org.graalvm.buildtools.native）からプラグインのバージョンを確認し、ビルドファイルに固定してください。記憶に頼ってバージョンをコピーしないでください。

ステップ 4：ビルドする

構成	コマンド
プレーン Maven	./mvnw -Pnative native:compile
プレーン Gradle	./gradlew nativeCompile
Spring Boot Maven	./mvnw -Pnative native:compile（またはコンテナの場合は spring-boot:build-image）
Spring Boot Gradle	./gradlew nativeCompile（または bootBuildImage）
Micronaut Maven	./mvnw package -Dpackaging=native-image
Micronaut Gradle	./gradlew nativeCompile

ネイティブビルドは時間がかかり、大量のメモリ（数 GB の RAM）を消費します。確認できるよう、出力全体を取得してください。

ステップ 5：ビルドが成功するまで繰り返す

1. 最後のサマリーではなく、最初の実際のエラーを読みます。
2. references/troubleshooting.md と照らし合わせます。
3. 最小限の修正を、次の優先順位で適用します。
   1. 互換性のあるライブラリ／フレームワークのバージョンに、ネイティブサポートが組み込まれているか確認します（リーチャビリティメタデータリポジトリを参照）。アップグレードを提案し、ユーザーの承認を得てから適用し、JVM のベースラインを再実行します。承認されない場合は、現在のバージョンと互換性のあるメタデータまたはフレームワークのヒントを試します。
   2. フレームワーク独自の仕組みを使用します（Spring の RuntimeHints、Quarkus の @RegisterForReflection、Micronaut の @Introspected）。
   3. トレーシングエージェントを使ってメタデータを収集します（references/reachability-metadata.md を参照）。
   4. src/main/resources/META-INF/native-image/<groupId>/<artifactId>/ にメタデータを手動で記述します。
   5. 特定のクラスに限って初期化を調整します（--initialize-at-build-time / --initialize-at-run-time）。
4. 再ビルドします。エラーなしでビルドが完了するまで繰り返します。

ステップ 6：実行ファイルを検証する

ビルドに成功しただけでは不十分です。多くの問題は実行時にしか発生しません。

• バイナリを実行し、主要な処理経路（HTTP エンドポイント、DB アクセス、シリアライズ、リソースの読み込み、スケジュールされたジョブ）を試します。
• フレームワークが対応している場合は、ネイティブテストを実行します（native:test、nativeTest、Quarkus の @QuarkusIntegrationTest）。
• ユーザーから求められた場合に限り、JVM での実行と起動時間およびメモリを比較します。
• 実行した正確なコマンド、ビルドと実行が成功したかどうか、残っている警告を報告します。

注意点

• CI では、明示した GraalVM のバージョンを使ったネイティブビルドとネイティブテストの実行を推奨します。ユーザーの同意なしに CI を追加または変更しないでください。
• Mockito のデフォルトのインラインモックメーカーはネイティブイメージでは動作しません（Mockito 5.0.0 のリリースノート）。ネイティブテストではサブクラスモックメーカーを使用してください。
• 正当な理由がない限り、--report-unsupported-elements-at-runtime や詳細出力フラグを本番ビルドに残さないでください。

参考資料

• GraalVM Native Image のドキュメント
• Native Build Tools
• GraalVM reachability metadata repository
• Spring Boot の GraalVM ネイティブイメージ
• Quarkus でのネイティブ実行可能ファイルのビルド
• Micronaut の GraalVM ガイド

上流ソース（GraalVM またはネイティブ設定をアップグレードする前に確認してください）

対象バージョンのページを取得してください。内容が矛盾する場合は、このスキルよりもそちらを優先してください。

• GraalVM のリリースノート：https://www.graalvm.org/release-notes/
• リーチャビリティメタデータの形式：https://www.graalvm.org/latest/reference-manual/native-image/metadata/
• ビルド設定オプション：https://www.graalvm.org/latest/reference-manual/native-image/overview/BuildConfiguration/
• メタデータリポジトリ（使用しているライブラリのバージョンが対象か確認してください）：https://github.com/oracle/graalvm-reachability-metadata