اختبار الكناري لواجهات برمجة التطبيقات: اكتشف أخطاء الإصدارات قبل وصولها للمستخدمين

الاختبار المرحلي يكتشف إصدارات واجهة برمجة التطبيقات الخاطئة عند 5% من حركة المرور، وليس 100%. تعرّف على سير العمل والتحكم في عمليات النشر باستخدام واجهة سطر الأوامر (CLI) الخاصة بـ Apidog ضمن مسار التكامل المستمر والتسليم المستمر (CI/CD) الخاص بك.

Ashley Innocent

Ashley Innocent

15 يونيو 2026

اختبار الكناري لواجهات برمجة التطبيقات: اكتشف أخطاء الإصدارات قبل وصولها للمستخدمين

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

لقد دمجت طلب السحب (PR). كان CI أخضر. اكتمل النشر بدون أي خطأ واحد في السجلات. بعد عشرين دقيقة، بدأت تذاكر الدعم بالورود: نقطة نهاية للدفع تعيد أخطاء 500s لشريحة من العملاء، وليس لديك أي فكرة عن السبب لأن شيئًا لم يفشل في مسار النشر.

هذه هي الفجوة التي يسدها اختبار الكناري. تختبر وحدات الاختبار (Unit tests) واختبارات التكامل (integration tests) شيفرتك البرمجية مقابل ما توقعته. لا يمكنها اختبار شيفرتك مقابل العالم الحقيقي: حركة المرور الإنتاجية، قاعدة البيانات الفعلية، واجهة برمجة التطبيقات (API) الخاصة بطرف ثالث التي غيرت حد معدلها بهدوء يوم الثلاثاء الماضي. يدفع اختبار الكناري إصدارًا جديدًا إلى جزء صغير من حركة المرور الحقيقية أولاً، ويراقب كيف يتصرف، ولا يوسع النشر إلا عندما تبدو الإشارات صحية. إذا حدث عطل، فإنه يحدث لـ 2% من المستخدمين لمدة دقيقتين بدلاً من 100% من المستخدمين لمدة ساعة.

بالنسبة لواجهات برمجة التطبيقات (APIs) على وجه التحديد، يمكنك القيام بما هو أفضل من مجرد مراقبة لوحات المعلومات والأمل. يمكنك تشغيل مجموعة اختبار حقيقية ضد الكناري في اللحظة التي يصبح فيها مباشرًا، والتأكد من رموز الحالة (status codes)، ومخططات الاستجابة (response schemas)، وزمن الاستجابة (latency)، ثم التحكم في النشر بناءً على النتيجة. هذا هو سير العمل الذي يتناوله هذا الدليل، وسنقوم بتوصيله من البداية إلى النهاية باستخدام Apidog ومُشغل سطر الأوامر الخاص به بحيث يعيش كل شيء داخل مسار CI/CD الحالي الخاص بك.

زر

ما هو اختبار الكناري بالفعل

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

عمليًا، يعني نشر الكناري تشغيل نسختين من خدمتك في وقت واحد:

يقوم موازن التحميل (load balancer)، أو شبكة الخدمات (service mesh)، أو وحدة التحكم بالدخول (ingress controller) بتقسيم حركة المرور بينهما. تراقب معدل الأخطاء وزمن الاستجابة والمقاييس التجارية للكناري مقابل خط الأساس المستقر. إذا صمد الكناري، فإنك تحول المزيد من حركة المرور إليه على مراحل حتى يخدم 100% ويصبح هو الإصدار المستقر الجديد. إذا تدهور الأداء، فإنك تعيد توجيه كل شيء إلى الإصدار المستقر ولا يصل الإصدار السيئ إلى معظم جمهورك أبدًا.

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

اختبار الكناري مقابل الاختبارات التي تقوم بها بالفعل

لا يحل اختبار الكناري محل اختباراتك الأخرى. إنه يجلس في نهاية السلسلة ويلتقط فئة مختلفة من الفشل.

نوع الاختبار يعمل ضد يلتقط يغفل
اختبارات الوحدة دوال معزولة أخطاء المنطق أي شيء يتضمن إدخال/إخراج حقيقي
اختبارات التكامل مكونات مترابطة العقود المكسورة بين الخدمات تهيئة الإنتاج، شكل البيانات الحقيقية
اختبارات الدخان بناء تم نشره إخفاقات أساسية "هل هو يعمل حتى؟" تراجعات سلوكية دقيقة
اختبار الكناري إصدار مباشر على بنية تحتية حقيقية تهيئة سيئة، انحراف البيئة، تراجعات الأداء، انقطاعات جزئية أخطاء تظهر فقط على نطاق كامل

