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

البدء مع Micronaut IOC: الأساسيات

الهدف من هذا المقال تقديم مدخل شامل إلى حاوية Micronaut IOC – تفاصيلها وميزاتها وحالات استخدامها. يستعرض المقال حالات الاستخدام النموذجية ويشير إلى أفضل الممارسات في العمل مع الحاوية.

9 دقائق قراءة
MicronautJavaأطر العمل

الهدف من هذا المقال تقديم مدخل شامل إلى حاوية Micronaut IOC – تفاصيلها وميزاتها وحالات استخدامها. يستعرض المقال حالات الاستخدام النموذجية ويشير إلى أفضل الممارسات في العمل مع الحاوية. وإضافة إلى ذلك، يتضمن المقال قسماً من النصائح والتجربة الشخصية والخبرة العملية، موجّهاً بصورة خاصة إلى القرّاء القادمين من Spring Boot، لتسهيل الانتقال إلى Micronaut.

حاوية انعكاس التحكم (IOC)

حاوية IOC مسؤولة عن إنشاء الكائنات – مع حقن التبعيات التي أُعلنت لها مسبقاً – وعن إدارة هذه الكائنات بعد ذلك. تسمى هذه الكائنات beans، وتُبنى وفق تعريف يُقدَّم للحاوية. يمكننا الإعلان عنها إما بوسم فئاتنا على أنها beans أو بكتابة دوال مصنعية (factory methods). بهذه الطريقة تتولى الحاوية، لا شيفرتنا، مسؤولية تهيئة الكائنات.

تطبّق حاوية Micronaut IoC المواصفة JSR-330 وتستخدم الترجمة المسبقة (AOT) لإبقاء الاعتماد على الانعكاس (reflection) عند الحد الأدنى ولتقصير زمن بدء التطبيق، ما يجعلها خفيفة ومناسبة للترجمة الأصلية (native). وهي وحدة مستقلة عن بقية الإطار، فيمكن استخدامها بالطريقة نفسها التي تُستخدم بها Guice أو Dagger المعروفتان.

أنواع حقن التبعيات (DI)

كما في معظم حاويات IoC، يوفر Micronaut ثلاث طرق لحقن التبعيات باستخدام الوسم @Inject

المُنشئ (Constructor)

class Car {

    private final Engine engine;

    @Inject
    public Car(Engine engine) {
        this.engine = engine;
    }

إذا كانت الفئة تملك مُنشئاً واحداً فقط، فلا حاجة إلى الوسم @Inject، لأن الحاوية تختار ذلك المُنشئ من تلقاء نفسها. وعند وجود عدة مُنشئات، يجب وسم أحدها.

الدالة/دالة التعيين (Method/Setter)

class Car {

    private Engine engine;

    @Inject
    public void setEngine(Engine engine) {
        this.engine = engine;
    }

الحقل (Field)

class Car {

    @Inject
    Engine engine;

}

ومع ذلك يبقى الحقن عبر المُنشئ الخيار الأكثر توصية، لأنه يتيح اشتراط التبعيات لحظة إنشاء الكائن، ومع الكلمة المفتاحية final يمنح أماناً أقوى من القيم الفارغة (null). كما أن الحقن عبر المُنشئ يجعل الشيفرة أسهل في الاختبار، إذ يمكنك في اختبار الوحدة تمرير كائنات وهمية (mocks) دون حاوية IoC. أما الحقن عبر دالة التعيين أو الحقل فينبغي اعتباره الملاذ الأخير، ولا يُستخدم إلا حين لا يكون هناك خيار آخر.

التبعيات

فيما يلي الحد الأدنى من التبعيات اللازمة لتشغيل حاوية Micronaut IoC وأمثلة هذا الدليل. وبدلاً من ذلك يمكنك توليد مشروع تجريبي من micronaut.io/launch. تستخدم الأمثلة التالية الإصدار 3.8.2 من Micronaut وJDK 17.

Gradle

plugins {
id 'io.micronaut.library' version '1.3.2'
}

micronaut {
version("3.8.2")
}

...

dependencies {
annotationProcessor "io.micronaut:micronaut-inject-java"
implementation "io.micronaut:micronaut-inject"
implementation "io.micronaut:micronaut-runtime"
testImplementation "io.micronaut.test:micronaut-test-junit5"
testImplementation "org.junit.jupiter:junit-jupiter-engine:5.9.1"
}

النطاقات (Scopes)

بحسب مواصفة JSR-330، يتحدد دورة حياة الـ bean بنطاقه (Scope). يخبر النطاق حاوية IOC متى تنشئ الـ beans وكيف تتعامل مع الموجود منها، وفق قواعد محددة مسبقاً. يوفر Micronaut سبعة نطاقات – بعضها مأخوذ مباشرة من المواصفة، وأضاف مؤلفو الإطار البقية.

النطاقات المتاحة

