0Pricing
Spring Boot 4 Complete Guide · درس

معالجة AOT ومسار البناء الأصلي

تعرّف على محرّك Spring للمعالجة المسبقة وابنِ صورًا أصلية باستخدام مجموعة أدوات GraalVM

معالجة AOT ومسار البناء الأصلي درس مجاني في Spring Boot 4 Complete Guide على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Spring Boot 4 Complete Guide، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Spring Boot 4 Complete Guide 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

Why Native Images?

A traditional Spring Boot app runs on the JVM: bytecode is loaded, classes are verified, and the JIT compiler warms up over time. That gives great peak throughput but pays a cost at startup and in memory footprint.

GraalVM native images flip the model. Instead of shipping bytecode plus a JVM, you produce a single, self-contained executable where almost all the work normally done at runtime is moved to build time.

  • Startup drops from seconds to tens of milliseconds.
  • Memory footprint shrinks dramatically (no JIT, no class metadata bloat).
  • Trade-off: longer, heavier builds and a closed-world assumption.

This makes native images ideal for serverless, CLIs, and high-density containers.

The Closed-World Assumption

GraalVM's native compiler (native-image) performs static analysis of your entire program and only includes code it can prove is reachable. Everything must be known at build time — this is the closed-world assumption.

The features that make Spring flexible at runtime are exactly the ones that break under closed-world analysis:

  • Reflection — calling methods/fields discovered by name at runtime.
  • Dynamic proxies — Spring AOP, @Transactional, repository interfaces.
  • Resource loading — files looked up by path at runtime.
  • Serialization and runtime class generation.

Spring's AOT engine exists to bridge this gap: it analyzes your application ahead of time and emits the metadata and code GraalVM needs.

What Spring AOT Actually Does

When you build for native (or just enable AOT), Spring runs an ahead-of-time processing phase that transforms your dynamic application context into static, pre-computed form.

Concretely, Spring AOT generates:

  • Bean definition code — instead of scanning and parsing at runtime, Spring emits Java source (*__BeanDefinitions.java) that registers beans programmatically.
  • An ApplicationContextInitializer that wires the context without classpath scanning.
  • GraalVM reachability metadata — JSON hints for reflection, resources, proxies, and serialization.

The runtime context becomes effectively frozen: the bean set is fixed at build time. You cannot add beans dynamically after AOT processing.

Enabling AOT in the Build

Spring AOT is driven by build plugins. With Maven, the spring-boot-maven-plugin exposes a process-aot goal; the native profile wires it together with GraalVM's native-maven-plugin.

The key dependency for native builds is the GraalVM toolchain plugin. Here is a typical Maven setup that activates AOT and native compilation.

<plugin>
  <groupId>org.graalvm.buildtools</groupId>
  <artifactId>native-maven-plugin</artifactId>
</plugin>
<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>

The Native Build Pipeline, Step by Step

Building a native image is a multi-stage pipeline. Understanding the order helps you locate failures.

  • 1. Compile — normal javac compilation of your sources.
  • 2. AOT processing — Spring runs process-aot, generating bean-definition sources and reachability metadata under target/spring-aot.
  • 3. AOT compile — the generated sources are compiled alongside your code.
  • 4. native-image — GraalVM performs static analysis (the closed-world step) and emits a native executable.

Trigger it with Maven via the native profile:

# Produce the native executable in target/
./mvnw -Pnative native:compile

# Or build a native container image with buildpacks
./mvnw -Pnative spring-boot:build-image

Runtime Hints: The Programmatic API

Spring AOT detects most reflection automatically, but for your own dynamic code (e.g., a class you load reflectively), you must declare hints. The idiomatic way is a RuntimeHintsRegistrar.

You register the registrar with @ImportRuntimeHints on a configuration or component. At AOT time Spring invokes it and folds your hints into the GraalVM metadata.

import org.springframework.aot.hint.MemberCategory;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;

public class MyRuntimeHints implements RuntimeHintsRegistrar {

    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.reflection().registerType(
            com.example.PaymentProcessor.class,
            MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
            MemberCategory.INVOKE_PUBLIC_METHODS);

        hints.resources().registerPattern("config/*.properties");
    }
}

Wiring Hints into the Context

A RuntimeHintsRegistrar does nothing until Spring knows about it. Attach it with @ImportRuntimeHints so it participates in AOT processing.

This keeps native-specific knowledge close to the code that needs it, rather than in a separate JSON file you must hand-maintain.

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.ImportRuntimeHints;

@Configuration
@ImportRuntimeHints(MyRuntimeHints.class)
public class NativeConfig {
    // Beans defined here are processed with the hints above
}

The @RegisterReflectionForBinding Shortcut

The most common reason to need hints is serialization/deserialization of DTOs — Jackson reflects over your classes. Writing a full registrar for every DTO is tedious.