السبب في أن اختبار الكناري يستحق مكانه: نسبة كبيرة من حوادث الإنتاج تأتي من أشياء لا يمكن لأي بيئة ما قبل الإنتاج إعادة إنتاجها بالكامل. متغير بيئة مفقود. إعداد تجمع اتصال (connection-pool) قديم. فهرس قاعدة بيانات موجود في بيئة الاختبار (staging) ولكن ليس في بيئة الإنتاج. تبعية (dependency) تتصرف بشكل مختلف تحت مصادقة حقيقية. رمزك صحيح؛ لكن البيئة المحيطة به ليست كذلك. اختبار الكناري هو المرة الأولى التي يلتقي فيها إصدارك الجديد بهذه البيئة، وتريد أن تلتقي به مع اثنين بالمئة من حركة المرور، وليس كلها.

إذا كنت تريد السياق الأوسع حول مكان هذا، فإن دليلنا حول كيفية أتمتة اختبارات API في CI/CD يغطي المراحل الأولية، واختبار الدخان مقابل اختبار الانحدار يشرح نوعي الاختبارات التي يعتمد عليها الكناري أكثر من غيرها.

ما الذي يجب قياسه على الكناري

الكناري يكون مفيدًا فقط إذا كنت تعرف كيف يبدو "الصحي". اختر مجموعة صغيرة من الإشارات وقارن الكناري بخط الأساس المستقر، وليس برقم مطلق. قد يكون معدل الخطأ بنسبة 1.2% طبيعيًا لخدمتك؛ المهم هو ما إذا كان الكناري أسوأ بشكل ملحوظ من الإصدار المستقر حاليًا.

تغطي أربع إشارات معظم الحالات:

  1. معدل الخطأ: نسبة استجابات 5xx، وغالبًا 4xx التي لا ينبغي أن تحدث، مثل ارتفاع مفاجئ في استجابات 401s بعد تغيير المصادقة. هذا هو المقياس الأهم على الإطلاق.
  2. زمن الاستجابة (Latency): p95 و p99، وليس المتوسط. يخفي المتوسط الذيل البطيء حيث يشعر المستخدمون الحقيقيون بالمعاناة. الكناري الذي يكون أبطأ بـ 40 مللي ثانية عند p99 هو تحذير حتى لو كان المتوسط يبدو جيدًا.
  3. صحة الاستجابة: هل لا يزال الجسم يطابق المخطط (schema)؟ استجابة 200 OK التي تعيد شكلًا خاطئًا أسوأ من 500، لأن المراقبة لن تكتشفها.
  4. إشارات الأعمال: نجاح عملية الدفع، نجاح تسجيل الدخول، العناصر المضافة إلى سلة التسوق. هذه تكشف عن تراجعات منطقية تعتبر استجابات HTTP "ناجحة" من الناحية الفنية.

يمكنك التأكد من الثلاثة الأولى مباشرة في اختبار API. هذا هو الجزء الذي سنقوم بأتمتته.

سير عمل اختبار الكناري، خطوة بخطوة

إليك شكل نشر الكناري المتحكم فيه بواسطة اختبارات API المؤتمتة. كل خطوة هي شيء يمكنك تشغيله من مسار النشر.

  1. انشر الإصدار الجديد ككناري جنبًا إلى جنب مع الإصدار المستقر.
  2. وجه شريحة صغيرة من حركة المرور (5% على سبيل المثال) إلى الكناري.
  3. شغّل مجموعة اختبار API مؤتمتة ضد نقطة نهاية الكناري.
  4. راقب معدل الخطأ وزمن الاستجابة لفترة زمنية قصيرة.
  5. البوابة: إذا نجحت الاختبارات وبقيت المقاييس ضمن الميزانية المحددة، حول المزيد من حركة المرور. وإلا، قم بالتراجع.
  6. كرر الزيادة التدريجية (من 5% إلى 25% إلى 50% إلى 100%)، مع إعادة الاختبار في كل خطوة.
  7. ارفع الكناري إلى الإصدار المستقر، وأنهِ خدمة الإصدار القديم.

الجزآن اللذان يستحقان اهتمامك هما الخطوة 3 (مجموعة الاختبار) والخطوة 5 (البوابة). إذا قمت بهما بشكل صحيح، فالبقية هي مجرد توصيلات توفرها منصتك بالفعل.

بناء مجموعة الاختبار في Apidog

مجموعة الاختبار هي قلب اختبار الكناري، وهي النقطة التي يختصر فيها معظم الفرق. اختبار كناري يقتصر على إرسال طلب إلى /health والتحقق من استجابة 200 يخبرك أن العملية بدأت. لكنه لا يخبرك شيئًا عما إذا كانت نقاط النهاية الفعلية لديك تعمل.

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

