GraalVM Native Image for Java アプリケーション

GraalVM Native Image を使用して Java アプリケーションから高性能なネイティブ実行可能ファイルを構築し、起動時間とメモリ消費量を大幅に削減するエキスパートスキル。

概要

GraalVM Native Image は Java アプリケーションを事前にコンパイル（AOT）してスタンドアロンのネイティブ実行可能ファイルに変換します。これらの実行可能ファイルはミリ秒単位で起動し、JVM ベースのデプロイメントよりも大幅に少ないメモリを必要とし、サーバーレス関数、CLI ツール、および高速起動と低リソース使用が重要なマイクロサービスに最適です。

このスキルは、ビルドツール設定、フレームワーク固有のパターン、リフレクションメタデータ管理をカバーする、JVM アプリケーションをネイティブバイナリに移行するための構造化されたワークフローを提供し、ネイティブビルドの失敗を解決するための反復的なアプローチを含みます。

使用時期

このスキルは以下の場合に使用してください：

• JVM ベースの Java アプリケーションを GraalVM ネイティブ実行可能ファイルに変換する
• サーバーレスまたはコンテナ化されたデプロイメントの冷起動時間を最適化する
• Java マイクロサービスのメモリフットプリント（RSS）を削減する
• GraalVM Native Build Tools で Maven または Gradle を構成する
• ネイティブビルドで ClassNotFoundException、NoSuchMethodException、またはリソース欠落エラーを解決する
• reflect-config.json、resource-config.json、またはその他の GraalVM メタデータファイルを生成または編集する
• GraalVM トレーシングエージェントを使用して到達可能性メタデータを収集する
• Spring Boot ネイティブサポート用に RuntimeHints を実装する
• Quarkus または Micronaut でネイティブイメージを構築する

説明

1. コンテキスト別プロジェクト分析

設定を行う前に、プロジェクトを分析してビルドツール、フレームワーク、依存関係を決定します：

ビルドツールを検出する：

# Maven の確認
if [ -f "pom.xml" ]; then
    echo "Build tool: Maven"
    # Maven ラッパーの確認
    [ -f "mvnw" ] && echo "Maven wrapper available"
fi

