بادر بإنشاء أول تطبيق للجهات الفاعلة الموثوقة Java Service Fabric على Linux

مقالة
06/01/2023

يساعدك هذا التشغيل السريع على إنشاء أول تطبيق Azure Service Fabric Java في بيئة تطوير Linux في بضع دقائق فقط. عند الانتهاء، سيكون لديك تطبيق Java بسيط أحادي الخدمة يعمل على نظام مجموعة التطوير المحلية.

المتطلبات الأساسية

قبل البدء، بادر بتثبيت عدة Service Fabric SDK وService Fabric CLI وYeoman وبادر بإعداد بيئة تطوير Java، وبإعداد نظام مجموعة تطوير في بيئة تطوير Linux خاصتك. إذا كنت تستخدم نظام التشغيل Mac X، فيمكنك إعداد بيئة تطوير على نظام التشغيل Mac باستخدام Docker.

ثبت Service Fabric CLIأيضاً.

تركيب وإعداد مُنشئي Java

توفر "Service Fabric" أدوات التدعيم التي تساعدك على إنشاء تطبيق "Service Fabric Java" من terminal باستخدام مُنشئي قالب Yeoman. إذا لم يكن Yeoman مثبتاً بالفعل، فراجع بدء استخدام Service Fabric بـ Linux للحصول على إرشادات عن إعداد Yeoman. بادر بتشغيل الأمر التالي لتثبيت منشئي قالب Service Fabric Yeoman لـ Java.

npm install -g generator-azuresfjava

المفاهيم الأساسية

لبدء استخدام الجهات الفاعلة الموثوقة، ما عليك سوى فهم بعض المفاهيم الأساسية:

خدمة الجهات الفاعلة. يتم تجميع الجهات الفاعلة الموثوقة في خدمات موثوقة يمكن توزيعها في البنية الأساسية لـ Service Fabric. يتم تنشيط مثيلات الجهات الفاعلة في مثيل خدمة مُسمى.
تسجيل الجهات الفاعلة. كما هو الحال مع الخدمات الموثوقة، يجب تسجيل خدمة الجهات الفاعلة الموثوقة في وقت تشغيل «Service Fabric». بالإضافة إلى ذلك، يجب تسجيل نوع الجهة الفاعلة في وقت تشغيل الجهة الفاعلة.
واجهة الجهة الفاعلة. يتم استخدام واجهة الجهة الفاعلة لتحديد واجهة عامة مكتوبة بقوة لإحدى الجهات الفاعلة. في مصطلحات نموذج الجهات الفاعلة الموثوق، تحدد واجهة الجهة الفاعلة أنواع الرسائل التي يمكن للجهة الفاعلة فهمها ومعالجتها. يتم استخدام واجهة الجهة الفاعلة من قبل غيرها من الجهات الفاعلة وتطبيقات العميل "لإرسال" رسائل (غير متزامنة) إلى الجهة الفاعلة. يمكن للجهات الفاعلة الموثوقة تنفيذ واجهات متعددة.
فئة ActorProxy. يتم استخدام فئة ActorProxy بواسطة تطبيقات العميل لاستدعاء الأساليب المكشوفة من خلال واجهة الجهة الفاعلة. توفر فئة ActorProxy وظيفتين مهمتين:
- تحليل الاسم: يمكنه تحديد موقع الجهة الفاعلة في نظام المجموعة (ابحث عن عُقدة نظام المجموعة حيث يتم استضافتها).
- معالجة الفشل: يمكنه إعادة محاولة استدعاءات الأسلوب وإعادة حل موقع الجهة الفاعلة بعد، على سبيل المثال، الفشل الذي يتطلب نقل الجهة الفاعلة إلى عُقدة أخرى في نظام المجموعة.

القواعد التالية التي تتعلق بواجهات الجهات الفاعلة جديرة بالذكر:

لا يمكن تحميل أساليب واجهة الجهة الفاعلة بدرجةٍ زائدةٍ.
يجب ألا تحتوي أساليب واجهة الجهة الفاعلة على معلمات خارجية أو مرجعية أو اختيارية.
الواجهات العامة غير مدعومة.

إنشاء التطبيق

