يا هلا بيك يا بشمهندس! فكر معايا كده، كام مرة اشتغلت على مشروع فيه خدمات بتكلم بعضها في الخلفية (Background Services) باستخدام نظام الـ Event-Driven Architecture؟ وكام مرة حسيت إنك تايه ومش عارف إيه الرسائل اللي ماشية في الـ Message Broker ولا شكل الـ Payload عامل إزاي؟

طول عمرنا مرتاحين مع توثيق الـ RESTful APIs بفضل أدوات عظيمة زي Swagger وOpenAPI. بنفتح صفحة الـ Swagger UI نلاقي كل الـ Endpoints قدامنا، نقدر نجربها ونعرف الـ Request والـ Response. لكن لما نيجي للأنظمة اللي بتعتمد على الأحداث (Event-Driven Systems) زي WebSockets، أو RabbitMQ، أو Kafka، الدنيا بتبقى "سداح مداح" وغالباً التوثيق بيكون عبارة عن شوية رسائل على الشات أو ملف Readme قديم ومحدش بيحدثه.

هنا بقى بيجي دور بطل مقالنا النهارده: AsyncAPI. الأداة اللي هتنقذنا وتخلينا نوثق أنظمة الويب سوكيتس ومسارات رسائل الـ Message Brokers بنفس الاحترافية والسهولة اللي متعودين عليها مع Swagger!

إيه هو الـ AsyncAPI وليه بنحتاجه؟

ببساطة شديدة، الـ AsyncAPI هو مواصفات قياسية (Specification) مفتوحة المصدر مخصصة لتوثيق واجهات برمجة التطبيقات غير المتزامنة (Asynchronous APIs). اعتبره كده "Swagger بتاع الـ Events".

زمان، لما كنا بنبني أنظمة معتمدة على الـ Message Brokers زي RabbitMQ أو Apache Kafka، أو بنستخدم تقنيات الـ WebSockets، كانت المشكلة الأساسية هي "الرؤية". المطور الجديد اللي بيدخل الفريق بياخد شهور عقبال ما يفهم إيه الـ Events اللي النظام بينشرها (Published) وإيه الـ Events اللي بيسمعها (Subscribed). الـ AsyncAPI بيحل المشكلة دي من جذورها عن طريق توفير ملف YAML أو JSON واحد بيوصف بدقة:

• إيه هي قنوات الاتصال (Channels) الموجودة في النظام.
• إيه هي الرسائل (Messages) اللي بتمشي في القنوات دي.
• شكل البيانات (Payload Schemas) جوه كل رسالة باستخدام JSON Schema.
• البروتوكول المستخدم زي AMQP، MQTT، Kafka، أو WebSocket.

ليه الـ AsyncAPI مهم جداً لمبرمج الباك اند والمبتدئين؟

لو إنت لسه مبتدئ في عالم الـ Web Development ومصمات الـ Microservices، ممكن تستغرب وتقول: "ما أنا ممكن أكتب شكل الرسالة في كود الجافاسكريبت أو البايثون وخلاص!". الكلام ده صحيح لو المشروع فردي، لكن في بيئات العمل الحقيقية (Enterprise Applications)، الموضوع أكبر بكتير.

لما تستخدم AsyncAPI، إنت بتستفيد من مميزات جبارة زي:

• توثيق تفاعلي (Interactive Documentation): زي الـ Swagger UI، تقدر تولد واجهة مرئية جميلة لفريق الـ Frontend أو لفرق الـ Backend التانية عشان يفهموا الـ Events من غير ما يقعدوا يقروا الكود سطر بسطر.
• توليد الكود التلقائي (Code Generation): أدوات AsyncAPI بتخلیک تولد كود جاهز (Code Skeletons) للاستهلاك أو النشر (Publish/Subscribe) بلغات برمجة مختلفة زي Node.js، Python، Go، وJava.
• التحقق من صحة البيانات (Validation): تقدر تتأكد إن الـ Events اللي طالعة من الخدمة مطابقة تماماً للمواصفات اللي اتفقنا عليها، وده بيقلل الـ Bugs الناتجة عن اختلاف شكل الـ Payload.

مثال عملي: إزاي تكتب ملف AsyncAPI لـ WebSocket أو Message Broker

تعالوا نبص على مثال عملي وبسيط لملف asyncapi.yml بيوصف خدمة خاصة بالشات أو إرسال الإشعارات عبر الـ WebSockets أو الـ Message Brokers:

asyncapi: '2.6.0'
info:
  title: نظام الإشعارات الفورية (Notification Service)
  version: '1.0.0'
  description: خدمة مسؤولة عن إرسال إشعارات اللحظية للمستخدمين عبر الـ WebSockets.
servers:
  production:
    url: api.example.com/ws
    protocol: wss
    description: سيرفر الإنتاج للويب سوكيت
channels:
  user/signedup:
    publish:
      summary: يُستدعى عندما يتم تسسجيل مستخدم جديد في النظام.
      message:
        name: UserSignedUp
        payload:
          type: object
          properties:
            userId:
              type: string
              description: الرقم التعريفي للمستخدم.
            email:
              type: string
              format: email
            signupDate:
              type: string
              format: date-time

الملف البسيط ده قدر يوضح لأي مطر يدخل على المشروع: إيه هي القناة (Channel) اللي اسمها user/signedup، وإيه شكل البيانات اللي هتيجي لما مستخدم جديد يسجل، وهل ده بيتم عبر بروتوكول إيه (زي الـ wss).

نصيحة من أخ: إزاي تطور مهاراتك في الـ Event-Driven Architecture؟

يا صاحبي، مجال الـ Software Engineering بيتطور بسرعة، والـ REST APIs مبقتش هي لوحدها الملكة في السوق. الأنظمة الحديثة بقت معتمدة بشكل كبير على الـ Microservices والـ Event-Driven Architecture.

عشان تثبت نفسك في السوق وتكون مبرمج "Heavyweight"، متكتفيش بس بتعلم إكتب كود بيشغل الـ RabbitMQ أو Kafka. اتعلم إزاي توثق شغلك. ابدأ طبق AsyncAPI في مشاريعك الشخصية (Side Projects). ادخل على الأداة الخاصة بتوليد الواجهات، وجرب تربط التوثيق ده بـ CI/CD Pipeline بحيث كل ما تعدل الكود، التوثيق يتحدث لوحده.

التوثيق الجيد مش رفاهية، ده دليل على احترافية المبرمج واحترامه لوقته ووقْت زملائه في الفريق. بالتوفيق، ومستشوفكم في مقال تقني جديد!