سيناريو كناري قوي لواجهة برمجة تطبيقات للتجارة الإلكترونية يبدو كالتالي:

في Apidog، تقوم بإنشاء كل طلب مرة واحدة، ثم تضيف التأكيدات بصريًا. لفحوصات المخطط (schema)، يمكنك التحقق من صحة الاستجابة مقابل مخطط OpenAPI الذي صممته بالفعل، لذا فإن جسم استجابة منحرف يفشل الاختبار تلقائيًا. لتسليم رمز المصادقة، تقوم باستخراجه من استجابة الخطوة 1 والرجوع إليه كمتغير في الخطوات اللاحقة. لا يلزم كتابة نصوص برمجية للحالات الشائعة، ويمكنك استخدام معالجات JavaScript اللاحقة (post-processors) عندما تحتاج إلى منطق مخصص.

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

تشغيل المجموعة من سطر الأوامر

للسيطرة على النشر، يجب أن تعمل المجموعة بدون واجهة رسومية في CI. يوفر Apidog واجهة سطر أوامر (CLI) لهذا الغرض بالضبط. قم بتثبيتها على وكيل البناء الخاص بك:

npm install -g apidog-cli

قم بتصدير بيانات سيناريو الاختبار الخاصة بك من Apidog كملف بتنسيق CLI، أو وجه المشغل إلى سيناريو بواسطة المعرف (ID) باستخدام رمز وصول (access token)، ثم قم بتشغيله:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$CANARY_SCENARIO_ID" \
  -e "$CANARY_ENV_ID" \
  -r cli,html,junit

بعض العلامات الجديرة بالمعرفة لعمل الكناري:

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

للحصول على شرح تفصيلي لتشغيل Apidog في مسارات النشر، يغطي كيفية أتمتة اختبارات API في GitHub Actions ودليل تكامل Jenkins تلك المنصات بالتفصيل.

ربطه بـ CI/CD

إليك مهمة GitHub Actions مختصرة تنشر كناري، تختبره، وترقيه فقط عند النجاح. ينتقل هذا الهيكل إلى GitLab CI أو CircleCI أو Jenkins مع تغييرات طفيفة في بناء الجملة.

name: canary-release

on:
  push:
    branches: [main]

jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy canary (5% traffic)
        run: ./deploy.sh --canary --weight 5

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Test the canary
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t "$CANARY_SCENARIO_ID" \
            -e "$CANARY_ENV_ID" \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
          CANARY_SCENARIO_ID: ${{ vars.CANARY_SCENARIO_ID }}
          CANARY_ENV_ID: ${{ vars.CANARY_ENV_ID }}

      - name: Bake and watch (2 min)
        run: sleep 120 && ./check-metrics.sh --service canary --max-error-rate 1.0

      - name: Promote canary to 100%
        run: ./deploy.sh --promote

      - name: Roll back on any failure
        if: failure()
        run: ./deploy.sh --rollback

المنطق الذي يجعل هذا كناريًا بدلاً من نشر عادي هو الترتيب. يستقبل الكناري شريحة من حركة المرور قبل تشغيل الاختبار، لذلك يختبر الإصدار الذي يخدم بالفعل طلبات حقيقية. خطوة if: failure() هي شبكة الأمان: إذا انتهت مجموعة الاختبار بقيمة غير صفرية، أو تعثر فحص المقاييس، تفشل المهمة ويتم تشغيل التراجع قبل أن تتجاوز حركة المرور 5%.

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

أخطاء شائعة تجعل اختبار الكناري عديم الفائدة

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

فترة تحضير صفرية. بعض الإخفاقات تظهر فقط تحت الحمل المستمر: تسرب الذاكرة (memory leaks)، استنزاف تجمع الاتصال (connection-pool exhaustion)، ذاكرة تخزين مؤقت (cache) تمتلئ. قم بتشغيل الاختبار، ثم راقب لبضع دقائق قبل الترقية. الكناري الذي ينجح على الفور ويتم ترقيته في عشر ثوانٍ بالكاد يكون كناريًا.

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

عتبات مطلقة بدلاً من المقارنات. "فشل إذا كان معدل الخطأ أعلى من 1%" يتسبب في مشكلة عندما يكون معدل الخطأ الأساسي لديك 1.5% بشكل مشروع. قارن الكناري بالإصدار المستقر الحالي، وفعل البوابة عندما يكون الكناري أسوأ بشكل ملحوظ، وليس عندما يتجاوز رقمًا اخترته قبل أشهر.