يحتوي تطبيق "Service Fabric" على خدمة واحدة أو أكثر، لكل منها دور محدد في تقديم وظائف التطبيق. يُسهل المُنشئ الذي ثبتَّه في القسم الأخير إنشاء خدمتك الأولى وإضافة المزيد لاحقاً. يمكنك أيضاً إنشاء تطبيقات Service Fabric Java وبنائها وتوزيعها باستخدام مكون إضافي لـ Eclipse. راجع إنشاء تطبيق Java الأول خاصتك وتوزيعه باستخدام Eclipse. لهذا التشغيل السريع، استخدم Yeoman لإنشاء تطبيق بخدمة واحدة تخزن قيمة عداد وتحصل عليها.

في terminal، اكتب yo azuresfjava.
قم بتسمية تطبيقك.
اختر نوع خدمتك الأولى وبادر بتسميتها. لهذا البرنامج التعليمي، اختر خدمة جهات فاعلة موثوقة. لمزيدٍ من المعلومات عن الأنواع الأخرى من الخدمات، راجع نظرة عامة على نموذج برمجة "Service Fabric".

إذا قمت بتسمية التطبيق "HelloWorldActorApplication" والجهة الفاعلة "HelloWorldActor"، يتم إنشاء الدُعامات التالية:

HelloWorldActorApplication/
├── build.gradle
├── HelloWorldActor
│   ├── build.gradle
│   ├── settings.gradle
│   └── src
│       └── reliableactor
│           ├── HelloWorldActorHost.java
│           └── HelloWorldActorImpl.java
├── HelloWorldActorApplication
│   ├── ApplicationManifest.xml
│   └── HelloWorldActorPkg
│       ├── Code
│       │   ├── entryPoint.sh
│       │   └── _readme.txt
│       ├── Config
│       │   ├── _readme.txt
│       │   └── Settings.xml
│       ├── Data
│       │   └── _readme.txt
│       └── ServiceManifest.xml
├── HelloWorldActorInterface
│   ├── build.gradle
│   └── src
│       └── reliableactor
│           └── HelloWorldActor.java
├── HelloWorldActorTestClient
│   ├── build.gradle
│   ├── settings.gradle
│   ├── src
│   │   └── reliableactor
│   │       └── test
│   │           └── HelloWorldActorTestClient.java
│   └── testclient.sh
├── install.sh
├── settings.gradle
└── uninstall.sh

كتل البناء الأساسية للجهات الفاعلة الموثوقة

تُفسَّر المفاهيم الأساسية الموصوفة سابقاً إلى كتل البناء الأساسية لخدمة الجهات الفاعلة الموثوقة.

واجهة الجهة الفاعلة

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

HelloWorldActorInterface/src/reliableactor/HelloWorldActor.java:

public interface HelloWorldActor extends Actor {
    @Readonly   
    CompletableFuture<Integer> getCountAsync();

    CompletableFuture<?> setCountAsync(int count);
}

خدمة الجهات الفاعلة

يحتوي هذا على التعليمة البرمجية الخاصة بتنفيذ الجهة الفاعلة وتسجيل الجهة الفاعلة. فئة الجهة الفاعلة تنفذ واجهة الجهة الفاعلة. هذا هو المكان الذي تباشر فيه جهتك الفاعلة عملها.

HelloWorldActor/src/reliableactor/HelloWorldActorImpl:

@ActorServiceAttribute(name = "HelloWorldActorService")
@StatePersistenceAttribute(statePersistence = StatePersistence.Persisted)
public class HelloWorldActorImpl extends FabricActor implements HelloWorldActor {
    private Logger logger = Logger.getLogger(this.getClass().getName());

    public HelloWorldActorImpl(FabricActorService actorService, ActorId actorId){
        super(actorService, actorId);
    }

    @Override
    protected CompletableFuture<?> onActivateAsync() {
        logger.log(Level.INFO, "onActivateAsync");

        return this.stateManager().tryAddStateAsync("count", 0);
    }

    @Override
    public CompletableFuture<Integer> getCountAsync() {
        logger.log(Level.INFO, "Getting current count value");
        return this.stateManager().getStateAsync("count");
    }

    @Override
    public CompletableFuture<?> setCountAsync(int count) {
        logger.log(Level.INFO, "Setting current count value {0}", count);
        return this.stateManager().addOrUpdateStateAsync("count", count, (key, value) -> count > value ? count : value);
    }
}

تسجيل الجهات الفاعلة

يجب تسجيل خدمة الجهات الفاعلة بنوعٍ خدمة في وقت تشغيل Service Fabric. لكي تشغل خدمة الجهات الفاعلة مثيلات الجهات الفاعلة خاصتك، يجب أيضاً تسجيل نوع الجهة الفاعلة خاصتك في خدمة الجهات الفاعلة. يؤدي أسلوب التسجيل ActorRuntime هذا العمل للجهات الفاعلة.