  • Singleton - نطاق للـ bean الذي لا يجوز أن يكون له سوى نسخة واحدة،
    تُنشأ بصورة كسولة عند أول حقن لها
  • Context - نطاق قريب من singleton، لكن دورة حياته مرتبطة بـ BeanContext ويُنشأ الـ bean فيه بصورة مبكرة (eager) عند بدء السياق. يوصي المؤلفون باستخدام @Singleton خياراً افتراضياً؛ ولا تلجأ إلى @Context إلا إذا احتجت إلى تهيئة مبكرة، لأن له أثراً على بدء التطبيق
  • Prototype - نطاق الـ bean الافتراضي، وفيه يحصل كل حقن على نسخة جديدة
  • RequestScope - نطاق للـ bean الذي ترتبط دورة حياته بطلب HTTP؛ ويحتاج إلى وحدة HTTP
  • Infrastructure - نطاق للـ bean الحرج الذي لا يمكن استبداله بـ @Replaces. مفيد لمؤلفي المكتبات والإضافات
  • ThreadLocal - نطاق ينشئ نسخة مستقلة من الـ bean لكل خيط (thread)
  • Refreshable - نطاق تُحدَّث حالة الـ bean فيه عبر /refresh أو بنشر RefreshEvent

تذكّر أن نطاق الـ bean الافتراضي هو prototype، بخلاف Spring Boot الشائع حيث يكون Singleton هو الافتراضي. سنركّز على النطاقات الثلاثة الأخيرة، لأنها في رأيي ما يميز Micronaut عن حاويات IoC الشائعة الأخرى.

Infrastructure

تخيّل bean حرجاً يحسب مساحة مستطيل، ولا نريد أن يستبدله أحد لأن ذلك قد يعطّل التطبيق. لهذا نطبّق الوسم @Infrastructure.

@Infrastructure
public class RectangleAreaCalculator {

    public double calculate(double a, double b) {
        return a * b;
    }

ماذا لو حاول مستخدم تجاوز الـ bean بوضع @Replaces على فئة فرعية بتنفيذ خاطئ؟

@Singleton
@Replaces(RectangleAreaCalculator.class)
public class InvalidRectangleAreaCalculator extends RectangleAreaCalculator {

    @Override
    public double calculate(double a, double b) {
    return a - b;
    }

في الواقع لا يحدث شيء: لا يُنشأ الـ bean المسمى InvalidRectangleAreaCalculator ولا يُستخدم بدلاً من RectangleAreaCalculator.

@MicronautTest
class InfrastructureTest {

    @Inject
    RectangleAreaCalculator rectangleAreaCalculator;

    @Test
    void infrastructureBeanDoesNotGetReplaced() {
        Assertions.assertInstanceOf(RectangleAreaCalculator.class, rectangleAreaCalculator);
        Assertions.assertEquals(20, rectangleAreaCalculator.calculate(4, 5));
    }

ThreadLocal

قبل الانتقال إلى النطاق نفسه، من المفيد معرفة أن واجهة Java البرمجية تتضمن آلية ThreadLocal. فهي تضمن أن كل خيط يستدعي الدالة .get() الخاصة بـ ThreadLocal يتلقى نسخة كائن منفصلة خاصة به. يمكنك تخيلها كأنها HashMap يؤدي فيها الخيط دور المفتاح الضمني.

عند التهيئة، علينا تنفيذ واجهة وظيفية (functional interface) تُرجع دالتها القيمة الأولية.

    ThreadLocal<Integer> threadLocal = ThreadLocal.withInitial(() -> 27);

بعد ذلك تعطينا الدالة get() نسخة فريدة للخيط الحالي.

