Technical Tutorials

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

لماذا يهم التطوير القائم على العقود؟

غالبًا ما يؤدي التطوير التقليدي إلى واجهات "كرة طين كبيرة" تتطور بشكل عضوي، مما يجعلها هشة. يضمن التطوير القائم على العقود، الذي يستفيد عادةً من أدوات مثل OpenAPI (Swagger) أو AsyncAPI للرسائل، أن تتفق كل خدمة على بنية البيانات ونقاط النهاية وأكواد الخطأ قبل النشر. يتيح هذا الفصل بين الواجهات الأمامية والخلفية (أو فرق الخدمات المصغرة المنفصلة) العمل بالتوازي، باستخدام نماذج محاكاة (Mocks) مولدة من العقد لاختبار تنفيذاتهم بشكل مستقل.

تعريف المصدر الذهبي

جوهر هذه الاستراتيجية هو الحفاظ على مواصفة "المصدر الذهبي". هذا ملف YAML أو JSON مُتحكم في إصداراته يعرّف الواجهة البرمجية. أدناه مثال مبسط لمواصفة OpenAPI 3.0 لخدمة UserService:

openapi: 3.0.0
info:
  title: User Service API
  version: 1.2.0
  description: Handles user profile management.
paths:
  /users/{userId}:
    get:
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time

من خلال الالتزام بهذا الملف في Git، يصبح المصدر الوحيد للحقيقة. يمكن بعد ذلك للخطوط التلقائية للبناء والنشر (CI/CD) التحقق من أي تغييرات مقابل هذه المواصفة باستخدام أدوات التدقيق (Linters) ومفحوات التوافق.

استراتيجيات الإصدارات: المسار، الترويسة، أم الدلالية؟

عندما تكون التغييرات الكاسرة حتمية، كيف ندير الإصدارات؟ في الخدمات المصغرة، هناك ثلاث استراتيجيات شائعة، لكل منها مزايا وعيوب:

إصدار المسار (/v1/users): بسيط وصريح. ممتاز للواجهات البرمجية العامة، لكنه قد يؤدي إلى فوضى في عناوين URL. يصعب إيقاف استخدامه لأن المسارات القديمة يجب أن تبقى نشطة.
إصدار الترويسة (X-API-Version: v1): يحافظ على نظافة عناوين URL. ومع ذلك، فهو غير مرئي في سجل المتصفح وقد يكون من الصعب تخزينه مؤقتًا بشكل صحيح.
الإصدار الدلالي مع أعلام الميزات: النهج الحديث للخدمات المصغرة. تحافظ على نقطة نهاية واحدة، لكنك تستخدم أعلام الميزات أو شبكات الخدمات (Service Meshes) لتوجيه حركة المرور بناءً على التوافق المعلن من المستهلك. هذا يتيح النشر التدريجي.

فرض الاستقرار في CI/CD

كتابة العقد هي نصف المعركة فقط؛ فرضه هو النصف الآخر. في خط CI الخاص بك، يجب أن تكمل أدوات مثل openapi-diff أو spectral. تحلل هذه الأدوات الفروقات بين الفرع الرئيسي وطلب الدمج (Pull Request) للكشف عن التغييرات الكاسرة.

على سبيل المثال، إذا أضاف المطور حقلًا مطلوبًا إلى مخطط User دون تحديث الإصدار، يجب أن يفشل الخط التلقائي مع رسالة واضحة:

❌ Breaking Change Detected:
   Property 'email' in schema 'User' was changed from optional to required.
   Action: Bump minor version to 1.3.0 or make field optional.

الخلاصة

التطوير القائم على العقود ليس مجرد نمط تقني؛ بل هو انضباط ثقافي. من خلال معاملة مواصفات الواجهات البرمجية الخاصة بك كمواطنين من الدرجة الأولى، تقلل الحمل المعرفي، وتمكن استقلالية الفرق، وتضمن بقاء منظومتك من الخدمات المصغرة مرنة أمام التغيير. ابدأ صغيرًا: وثّق خدمة حرجة واحدة، أتمتة التحقق منها، وقم بتوسيع العملية عبر مؤسستك.