HelloWorldActor/src/reliableactor/HelloWorldActorHost:

public class HelloWorldActorHost {

private static final Logger logger = Logger.getLogger(HelloWorldActorHost.class.getName());

public static void main(String[] args) throws Exception {

        try {

            ActorRuntime.registerActorAsync(HelloWorldActorImpl.class, (context, actorType) -> new FabricActorService(context, actorType, (a,b)-> new HelloWorldActorImpl(a,b)), Duration.ofSeconds(10));
            Thread.sleep(Long.MAX_VALUE);
        } catch (Exception e) {
            logger.log(Level.SEVERE, "Exception occurred", e);
            throw e;
        }
    }
}

إنشاء التطبيق

تتضمن قوالب Service Fabric Yeoman نصاً برمجياً للإنشاء لـ Gradle، والذي يمكنك استخدامه لإنشاء التطبيق من terminal. يتم جلب تبعيات Service Fabric Java من Maven. لإنشاء تطبيقات Service Fabric Java والعمل عليها، تحتاج إلى التأكد من تثبيت JDK وGradle. إذا لم يتم تثبيتها، فراجع بدء استخدام Service Fabric بـ Linux للحصول على إرشادات عن تثبيت JDK وGradle.

لإنشاء التطبيق وحزمه، بادر بتشغيل ما يلي:

cd HelloWorldActorApplication
gradle

نشر التطبيق

بمجرد إنشاء التطبيق، يمكنك توزيعه في الكتلة المحلية.

الاتصال بنظام المجموعة Service Fabric المحلي (يجب إعداد وتشغيلنظام المجموعة).
```
sfctl cluster select --endpoint http://localhost:19080
```
بادر بتشغيل نص التثبيت المتوفر في القالب لنسخ حزمة التطبيق إلى مخزن صور المجموعة، وتسجيل نوع التطبيق، وإنشاء مثيل للتطبيق.
```
./install.sh
```

يعد توزيع التطبيق المدمج هو نفسه مثل أي تطبيق Service Fabric آخر. راجع الوثائق الخاصة بإدارة تطبيق Service Fabric مع Service Fabric CLI للحصول على إرشادات مفصلة.

يمكن العثور على معلمات هذه الأوامر في البيانات التي تم إنشاؤها داخل حزمة التطبيق.

بمجرد توزيع التطبيق، افتح متصفحاً وانتقل إلى Service Fabric Explorer على http://localhost:19080/Explorer. ثم بادر بتوسيع عقدة التطبيقات ولاحظ أنه يوجد الآن إدخال لنوع التطبيق خاصتك وآخر للمثيل الأول من هذا النوع.

هام

لتوزيع التطبيق إلى كتلة Linux آمنة في Azure، تحتاج إلى تكوين شهادة للتحقق من صحة التطبيق خاصتك مع وقت تشغيل نسيج الخدمة. يؤدي القيام بذلك إلى تمكين خدمات الجهات الفاعلة الموثوقة خاصتك من التواصل مع واجهات برمجة تطبيقات وقت تشغيل Service Fabric الأساسية. لمعرفة المزيد، راجع تكوين تطبيق خدمات موثوقة للتشغيل على أنظمة مجموعات Linux.

بدء تشغيل عميل الاختبار وإجراء تجاوز الفشل

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

ملاحظة

يستخدم عميل الاختبار فئة ActorProxy للتواصل مع الجهات الفاعلة، والتي يجب تشغيلها داخل المجموعة نفسها مثل خدمة الجهات الفاعلة أو مشاركة نفس مساحة عنوان IP. يمكنك تشغيل عميل الاختبار على نفس الكمبيوتر العميل مثل نظام مجموعة التطوير المحلية. ومع ذلك، للتواصل مع الجهات الفاعلة في نظام مجموعة بعيد، يجب أن توزع بوابة على نظام المجموعة تتعامل مع الاتصالات الخارجية مع الجهات الفاعلة.

بادر بتشغيل البرنامج النصي باستخدام الأداة المساعدة للمراقبة لرؤية مخرجات خدمة الجهة الفاعلة. يستدعي البرنامج النصي للاختبار الأسلوب setCountAsync() الموجود على الجهة الفاعلة لزيادة عداد، ويستدعي الأسلوب getCountAsync() الموجود على الجهة الفاعلة للحصول على قيمة العداد الجديدة، ويعرض تلك القيمة على وحدة التحكم.