    Integer myUniqueInteger = threadLocal.get();

هنا تمثل القيمة الأولية تعريف الـ bean لدينا. داخلياً، يُنفَّذ هذا النطاق بوكيل (proxy) يحتفظ بمتغير ThreadLocal ويمرر استدعاءات الدوال إلى النسخة الصحيحة. وبفضل ذلك يمكن مشاركة الـ bean بين beans أخرى تعمل في الخيط نفسه.

بعد استعراض النظرية، لننظر إلى مثال. سننشئ bean بسيطاً مهمته الوحيدة حمل String.

@ThreadLocal
public class ThreadLocalStorage {

    private String text;

    public String getText() {
        return text;
    }

    public void setText(String text) {
        this.text = text;
    }

وفقاً لفكرة نطاق ThreadLocal، ينبغي أن يشير كل خيط إلى نسخته الخاصة من الـ bean. ونتيجة لذلك، تُشارك قيمة الحقل “text” داخل خيط واحد فقط، كما يوضح الاختبار أدناه.

@MicronautTest
class ThreadLocalExampleTest {

    @Inject
    ThreadLocalStorage storage;

    @Test
    void test() {
        storage.setText("Main test thread");
        assertEquals("Main test thread", storage.getText());

        runBlockingInNewThread(() -> {
            assertNull(storage.getText()); (1)
            storage.setText("Sub-thread in test");
            assertEquals("Sub-thread in test", storage.getText());

            runBlockingInNewThread(() -> {
                assertNull(storage.getText());
                storage.setText("Sub-sub-thread in test");
                assertEquals("Sub-sub-thread in test", storage.getText());
            });

            assertEquals("Sub-thread in test", storage.getText()); (2)
        });

        assertEquals("Main test thread", storage.getText());
    }