Spring offers @RegisterReflectionForBinding, which automatically registers the reflection metadata needed to bind (serialize/deserialize) the listed types.

import org.springframework.aot.hint.annotation.RegisterReflectionForBinding;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RegisterReflectionForBinding({ OrderResponse.class, OrderItem.class })
class OrderController {

    @GetMapping("/orders/latest")
    OrderResponse latest() {
        return new OrderResponse("A-100", List.of(new OrderItem("sku-1", 2)));
    }
}

The GraalVM Tracing Agent

For third-party libraries that use reflection but ship no metadata, the AOT engine can't always infer the hints. The fallback is the GraalVM tracing agent.

You run your app on the JVM with the agent attached and exercise its code paths (tests, a smoke run). The agent records every reflective access, resource load, and proxy and writes them as metadata JSON.

  • Output lands under META-INF/native-image/.
  • It only captures paths you actually execute — incomplete test coverage means missing hints.
  • Treat it as a last resort; prefer reachability metadata repos and Spring's automatic detection first.
# Attach the tracing agent while running tests on the JVM
java -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image \
     -jar target/app.jar

Build-Time vs Runtime Initialization

A subtle but critical concept: native-image can run static initializers at build time and bake the resulting state into the image. Spring Boot's defaults push most app initialization to build time for speed.

This causes a classic bug: anything that captures environment-specific or time-sensitive state in a static initializer gets frozen at build time.

  • A static final SecureRandom seed computed at build time would be identical on every machine.
  • Reading an environment variable in a static block captures the build server's value, not production's.

The fix: defer such work to runtime (e.g., a @Bean method or lazy init) so it executes when the executable actually starts.

@Configuration
class CryptoConfig {

    // Created when the native executable starts, NOT at build time
    @Bean
    SecureRandom secureRandom() {
        return new SecureRandom();
    }
}

Verifying and Debugging the Native Build

Native builds fail differently from JVM apps. Two habits save hours:

  • Test the AOT path on the JVM first. Run with the springAot mode or the generated context before doing the slow native-image step — most bean-wiring issues surface here in seconds.
  • Read the static-analysis errors. A ClassNotFoundException or No instances of X are allowed in the image heap at run time almost always means a missing reflection/resource hint or an accidental build-time initialization.

You can run the AOT-processed app on the JVM to validate the frozen context quickly:

# Run the AOT-optimized context on a regular JVM (fast feedback loop)
./mvnw spring-boot:run -Dspring-boot.run.profiles=default \
  -Dspring.aot.enabled=true

Quick Check: AOT and the Native Pipeline

Test your understanding of how Spring's AOT engine cooperates with GraalVM.

Recap: AOT Processing and the Native Pipeline

You now understand how Spring Boot 4 turns a dynamic application into a native executable:

  • Why native: millisecond startup and low memory, at the cost of slow builds and a closed-world assumption.
  • Spring AOT runs at build time, emitting bean-definition code, an ApplicationContextInitializer, and GraalVM reachability metadata; the bean set becomes frozen.
  • The pipeline: compile → process-aot → compile generated sources → native-image static analysis.
  • Hints: use RuntimeHintsRegistrar + @ImportRuntimeHints for custom needs, @RegisterReflectionForBinding for DTOs, and the tracing agent as a last resort for opaque libraries.
  • Watch out for build-time initialization freezing state; defer environment- and time-sensitive work to runtime beans.
  • Debug fast by running the AOT context on the JVM before the slow native build.

الأسئلة الشائعة

هل درس «معالجة AOT ومسار البناء الأصلي» مجاني؟

نعم — نص درس «معالجة AOT ومسار البناء الأصلي» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Spring Boot 4 Complete Guide، انتقل إلى CoddyKit PRO. تتضمن دورة Spring Boot 4 Complete Guide 4 دروس في المجموع.

ماذا ستتعلم في «معالجة AOT ومسار البناء الأصلي»؟

تعرّف على محرّك Spring للمعالجة المسبقة وابنِ صورًا أصلية باستخدام مجموعة أدوات GraalVM تتمرن على Spring Boot 4 Complete Guide مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Spring Boot 4 Complete Guide؟

لا تُشترط خبرة سابقة. Spring Boot 4 Complete Guide على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «معالجة AOT ومسار البناء الأصلي»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Spring Boot 4 Complete Guide هذا؟

نعم. كل درس في Spring Boot 4 Complete Guide يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

  1. معالجة AOT ومسار البناء الأصلي
  2. تلميحات وقت التشغيل للانعكاس والموارد
  3. مشاركة بيانات الفئات وضبط بدء تشغيل JVM
  4. تشخيص مشكلات التوافق الأصلي وإصلاحها
← العودة إلى Spring Boot 4 Complete Guide