# Gradle の確認
if [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
    echo "Build tool: Gradle"
    [ -f "build.gradle.kts" ] && echo "Kotlin DSL"
    [ -f "gradlew" ] && echo "Gradle wrapper available"
fi

依存関係を分析してフレームワークを検出する：

• Spring Boot: pom.xml または build.gradle で spring-boot-starter-* を確認
• Quarkus: quarkus-* 依存関係を確認
• Micronaut: micronaut-* 依存関係を確認
• Plain Java: フレームワーク依存関係が検出されない

Java バージョンを確認する：

java -version 2>&1
# GraalVM Native Image には Java 17+ が必要（推奨：Java 21+）

潜在的なネイティブイメージの課題を特定する：

• リフレクションが多い ライブラリ（Jackson、Hibernate、JAXB）
• 動的プロキシの使用（JDK プロキシ、CGLIB）
• リソースバンドルとクラスパスリソース
• JNI またはネイティブライブラリ依存関係
• シリアライゼーション要件

2. ビルドツール設定

検出された環境に基づいて適切なビルドツールプラグインを設定します。

Maven プロジェクトの場合、標準ビルドをクリーンに保つために専用の native プロファイルを追加します。完全な設定については Maven Native Profile Reference を参照してください。

Maven の主なセットアップ：

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <version>0.10.6</version>
          <extensions>true</extensions>
          <executions>
            <execution>
              <id>build-native</id>
              <goals>
                <goal>compile-no-fork</goal>
              </goals>
              <phase>package</phase>
            </execution>
          </executions>
          <configuration>
            <imageName>${project.artifactId}</imageName>
            <buildArgs>
              <buildArg>--no-fallback</buildArg>
            </buildArgs>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

ビルド実行：./mvnw -Pnative package

Gradle プロジェクトの場合、org.graalvm.buildtools.native プラグインを適用します。完全な設定については Gradle Native Plugin Reference を参照してください。

Gradle の主なセットアップ（Kotlin DSL）：

plugins {
    id("org.graalvm.buildtools.native") version "0.10.6"
}

graalvmNative {
    binaries {
        named("main") {
            imageName.set(project.name)
            buildArgs.add("--no-fallback")
        }
    }
}

ビルド実行：./gradlew nativeCompile

3. フレームワーク固有の設定

各フレームワークには独自の AOT 戦略があります。検出されたフレームワークに基づいて正しい設定を適用してください。

Spring Boot（3.x+）: Spring Boot には GraalVM の組み込みサポートと AOT 処理があります。RuntimeHints、@RegisterReflectionForBinding、テストサポートなどのパターンについては Spring Boot Native Reference を参照してください。

主なポイント：

• spring-boot-starter-parent 3.x+ を使用します（これはネイティブプロファイルを含みます）
• RuntimeHintsRegistrar を介してリフレクションヒントを登録します
• process-aot ゴールで AOT 処理を実行します
• ビルド実行：./mvnw -Pnative native:compile または ./gradlew nativeCompile

Quarkus と Micronaut: これらのフレームワークはネイティブファーストで設計されており、追加設定はほとんど必要ありません。詳細については Quarkus & Micronaut Reference を参照してください。

4. GraalVM 到達可能性メタデータ

Native Image は閉じた世界と仮定します — すべてのコードパスはビルド時に既知である必要があります。リフレクション、リソース、プロキシなどの動的機能には明示的なメタデータ設定が必要です。

メタデータファイルは META-INF/native-image/<group.id>/<artifact.id>/ に配置されます：

ファイル	目的
reachability-metadata.json	統合メタデータ（リフレクション、リソース、JNI、プロキシ、バンドル、シリアライゼーション）
reflect-config.json	レガシー：リフレクション登録
resource-config.json	レガシー：リソースインクルージョンパターン
proxy-config.json	レガシー：動的プロキシインターフェース
serialization-config.json	レガシー：シリアライゼーション登録
jni-config.json	レガシー：JNI アクセス登録

完全なフォーマットと例については Reflection & Resource Config Reference を参照してください。

5. 反復的な修正エンジン

ネイティブイメージビルドは、メタデータが不足しているために失敗することがよくあります。このような反復的なアプローチに従ってください：

ステップ 1 — ネイティブビルドを実行する：

# Maven
./mvnw -Pnative package 2>&1 | tee native-build.log

# Gradle
./gradlew nativeCompile 2>&1 | tee native-build.log

ステップ 2 — ビルドエラーを解析して根本原因を特定する：

一般的なエラーパターンと修正方法：

エラーパターン	原因	修正
ClassNotFoundException: com.example.MyClass	リフレクションメタデータが不足	reflect-config.json に追加するか @RegisterReflectionForBinding を使用
NoSuchMethodException	メソッドがリフレクション用に登録されていない	リフレクション設定にメソッドを追加
MissingResourceException	リソースがネイティブイメージに含まれていない	resource-config.json に追加
Proxy class not found	動的プロキシが登録されていない	インターフェースリストを proxy-config.json に追加
UnsupportedFeatureException: Serialization	シリアライゼーションメタデータが不足	serialization-config.json に追加

ステップ 3 — 適切なメタデータファイルを更新するか、フレームワークアノテーションを使用して修正を適用する。

ステップ 4 — リビルドして検証する。 ビルドが成功するまで繰り返します。

ステップ 5 — 手動修正が不十分な場合、GraalVM トレーシングエージェントを使用して到達可能性メタデータを自動的に収集します。Tracing Agent Reference を参照してください。

6. 検証とベンチマーク

ネイティブビルドが成功したら：

実行可能ファイルが正しく実行されることを確認する：

# ネイティブ実行可能ファイルを実行
./target/<app-name>

# Spring Boot の場合、アプリケーションコンテキストが読み込まれることを確認
curl http://localhost:8080/actuator/health

起動時間を測定する：

# 起動時間を測定
time ./target/<app-name>

# Spring Boot の場合、スタートアップログを確認
./target/<app-name> 2>&1 | grep "Started .* in"

メモリフットプリント（RSS）を測定する：

# Linux の場合
ps -o rss,vsz,comm -p $(pgrep <app-name>)

# macOS の場合
ps -o rss,vsz,comm -p $(pgrep <app-name>)

JVM ベースラインと比較する：

メトリック	JVM	ネイティブ	改善
起動時間	~2-5秒	~50-200ms	10-100倍
メモリ（RSS）	~200-500MB	~30-80MB	3-10倍
バイナリサイズ	JRE + JARs	単一バイナリ	簡素化

7. Docker 統合

ネイティブ実行可能ファイルで最小限のコンテナイメージを構築する：

# マルチステージビルド
FROM ghcr.io/graalvm/native-image-community:21 AS builder
WORKDIR /app
COPY . .
RUN ./mvnw -Pnative package -DskipTests

# 最小ランタイムイメージ
FROM debian:bookworm-slim
COPY --from=builder /app/target/<app-name> /app/<app-name>
EXPOSE 8080
ENTRYPOINT ["/app/<app-name>"]

Spring Boot アプリケーションの場合、Cloud Native Buildpacks で paketobuildpacks/builder-jammy-tiny を使用してください：

./mvnw -Pnative spring-boot:build-image

ベストプラクティス

1. 複雑なプロジェクトではトレーシングエージェントから開始する — 初期メタデータベースラインを生成
2. native プロファイルを使用する — ネイティブ固有の設定を標準ビルドから分離
3. --no-fallback を優先する — 真のネイティブビルド（JVM フォールバックなし）を確保
4. nativeTest でテストする — ネイティブモードで JUnit テストを実行
5. GraalVM Reachability Metadata Repository を使用する — サードパーティライブラリメタデータ用
6. リフレクションを最小化する — 可能な限りコンストラクタインジェクションとコンパイル時 DI を優先
7. リソースパターンを明示的に含める — クラスパススキャンに依存しない
8. 修正前後をプロファイルする — 常に起動とメモリの改善を測定
9. Java 21+ を使用する — 最高の GraalVM 互換性とパフォーマンスのため
10. GraalVM と Native Build Tools のバージョンを揃える

例

例 1: Spring Boot Maven プロジェクトへのネイティブサポートの追加

シナリオ: Spring Boot 3.x REST API があり、これをネイティブ実行可能ファイルにコンパイルしたいです。

ステップ 1 — pom.xml にネイティブプロファイルを追加する：

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
          <executions>
            <execution>
              <id>process-aot</id>
              <goals>
                <goal>process-aot</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

ステップ 2 — DTO のリフレクションヒントを登録する：

@RestController
@RegisterReflectionForBinding({UserDto.class, OrderDto.class})
public class UserController {

    @GetMapping("/users/{id}")
    public UserDto getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

ステップ 3 — ビルドして実行する：

./mvnw -Pnative native:compile
./target/myapp
# Started MyApplication in 0.089 seconds

例 2: ネイティブビルドでのリフレクションエラーの解決

シナリオ: ネイティブビルドが Jackson でシリアライズされた DTO に対して ClassNotFoundException で失敗します。

エラー出力：

com.oracle.svm.core.jdk.UnsupportedFeatureError:
  Reflection registration missing for class com.example.dto.PaymentResponse

修正 — src/main/resources/META-INF/native-image/reachability-metadata.json に追加する：

{
  "reflection": [
    {
      "type": "com.example.dto.PaymentResponse",
      "allDeclaredConstructors": true,
      "allDeclaredMethods": true,
      "allDeclaredFields": true
    }
  ]
}

または Spring Boot アノテーションアプローチを使用する：

@RegisterReflectionForBinding(PaymentResponse.class)
@Service
public class PaymentService { /* ... */ }

例 3: 複雑なプロジェクトでのトレーシングエージェントの使用

シナリオ: 多くのサードパーティライブラリを持つプロジェクトは包括的な到達可能性メタデータが必要です。

# 1. JAR をビルド
./mvnw package -DskipTests

# 2. トレーシングエージェント付きで実行
java -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image \
    -jar target/myapp.jar

# 3. すべてのエンドポイントを操作
curl http://localhost:8080/api/users
curl -X POST http://localhost:8080/api/orders -H 'Content-Type: application/json' -d '{"item":"test"}'
curl http://localhost:8080/actuator/health

# 4. アプリケーションを停止（Ctrl+C）してからネイティブをビルド
./mvnw -Pnative native:compile

# 5. 検証
./target/myapp

制約と警告

重要な制約

• GraalVM Native Image には Java 17+ が必要です（Java 21+ が最高の互換性のために推奨）
• 閉じた世界と仮定: すべてのコードパスはビルド時に既知である必要があります — 動的クラスローディング、ランタイムバイトコード生成、MethodHandles.Lookup は動作しないことがあります
• ビルド時間とメモリ: ネイティブコンパイルはリソース集約的です — 典型的なプロジェクトで 2～10 分と 4～8 GB の RAM を予想してください
• すべてのライブラリが互換性があるわけではありません: リフレクション、動的プロキシ、CGLIB に大きく依存するライブラリは、大量のメタデータ設定が必要な場合があります
• AOT プロファイルはビルド時に固定されます: Spring Boot @Profile と @ConditionalOnProperty は AOT 処理中に評価され、ランタイムではありません

一般的な落とし穴

• --no-fallback を忘れる: このフラグなしでは、ビルドが JVM フォールバックイメージを静かに作成する可能性があります
• 不完全なトレーシングエージェントカバレッジ: エージェントは実行中に操作されたコードパスのみをキャプチャします — すべての機能がテストされていることを確認してください
• バージョン不一致: GraalVM JDK、Native Build Tools プラグイン、フレームワークバージョンを揃えて、非互換性を回避してください
• クラスパスの違い: AOT/ビルド時のクラスパスはランタイムと一致する必要があります — ネイティブコンパイル後に JAR を追加/削除するとエラーが発生します

セキュリティに関する考慮事項

• ネイティブ実行可能ファイルは JAR より逆コンパイルが難しいですが、改ざんに強いわけではありません
• ビルド時にシークレットがネイティブイメージに埋め込まれていないことを確認してください
• 機密データには環境変数または外部設定を使用してください

トラブルシューティング

問題	解決方法
ビルドがメモリ不足になる	ビルドメモリを増やす：buildArgs で -J-Xmx8g
ビルドに時間がかかる	ビルドキャッシュを使用し、クラスパスを削減し、開発用の高速ビルドモードを有効化
アプリケーションがランタイムでクラッシュ	リフレクション/リソースメタデータが不足 — トレーシングエージェントを実行
Spring Boot コンテキストの読み込みが失敗	@Conditional ビーンとプロファイル依存設定を確認
サードパーティライブラリに互換性がない	GraalVM Reachability Metadata リポジトリを確認するか、手動ヒントを追加