    private void runBlockingInNewThread(Runnable runnable) throws RuntimeException {
        try {
            final var thread = new Thread(runnable);
            thread.start();
            thread.join();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

}

(1) يجب ألا يرى هذا الخيط النص الذي عُيّن في خيط الاختبار الرئيسي، لذا ينبغي أن تكون القيمة null.

(2) نتحقق من أن الخيط الداخلي لم يكتب فوق القيمة.
يبين الاختبار أعلاه أن ترتيب استدعاءات الدوال على bean معين غير مهم. فالحالة المنقولة بين الاستدعاءات لا تهم إلا داخل خيط واحد.

Refreshable

يتيح نطاق Refreshable تحديث حالة الـ bean لدينا. عملياً، تُستدعى الدالة الموسومة بـ @PostConstruct على الـ bean مرة أخرى. من الاستخدامات الممكنة لهذا النطاق إعادة تحميل إعدادات الـ bean أو مسح الذاكرة المؤقتة أو إطلاق أي أثر جانبي آخر. هل سأعتمد عليه في الممارسة؟ هذا يستحق مقالاً مستقلاً، لكن الخيار موجود.

في المثال سنكتب فئة تسمى RefreshableSeed فيها الدالة init() والدالة latestSeed().

@Refreshable
public class RefreshableSeed {

    private int seed;

    @PostConstruct
    public void init() {
    seed = new Random().nextInt();
    }

    public int latestSeed() {
    return seed;
    }

كما ذُكر سابقاً، هناك طريقتان لتحديث الحالة. إحداهما نقطة النهاية /refresh التي يعرّفها Micronaut جاهزة، لكنها تحتاج إلى وحدة HTTP

Publishing RefreshEvent using ApplicationEventPublisher
eventPublisher.publishEvent(new RefreshEvent());

للاختبار والعرض التوضيحي سنعتمد أسلوب ناشر الأحداث (event publisher).

@MicronautTest
class RefreshableSeedTest {

    @Inject
    RefreshableSeed refreshableSeed;

    @Inject
    ApplicationEventPublisher<RefreshEvent> eventPublisher;

    @Test
    void refreshableBeanGetsRefreshedWithRefreshEvent() {
        final var firstSeed = refreshableSeed.latestSeed();

        // Should not change before event
        assertEquals(firstSeed, refreshableSeed.latestSeed());

        eventPublisher.publishEvent(new RefreshEvent());

        assertNotEquals(firstSeed, refreshableSeed.latestSeed());
    }

يبين الاختبار أعلاه أن إطلاق الحدث غيّر حالة الـ bean فقط.

القادمون من Spring

كثير ممن يتعلمون Micronaut عملوا سابقاً مع Spring. ويعرف مؤلفو الإطار ذلك أيضاً، لذا يبنون وحدات مخصصة مثل Micronaut for Spring لتسهيل ترحيل التطبيقات القائمة إلى منظومة Micronaut. عيب مثل هذه الوحدة أنها تحل المشكلة جزئياً فقط، إذ ينتهي بك الأمر إلى مزج شيفرة من إطارَي عمل مختلفين. وفي رأيي ليست هذه الوحدات أفضل طريق، ولذلك سأبرز بدلاً منها الفروق الأساسية المهمة لمطوري Spring.

يختلف النطاق الافتراضي

الفرق الأكبر أن النطاق الافتراضي لحاوية Micronaut هو Prototype، وهو اسم بديل لـ @Bean، وليس Singleton كما في Spring Boot. أوصي بأن تكون صريحاً وأن تستخدم الوسوم التي تحدد النطاق فعلاً، مثل @Singleton أو @Prototype، بدلاً من الاعتماد على الإعدادات الافتراضية.

نطاق Singleton لا يتصرف بالطريقة نفسها

يختلف نطاق Singleton عن نظيره في Spring Boot. ففي Micronaut يكون Singleton كسولاً افتراضياً – فلا يُنشأ عند بدء السياق، بل عند الحاجة إليه فقط. أما المقابل الحقيقي لـ @Scope(“Singleton”) من Spring Boot فهو @Context. وهذا اختيار متعمد: بناه المؤلفون هكذا لتقليص زمن بدء التطبيق أكثر. لهذا السبب، استخدم التهيئة المبكرة فقط عندما تكون لديك أسباب أو مبررات وجيهة فعلاً.

Spring Boot Micronaut
@Component @Context
@Lazy @Component @Singleton

Singleton المبكر في Micronaut

كما ذُكر سابقاً، التهيئة الكسولة لـ singleton هي النهج المفضل وينبغي أن تكون خيارك الأول. أما إذا كان لديك سبب للتهيئة المبكرة، فهناك عدة خيارات.

  1. تطبيق نطاق @Context
  2. ضبط سياق الـ beans، وهو ما ينطبق مع ذلك على كل singleton
public class MicronautApp {

    public static void main(String[] args) {
        Micronaut.build(args)
            .eagerInitSingletons(true)
            .mainClass(Application.class)
            .start();
    }
}
  1. الجمع بين الوسم @Parallel والوسم @Singleton

ورقة مرجعية للوسوم

أعددت أيضاً ورقة مرجعية قصيرة بالوسوم الشائعة الاستخدام في Spring Boot لمساعدتك على إيجاد ما يقابلها في Micronaut.

Spring Micronaut
@Component المقابل المباشر 1:1 هو @Context، لكن فضّل @Singleton. واحتفظ بـ Context للحالات التي تكون فيها التهيئة المبكرة ضرورية فعلاً.
@Service المقابل المباشر 1:1 هو @Context، لكن فضّل @Singleton. واحتفظ بـ Context للحالات التي تكون فيها التهيئة المبكرة ضرورية فعلاً.
@Repository @Repository
@RestController @Controller
@Bean المقابل المباشر 1:1 هو @Context، لكن فضّل @Singleton. واحتفظ بـ Context للحالات التي تكون فيها التهيئة المبكرة ضرورية فعلاً.@Bean لا يقابله شيء، لأن النطاق الافتراضي في Micronaut هو @Prototype
@Scope @Singleton @Context @Prototype @Infrastructure @ThreadLocal @Refreshable @RequestScope
@Autowired @Inject
@Value @Value
@Qualifier @Named
@Configuration @Factory
@Profile(“test”) @Requires(env=“test”)
@Import @Import
@Primary @Primary

الخلاصة

آمل أن يكون هذا المقال مفيداً لك وأن يكون قد قدّم لك مدخلاً أساسياً متيناً إلى IoC في Micronaut، أياً كانت خبرتك السابقة مع Spring Framework. في تدوينتنا القادمة سنستكشف حاويات الـ beans والـ beans الشرطية وكيف يمكن استخدامها. ترقبوا!