تقدير المشروع
← كل المقالات

ترحيل تطبيق Spring Boot إلى صورة أصلية (native image) – كيف يتم ذلك؟

تعرّف على دعم GraalVM Native Image ورحّل تطبيق Spring Boot معقدًا – تطبيق RealWorld الذي يتجاوز كثيرًا مثال 'Hello World' البسيط.

15 دقائق قراءة
JavaSpring BootRealWorldGraalvmKotlin

نتناول هذه المرة دعم GraalVM Native Image. كُتبت مقالات كثيرة عن هذه الميزة. للأسف، كثير منها قديم، لأن الصور الأصلية لتطبيقات spring boot كانت تُولَّد سابقًا بوحدة spring-native التي أُهملت لاحقًا. وفوق ذلك، تعرض معظم المواد توليد الصورة الأصلية على تطبيقات بسيطة جدًا، وهذا قد يخفي بعض التفاصيل. سنوضح هنا كيف تُجرى هذه العملية لتطبيق أكبر من hello world.

ما الخطة؟

كما ذكرنا، هدفنا أن نبيّن كيف نرحّل تطبيق spring boot إلى تطبيق أصلي (native). قد تتساءل: «لماذا أريد أن يعمل تطبيقي كصورة أصلية؟». حسنًا… الدافعان الرئيسيان هما سرعة بدء التطبيق (من لا يريد تطبيقًا إنتاجيًا يبدأ في أجزاء من الثانية) وبصمة ذاكرة أصغر. لهذا النهج سلبياته أيضًا، وأثناء عملنا على الترحيل سترى بنفسك أين أكبر نقاط الألم. لكن لنعد إلى الخطة.

بدايةً نحتاج إلى تطبيق نرحّله، ويجب أن يكون تطبيقًا حقيقيًا لا hello world تافهًا. فالتطبيق البسيط أكثر من اللازم قد يخفي بعض التفاصيل الجوهرية. وبدلًا من كتابته من الصفر، سنأخذ أحد تطبيقات RealWorld الذي يعتمد على وحدات spring boot كثيرة. يتيح لنا هذا التركيز حصريًا على التغييرات اللازمة لتصريف التطبيق إلى تطبيق أصلي. وهناك مرشح مثالي للترحيل: تنفيذ مجتمعي يعمل على java 17 وspring boot 3.0. سنكيّف هذا التطبيق بحيث يمكن بناء صورة أصلية منه. يعتمد التطبيق على وحدات كثيرة شائعة في مشاريعنا، مثل spring-boot-starter-jpa وspring-boot-starter-security وspring-boot-starter-web وhibernate وقاعدة بيانات h2 وأدوات أصغر مثل Lombok، لذا ينبغي أن يكفي لإظهار المشكلات التي قد تظهر أثناء الترحيل.

بعد ذلك سنمر على الترحيل معًا، ونعرض أفضل الممارسات وطرق حل بعض مشكلات الترحيل التي قد تواجهها في تطبيقاتك.

قبل الترحيل

إذا كنت تنوي بناء تطبيق spring boot الخاص بك كصورة أصلية، فابدأ بمراجعة هذه الوثيقة عن القيود المعروفة للتحقق مما إذا كان تطبيقك يعتمد على شيء مذكور فيها. وإذا كان في تطبيقك شيء غير مدعوم بعد، فيمكنك إما انتظار الدعم الرسمي أو استبدال ذلك الشيء بشيء آخر. فمثلًا، بما أن log4j2 لا يعمل في الصور الأصلية، عليك التحول إلى logback قبل أن تحاول بناء الصورة الأصلية أصلًا.

خطوات الترحيل

تأخذك الأقسام التالية عبر عملية الترحيل خطوة بخطوة.

بنية تطبيقنا

أولًا، لنتعرف قليلًا على بنية التطبيق:

├── api
├── build
├── build.gradle.kts
├── database
├── gradle
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
└── src
  • api - يحتوي على تعريف open api، وطلبات إلى واجهتنا بصيغة مجموعة postman، وسكربت صغير يختبر الواجهة باستخدام newman؛ وسنستخدمه لاختبار التطبيق
  • build - المجلد الذي يحوي جميع نواتج البناء
  • build.gradle.kts, settings.gradle.kts - إعدادات مشروع gradle المكتوبة بـ kotlin dsl (بالمناسبة، هل كنت تعلم أن kotlin dsl أصبحت الافتراضية لعمليات بناء gradle الجديدة؟)
  • gradle, gradlew, gradlew.bat - غلاف gradle (wrapper)
  • database - المجلد الذي يحوي مخطط قاعدة البيانات
  • src - الشيفرة المصدرية للتطبيق

المتطلبات المسبقة

لبناء الصور الأصلية باستخدام Native Build Tools نحتاج إلى توزيعة GraalVM. أرجوك، أرجوك، أدِر توزيعاتك باستخدام sdkman بدلًا من تنزيلها يدويًا. سنستخدم توزيعة Liberica المبنية على GraalVM، الإصدار 22.3.2.r17

$ sdk install java 22.3.2.r17-nik
$ sdk use java 22.3.2.r17-nik

شغّل تطبيقك مع تفعيل AOT

بدلًا من الانتقال مباشرة إلى تصريف الصورة الأصلية، ينبغي أن نتحقق أولًا من أن التطبيق يعمل بشكل صحيح على JVM باستخدام شيفرة التهيئة المولَّدة بتقنية AOT. بهذه الطريقة تظهر الأخطاء المحتملة أبكر بكثير مما لو شغّلنا عملية تصريف الصورة الأصلية كاملة.

للبدء علينا تفعيل توليد شيفرة التهيئة. لماذا؟ كما تعلم على الأرجح، يؤدي spring قدرًا كبيرًا من العمل عند بدء التطبيق، ولا يمكن حدوث أي من ذلك العمل وقت التشغيل إذا أردت صورة أصلية. ولهذا توجد مرحلة توليد شيفرة التهيئة: كل ما يفعله تطبيق spring العادي وقت التشغيل يُترجم إلى شيفرة تُولَّد وقت البناء.

حسنًا، لتوليد هذه الشيفرة بـ gradle، كل ما علينا هو إضافة الإضافة org.graalvm.buildtools.native إلى قسم الإضافات:

plugins {
    java
    id("com.diffplug.spotless") version "6.18.0"
    id("org.springframework.boot") version "3.0.5"
    id("io.spring.dependency-management") version "1.1.0"
    id("org.graalvm.buildtools.native") version "0.9.20"
}

بعد ذلك نبني التطبيق:

$ ./gradlew build

وها هو ذا خطؤنا الأول البسيط:

Execution failed for task ':spotlessJavaCheck'.
> The following files had format violations:
      build/generated/aotSources/com/github/gavlyukovskiy/boot/jdbc/decorator/DataSourceDecoratorAutoConfiguration__BeanDefinitions.java

يبدو أن spotless يفحص أصنافي المولَّدة في مجلد البناء أيضًا… تعديل صغير على إعدادات spotless يوقف ذلك:

spotless {
    java {
        target("src/main/java/**/*.java")
        palantirJavaFormat()
        indentWithSpaces()

يمكننا الآن تشغيل ./gradlew build مرة أخرى. يُبنى التطبيق الآن مع تضمين الشيفرة المولَّدة بـ AOT. لنحاول تشغيله باستخدام شيفرة التهيئة المولَّدة بـ AOT، وهذا يتم بتفعيل الخاصية spring.aot.enabled.

$ java -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar

في بداية السجلات تمامًا ينبغي أن نرى أن التطبيق المعالَج بـ AOT يبدأ:

Starting AOT-processed RealworldApplication using Java 17.0.7 with PID....

وللتأكد من أن كل شيء سليم، يمكننا تشغيل اختبارات الواجهة:

$ ./api/run-api-tests.sh

يبدو أن كل شيء يعمل. حتى الآن كل شيء على ما يرام.

لننتقل إلى الأصلي (native)

المحاولة الأولى

بمجرد أن يعمل تطبيقك بسلاسة مع شيفرة AOT المولَّدة، يمكننا محاولة بنائه في الوضع الأصلي. لكن… هذا على الأرجح ليس ما ينبغي أن تفعله أولًا. وإليك السبب. لبدء التصريف الأصلي، كل ما نحتاج إلى تشغيله هو:

$ ./gradlew nativeCompile

حان وقت القهوة… تستغرق العملية بضع دقائق.

المصدر

BUILD SUCCESSFUL in 4m 24s

أخيرًا، صورتنا الأصلية جاهزة!!!! لنشغّلها!

$ ./build/native/nativeCompile/realworld

وانهارت…

Caused by: java.lang.ExceptionInInitializerError: null
        at com.github.gavlyukovskiy.boot.jdbc.decorator.p6spy.P6SpyConfiguration.init(P6SpyConfiguration.java:112) ~[realworld:na]

إذن في مكان ما بين اعتمادياتنا توجد شيفرة فشلت في تهيئة بعض المتغيرات. وهذا يترك كائنًا null يُستخدم لاحقًا في الشيفرة – ومن هنا جاء NullPointerException. لماذا لم تحدث التهيئة؟ لنعد إلى نقطة البداية…

السبب الرئيسي لرغبتنا في تطبيق أصلي أنه يمنحنا ميزتين رائعتين: بدء سريعًا للتطبيق وبصمة ذاكرة صغيرة. ولتحقيقهما يعمل GraalVM بافتراض العالم المغلق (closed-world)، حيث يجب أن تكون كل الشيفرة معروفة وقت البناء. ولهذا يحتوي التطبيق النهائي فقط على الأصناف التي يستخدمها تطبيقنا فعلًا (بصمة ذاكرة صغيرة). إضافةً إلى ذلك، يعرف مصرّف native-image أثناء التصريف أيضًا أي الكائنات تُنشأ عند بدء التطبيق، فيملأ كومة (heap) مسبقًا بها – ومن هنا يأتي البدء السريع.

نعود إلى المشكلة. وقت البناء لم يستطع مصرّف native-image اكتشاف أننا نحمّل بعض الأصناف ديناميكيًا، فاستبعدها من التطبيق النهائي. والشيفرة المسؤولة عن تحميل تلك الأصناف عيّنت المتغير إلى null، وفي وقت التشغيل انتهى بنا الأمر إلى NullPointerException.

كيف نصلح ذلك؟ بما أن الصنف يُوصل إليه عبر الانعكاس (reflection)، علينا إخبار المصرّف بتحميله وقت البناء وإتاحته لتطبيقنا وقت التشغيل. ولهذا يجب أن نعرّف بيانات الوصول الوصفية (reachability metadata) في ملفات JSON. نعم… هذا ممكن، لكن ماذا يُفترض أن نضع في هذه الملفات؟ هل علينا تحليل كل مكتبة لنعرف ما تفعله؟!

استغرق البناء 5 دقائق للحصول على الخطأ الأول. يمكننا محاولة كتابة بيانات الوصول هذه بأنفسنا، وهذا سيستغرق بالتأكيد أكثر من 5 دقائق، ثم علينا إعادة تصريف التطبيق وتشغيله وإصلاح الأخطاء وإعادة التصريف والتشغيل وإصلاح الأخطاء… من لديه وقت لذلك؟ ترى الآن لماذا ليس هذا هو الطريق. في التطبيقات بهذا التعقيد يكاد يكون تعريف كل بيانات الوصول يدويًا مستحيلًا. هناك نهج أفضل.

شغّل وكيل التتبع (tracing agent) لجمع بيانات الوصول

بدلًا من كتابة بيانات الوصول يدويًا، يمكننا تشغيل التطبيق مع وكيل تتبع مرفق يجمعها كلها لنا. لكن بما أن البيانات تُجمع وقت التشغيل، علينا التأكد من تنفيذ كل مسارات الشيفرة في التطبيق، حتى يجمع الوكيل كل ما يلزم ولا تحمل الصورة الأصلية مفاجآت عند تشغيلها.

مرة أخرى نبني التطبيق كملف jar.

$ ./gradlew build

ثم نشغّل التطبيق مع إرفاق native-image-agent:

$ java -agentlib:native-image-agent=config-output-dir=./src/main/resources/META-INF/native-image/ -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar

لاحظ أننا مررنا إلى الوكيل خيار الإعداد config-output-dir=./src/main/resources/META-INF/native-image/: فبمجرد وصول بيانات الوصول إلى هذا المجلد، يلتقطها مصرّف الصورة الأصلية تلقائيًا عند تشغيل ./gradlew nativeCompile.

بعد ذلك علينا تحريك التطبيق ليتمكن الوكيل من جمع كل بيانات الوصول. ويمكننا لهذا استخدام اختبارات الواجهة الموجودة في المجلد ./api.

$ ./api/run-api-tests.sh

بعد إيقاف التطبيق، نرى إعدادات كثيرة في ملفات JSON داخل المجلد src/main/resources/META-INF/native-image. تخيّل أن تكتب كل ذلك يدويًا…

ابنِ صورة أصلية

صرنا جاهزين لبناء الصورة الأصلية. هيا بنا!

./gradlew nativeCompile

المصدر

BUILD SUCCESSFUL in 4m 46s

والآن لنشغّلها!

$ ./build/native/nativeCompile/realworld

إنها حية!!! أخيرًا تعمل. انظر كم بدأت بسرعة! نصف ثانية لتطبيق spring boot؟ مذهل!

Started RealworldApplication in 0.453 seconds (process running for 0.463)

لكن مهلًا – لنشغّل اختبارات الـ API للتأكد من أن كل شيء سليم.

$ ./api/run-api-tests.sh

للأسف، هناك بعض الأخطاء…

|                    | executed | failed |
|--------------------|----------|--------|
| iterations         | 1        | 0      |
| requests           | 32       | 0      |
| test-scripts       | 48       | 2      |
| prerequest-scripts | 18       | 0      |
| assertions         | 194      | 69     |

يبدو أن Hibernate هو سبب المشكلة:

Caused by: org.hibernate.HibernateException: Generation of HibernateProxy instances at runtime is not allowed when the configured BytecodeProvider is 'none'; your model requires a more advanced BytecodeProvider to be enabled.

حسنًا، حاول hibernate توليد وكلاء (proxies) – لتتبع التغييرات (dirty checking) أو التهيئة الكسولة (lazy initialization) مثلًا – لكن هذا غير ممكن في صورة أصلية، لأن مزوّد الشيفرة البايتية (bytecode provider) في hibernate بأكمله يجب أن يُعطَّل. فالتلاعب بالشيفرة البايتية وقت التشغيل غير وارد.

مقطع شيفرة من org.springframework.orm.jpa.vendor.SpringHibernateJpaPersistenceProvider

static {
    if (NativeDetector.inNativeImage()) {
        System.setProperty(Environment.BYTECODE_PROVIDER, Environment.BYTECODE_PROVIDER_NAME_NONE);
    }
}

لا يتبقى لنا سوى خيار واحد: تعطيل توليد وكلاء hibernate وقت التشغيل أيضًا، وتوليد كل الوكلاء وقت البناء بدلًا من ذلك. توجد إضافة gradle مخصصة لهذا: Hibernate Enhance Plugin. وخياراتها موضحة في مقالة ممتازة لـ Vlad Mihalcea. يتطلب توليد هذه الشيفرة وقت البناء تغييرين في build.gradle.kts. أولًا، أضف هذا إلى الإضافات:

id("org.hibernate.orm") version ("6.2.2.Final")

ثم اضبط تحسينات الشيفرة:

hibernate {
    enhancement {
        enableDirtyTracking.set(true)
        enableLazyInitialization.set(true)
        enableExtendedEnhancement.set(false)
    }
}

يمكننا الآن المرور بالدورة الكاملة مجددًا للتحقق من أن كل شيء يعمل: نبني تطبيقًا عاديًا، ونشغّله مع native-image-agent، ونشغّل الاختبارات لجمع بيانات الوصول، وفي النهاية نبني الصورة الأصلية.

لكن قبل ذلك تلزم خطوة إضافية لحل كل مشكلات hibernate. فمزوّد الشيفرة البايتية (الذي يستخدمه hibernate) يجب تعطيله أيضًا عند تشغيل التطبيق العادي. وذلك لسببين: نريد أن يتصرف التطبيق العامل مع الوكيل تمامًا كما سيتصرف في بيئة أصلية، ونريد أن يعمل التطبيق العادي بالطريقة نفسها التي يعمل بها التطبيق الأصلي، حتى تظهر الأخطاء التي قد تحدث في بيئة أصلية أبكر بكثير أثناء اختبار التطبيق العادي.

ولهذا يمكننا وضع hibernate.properties في src/main/resources بالإعدادات التالية:

hibernate.bytecode.provider=none
hibernate.bytecode.use_reflection_optimizer=false

يعطّل السطر الثاني ReflectionOptimizer، لأنه من دون تعطيله تفشل اختباراتنا بهذا الاستثناء:

org.hibernate.HibernateException: Using the ReflectionOptimizer is not possible when the configured BytecodeProvider is 'none'. Disable hibernate.bytecode.use_reflection_optimizer or use a different BytecodeProvider

حسنًا، حان وقت المرور بالدورة الكاملة (بناء تطبيق عادي، وتشغيله مع native-image-agent، وتشغيل الاختبارات لجمع بيانات الوصول، وبناء صورة أصلية) مرة أخرى…

المصدر

نشغّل التطبيق وها هو خطأ آخر… هذا مرهق…

Caused by: com.oracle.svm.core.jdk.UnsupportedFeatureError: No classes have been predefined during the image build to load from bytecodes at runtime.
        at org.graalvm.nativeimage.builder/com.oracle.svm.core.util.VMError.unsupportedFeature(VMError.java:89) ~[na:na]
        at org.graalvm.nativeimage.builder/com.oracle.svm.core.hub.PredefinedClassesSupport.throwNoBytecodeClasses(PredefinedClassesSupport.java:76) ~[na:na]
        at org.graalvm.nativeimage.builder/com.oracle.svm.core.hub.PredefinedClassesSupport.loadClass(PredefinedClassesSupport.java:130) ~[na:na]
        at java.base@17.0.7/java.lang.ClassLoader.defineClass(ClassLoader.java:294) ~[realworld:na]
        at net.bytebuddy.utility.dispatcher.JavaDispatcher$DynamicClassLoader.invoker(JavaDispatcher.java:1383) ~[na:na]

يقول هذا الخطأ إن إضافة التحسين تتلاعب بالشيفرة البايتية وقت التشغيل. لكن التلاعب بالشيفرة البايتية وقت التشغيل غير مسموح – فbytebuddy معطّل. فكيف نتعامل مع هذا؟

الحل هو إحدى الميزات التجريبية في GraalVM: دعم الأصناف المعرَّفة مسبقًا (Support for Predefined Classes). لذلك سنعدّل الأمر الذي يشغّل التطبيق مع native-image-agent.

وهذه هي النسخة المحدّثة:

$ java -agentlib:native-image-agent=config-output-dir=./src/main/resources/META-INF/native-image/,**experimental-class-define-support** -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar

بهذا يخزّن native-image-agent بعض الشيفرة البايتية كبيانات وصول في المجلد src/main/resources/META-INF/native-image، ويمكننا محاولة بناء التطبيق.

لكن إن فعلنا ذلك، فإن JaCoCo يسبب مشكلة هذه المرة. JaCoCo محلل لتغطية الاختبارات يعمل بتزويد الشيفرة البايتية بأدوات قياس. وبما أننا نولّد الآن شيفرة بايتية داخل ./src/main/resources، فإنه يبدأ بتحليل تلك الشيفرة أيضًا ويرمي خطأ يقول إن أصنافًا بالاسم نفسه قد حُلّلت من قبل (صنف واحد جاء من المصادر العادية والآخر من بيانات الوصول). أبسط حل بديل هو وضع الشيفرة المولَّدة في مكان آخر، لكن عندها يجب إعادة ضبط native-image لقراءة بيانات الوصول من مجلد مختلف.

لننشئ مجلد aot في جذر المشروع ونعيّنه مجلد إخراج لـ native-image-agent

$ java -agentlib:native-image-agent=config-output-dir=**./aot/META-INF/native-image/**,experimental-class-define-support -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar

بعد ذلك يجب إضافة المجلد aot إلى مسار الأصناف (classpath) لأداة native-image. نفعل ذلك في build.gradle.kts

graalvmNative {
    binaries {
        names.forEach { binaryName ->
            named(binaryName){
                classpath("./aot/")
            }
        }
    }
}

يضيف هذا المجلد aot إلى مسار الأصناف لكل ملف ثنائي – وفي حالتنا main وtest.

صرنا جاهزين لبناء التطبيق. تذكّر أن الدورة الكاملة يجب أن تتكرر. هل تفضّل فنجان قهوة ثانيًا؟

بعد دورة بناء أخرى (فقدتُ العدّ لعدد مرات مروري بها)، يمكننا تشغيل التطبيق مع اختبارات الواجهة، ويبدو أن كل شيء يعمل! يبدأ التطبيق في نصف ثانية – نجاح كبير.

Started RealworldApplication in 0.448 seconds (process running for 0.456)

لكننا لم ننتهِ بعد. لنتأكد فعلًا من أن التطبيق يعمل بشكل صحيح كصورة أصلية، يجب تشغيل اختبارات الوحدة في البيئة الأصلية. يكفي لذلك هذا الأمر البسيط.

./gradlew nativeTest

يبدو أن الاختبارات تفشل لأننا نستخدم mockito – هل تذكر القيود المعروفة؟

بعد إزالة mockito وبعض مطابقات hamcrest، يمكننا إعادة تشغيل الاختبارات الأصلية، وهذه المرة ينجح كل شيء. أعدكم بذلك!

يا لها من رحلة طويلة!

أفكار ختامية

كما رأيت، يمكن لتطبيقات spring boot الواقعية أن تعمل كصور أصلية، لكن ذلك ليس سهلًا، والوصول إلى شيء يعمل يستغرق وقتًا طويلًا. كما ينبغي دمج هذا التدفق بأكمله في خط CI، وقد يثبت أن ذلك صعب أيضًا.

وهذه مقارنة سريعة بين تطبيقنا العامل كصورة أصلية وكتطبيق Java عادي.

|                     | startup time | occupied memory (rss) |
|---------------------|--------------|-----------------------|
| regular application | ~3 seconds   | 500 Mb                |
| native application  | ~0.5 second  | 200 Mb                |

في التطبيقات الأكبر سيكون الفارق في زمن البدء واستهلاك الذاكرة أكبر.

الأرقام تبدو رائعة، فما العيب؟ للتحول إلى الصورة الأصلية هذه السلبيات الرئيسية:

  • بناء الصورة الأصلية أبطأ بكثير من البناء العادي – إذ يُبنى التطبيق العادي في ~20 ثانية فقط بتوزيعة temurin من Java 17، فـ 5 دقائق مقابل 20 ثانية فرق هائل،
  • ليست كل المكتبات تعمل في بيئة أصلية بعد (القيود المعروفة),
  • لا يوجد دعم لـ JVMTI ولا لوكلاء Java ولا JMX ولا JFR. ولا يتبقى سوى ميزات النواة لفحص ما يجري داخل التطبيق. وهذا يعني أيضًا أن مقاييس كومة jvm التي تُجمع عبر MXBeans (بواسطة micrometer مثلًا) غير متاحة. وبشكل عام لا تتوفر أي مقاييس تُجمع من MXBeans,
  • في النسخة المجتمعية من GraalVM، serialGC هو مجمّع النفايات الوحيد المتاح. يمكن استخدام G1 GC، لكن فقط في النسخة المؤسسية من GraalVM التي تأتي مع اشتراك Oracle Java SE,
  • لا يوجد JIT، لذا سيكون معدل إنتاجية تطبيقك أقل.

هذا كل شيء يا جماعة. آمل أن تساعدك هذه المقالة في الترحيل إلى الصورة الأصلية – فقط تذكّر أن «تختار مقاتلك بحكمة»

حان وقت إغلاق كل علامات التبويب المفتوحة لديّ… شعور رائع، أليس كذلك؟

مصادر إضافية تستحق القراءة إن أردت التعمق.

  1. Everything You Never Wanted to Know About Spring Boot 3 AOT
  2. توثيق أداة Native image
  3. GraalVM medium