في حالة نظام التشغيل MAC X، تحتاج إلى نسخ مجلد HelloWorldTestClient إلى الموقع نفسه داخل الحاوية عن طريق تشغيل الأوامر الإضافية التالية.
```
 docker cp HelloWorldTestClient [first-four-digits-of-container-ID]:/home
 docker exec -it [first-four-digits-of-container-ID] /bin/bash
 cd /home
```
```
cd HelloWorldActorTestClient
watch -n 1 ./testclient.sh
```
في Service Fabric Explorer، حدد موقع العُقدة التي تستضيف النسخة المتماثلة الأساسية لخدمة الجهات الفاعلة. في لقطة الشاشة أدناه، هي العُقدة 3. تتعامل النسخة المتماثلة للخدمة الأساسية مع عمليات القراءة والكتابة. ثم يتم نسخ التغييرات في حالة الخدمة إلى النُسخ المتماثلة الثانوية والتي تعمل على العُقد 0 و1 في لقطة الشاشة أدناه.
في العُقد، انقر على العُقدة التي عثرت عليها في الخطوة السابقة، ثم حدد إلغاء التنشيط (إعادة التشغيل) من قائمة الإجراءات. يُعيد هذا الإجراء تشغيل العُقدة التي تشغِّل النسخة المتماثلة للخدمة الأساسية ويفرض تجاوز فشل إلى إحدى النُسخ المتماثلة الثانوية التي تعمل على عُقدة أخرى. تتم ترقية هذه النسخة المتماثلة الثانوية إلى نسخةٍ أساسيةٍ، ويتم إنشاء نسخة متماثلة ثانوية أخرى على عُقدة مختلفة، وتبدأ النسخة المتماثلة الأساسية في إجراء عمليات القراءة/الكتابة. أثناء إعادة تشغيل العُقدة، راقب الإخراج من عميل الاختبار ولاحظ أن العداد يستمر في الزيادة على الرغم من تجاوز الفشل.

إزالة التطبيق

استخدم البرنامج النصي لإزالة التثبيت المتوفر في القالب لحذف مثيل التطبيق وإلغاء تسجيل حزمة التطبيق وإزالة حزمة التطبيق من مخزن صور نظام المجموعة.

./uninstall.sh

في Service Fabric Explorer، ترى أن التطبيق ونوع التطبيق لم يعودا يظهران في عُقدة التطبيقات.

مكتبات Service Fabric Java على Maven

تمت استضافة مكتبات Service Fabric Java في Maven. يمكنك إضافة التبعيات في pom.xml أو build.gradle من مشاريعك لاستخدام مكتبات Service Fabric Java من mavenCentral.

الممثلون

دعم ممثل Service Fabric الموثوق به لتطبيقك.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-actors</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-actors:1.0.0'
}

الخدمات

دعم الخدمات الموثوقة لـ Service Fabric لتطبيقك.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-services</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-services:1.0.0'
}

أخرى

نقل

دعم طبقة النقل لتطبيق Service Fabric Java. لا تحتاج إلى إضافة هذه التبعية صراحةً إلى تطبيقات "الممثل الموثوق به" أو "الخدمات"، إلا إذا باشرت بالبرمجة في طبقة النقل.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-transport</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-transport:1.0.0'
}

دعم Fabric

دعم مستوى النظام لـ Service Fabric والذي يتحدث إلى وقت تشغيل Service Fabric الأصلي. لا تحتاج إلى إضافة هذه التبعية صراحةً إلى تطبيقات "الممثل الموثوق به" أو "الخدمات". يتم جلب هذا تلقائياً من Maven، عند تضمين التبعيات الأخرى أعلاه.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf:1.0.0'
}

مشاركة عبر

بادر بإنشاء أول تطبيق للجهات الفاعلة الموثوقة Java Service Fabric على Linux

المتطلبات الأساسية

تركيب وإعداد مُنشئي Java

المفاهيم الأساسية

إنشاء التطبيق

كتل البناء الأساسية للجهات الفاعلة الموثوقة

واجهة الجهة الفاعلة

خدمة الجهات الفاعلة

تسجيل الجهات الفاعلة

إنشاء التطبيق

نشر التطبيق

بدء تشغيل عميل الاختبار وإجراء تجاوز الفشل

إزالة التطبيق

مكتبات Service Fabric Java على Maven

الممثلون

الخدمات

أخرى

نقل

دعم Fabric

الخطوات التالية

الموارد الإضافية