تأكيدات ضعيفة. استجابة 200 مع جسم مشوه تمر بفحص رمز الحالة فقط وتفشل مستخدميك. تأكد من مخطط الاستجابة، وليس فقط الرمز. هذا هو المكان الذي يؤتي فيه تصميم عقد API الخاص بك أولاً والتحقق من صحة الاستجابات مقابل المخطط ثماره مباشرة: يرث اختبار الكناري الخاص بك العقد مجانًا.

ما هو مدى اتساع الكناري وكم من الوقت يجب أن يستمر؟

لا توجد إجابة عالمية، ولكن هناك إعداد افتراضي قابل للتطبيق لمعظم الفرق:

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

أين يتناسب اختبار الكناري مع استراتيجية إصدارك

يتوافق اختبار الكناري بشكل طبيعي مع علامات الميزات (feature flags) وعمليات النشر الزرقاء-الخضراء (blue-green deployments)، ومن المهم توضيح الفرق. النشر الأزرق-الأخضر يحول كل حركة المرور من بيئة كاملة إلى أخرى دفعة واحدة؛ التراجع سريع، لكن لا يوجد تعرض تدريجي. علامات الميزات تبدل السلوك لمستخدمين مختارين دون إعادة نشر. إصدارات الكناري تحول حركة المرور الحقيقية تدريجيًا وتتحكم بناءً على إشارات حية.

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

هذه هي الفكرة الأساسية الحقيقية. اختبار الكناري ليس أداة تشتريها؛ بل هو منهجية: انشر بكميات صغيرة، اختبر الإصدار المباشر بتأكيدات حقيقية، راقب الإشارات، وتحكم في النشر بناءً على النتيجة. الأدوات موجودة لجعل كل خطوة من هذه الخطوات تلقائية. مع Apidog، تقوم ببناء مجموعة الاختبار مرة واحدة، وتشغلها من واجهة سطر الأوامر داخل أي مسار نشر، وتدع رمز الخروج يقرر ما إذا كان الإصدار يتقدم أم لا. تتوقف الإصدارات السيئة عند 5% من حركة المرور، ولا يرى المستخدمون أبدًا أخطاء 500s.

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

زر

الأسئلة الشائعة

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

هل أحتاج إلى شبكة خدمات (service mesh) للقيام باختبار الكناري؟ لا. شبكة الخدمات مثل Istio أو Linkerd تجعل تقسيم حركة المرور أسهل، ولكن يمكنك تشغيل الكناري باستخدام وزن موازن تحميل عادي، أو تعليقات الكناري لوحدة تحكم الدخول (ingress controller)، أو حتى ترجيح DNS. جزء الاختبار والتحكم في سير العمل، وهو ما يركز عليه هذا الدليل، يعمل بنفس الطريقة بغض النظر عن كيفية تقسيم حركة المرور.

بماذا يختلف هذا عن اختبار الدخان بعد النشر؟ عادةً ما يتم تشغيل اختبار الدخان مرة واحدة مقابل إصدار تم نشره بالكامل للتأكد من أنه يعمل. بينما يعمل اختبار الكناري مقابل إصدار يخدم جزءًا فقط من حركة المرور الحقيقية، وهو يتحكم في الزيادة التدريجية. يمكن أن تكون التأكيدات متطابقة؛ الفرق هو التوقيت والنتيجة. اختبار دخان فاشل يعني التراجع عن شيء مباشر بالفعل للجميع؛ اختبار كناري فاشل يعني إيقاف عملية النشر عند 5%. للتمييز بين اختبارات الدخان والانحدار، راجع دليل المقارنة الخاص بنا.

هل يمكنني إعادة استخدام اختبارات API الحالية كاختبارات كناري؟ غالبًا، نعم. إذا كان لديك بالفعل سيناريوهات اختبار Apidog بتأكيدات حقيقية، فإنك توجهها إلى بيئة يكون عنوان URL الأساسي الخاص بها هو الكناري وتشغلها باستخدام واجهة سطر الأوامر (CLI). العمل يكمن في التأكد من أن اختباراتك تؤكد على أجسام الاستجابة وليس فقط رموز الحالة، وفي توجيهها إلى الكناري بدلاً من عنوان URL العام الموزع بواسطة موازن التحميل.

ماذا يحدث عندما يفشل اختبار الكناري في CI؟ تخرج واجهة سطر الأوامر (CLI) الخاصة بـ Apidog برمز غير صفري عند أي تأكيد فاشل. يتعامل مسار النشر الخاص بك مع هذا كأي خطوة فاشلة: تتوقف المهمة، ويتم تخطي خطوة الترقية، ويتم تشغيل خطوة التراجع if: failure(). لا يحتاج أي إنسان إلى المراقبة لحدوث التراجع.

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات