عند استلام تكامل يعتمد على الأحداث، لا تكتفِ بعرض يصل فيه إشعار واحد ويُنشئ سجلاً واحداً. اطلب إثبات ما يحدث إذا وصل الإشعار مرتين، أو وصل تحديث قديم بعد تحديث أحدث، أو لم يصل إشعار متوقع أصلاً. الهدف هو ضبط أثر العملية التجارية مع وجود أدلة ومسؤول للتعافي، لا تقديم وعد عام بأن الربط «لا يفقد شيئاً».
هذا الدليل يركز على التسليم والتعافي بعد الاتفاق على الحقول والواجهات. يشمل نطاق تطوير وربط واجهات برمجة التطبيقات معالجة الأخطاء، لكن سلوك المزوّد وحدود إعادة المحاولة تحتاج تحققاً من توثيقه الحالي وإعداد حسابه الفعلي.
ثلاث مشكلات تحتاج ثلاثة قرارات
التكرار يعني وصول إشعار سبق التعامل معه أو وصول إشعار مختلف يؤدي إلى الأثر التجاري نفسه. التأخر يعني أن الإشعار وصل بعد أن تغيرت حالة العمل. أما الفقد التشغيلي فيعني أن النظام المتوقع لم يحقق النتيجة رغم وجودها في المصدر؛ قد تكون المشكلة في التسليم أو المعالجة أو البيانات.
تذكر وثائق Stripe للأحداث أن الأحداث قد تتكرر وأن ترتيب وصولها غير مضمون. هذا دليل على ضرورة فحص سلوك المزود، وليس افتراض أن كل واجهة تملك سياسة Stripe نفسها. لا تنقل مدد إعادة المحاولة أو ضمانات منصة إلى أخرى دون تحقق.
قبل أي أثر تجاري، تحقق من مصدر الإشعار بالطريقة التي يوثقها المزوّد، مثل فحص التوقيع عندما يفرضه. تذكر وثائق Stripe المشار إليها ضرورة التحقق من مصدر أحداثها؛ وتُختار آلية كل ربط من وثائق مزوّده، لا من اسم الحقل وحده.
حدد مفتاح الإشعار ومفتاح العملية التجارية كلّاً على حدة. منع تكرار معرف إشعار واحد قد لا يمنع إنشاء أمرين إذا أرسل المصدر إشعارين مختلفين للعملية نفسها. وفي المقابل، تجاهل جميع الإشعارات التي تحمل رقم طلب واحد قد يسقط تحديثاً مشروعاً لذلك الطلب.
مثال افتراضي: طلب مدفوع وإشعار متأخر
لنفترض أن طلباً تجريبياً بمعرف O-71 أصبح جاهزاً للتجهيز بعد تأكيد الدفع. يصل الحدث E-100 فينشئ النظام مهمة تجهيز واحدة. يعاد إرسال الحدث نفسه لأن تأكيد استلامه لم يصل إلى المصدر. النتيجة المطلوبة تبقى مهمة واحدة، مع تسجيل الاستلام المكرر دون تكرار أثره.
بعد ذلك يصل تحديث قديم يصف الطلب بأنه «بانتظار الدفع»، بعدما أصبح جاهزاً. لا ينبغي أن يعيد النظام الطلب إلى حالة سابقة بمجرد أن الرسالة وصلت الآن. يتفق الفريق على طريقة تحديد الحالة المعتبرة، مثل التحقق من الحالة الحالية لدى المصدر أو استخدام إصدار موثوق يتيحه، بحسب الواجهة الفعلية.
وأخيراً، يظهر في المصدر طلب آخر جاهز بمعرف O-72 دون مهمة مقابلة في الوجهة. لا يستطيع عدّ الرسائل المستلمة كشفه وحده. تكشفه مطابقة قائمة الطلبات المستحقة مع المهام المنشأة، ثم يراجعه المسؤول ويعيد المعالجة المأذونة. المثال توضيحي لطلب افتراضي، ولا يتضمن ربط دفع متاحاً تلقائياً أو توصية بمزوّد.
فرّق بين الاستلام وإتمام العمل
قد يستلم الربط الرسالة ويحفظها، ثم يفشل النظام التالي في إنشاء المهمة. لذلك يحتاج سجل المعالجة إلى حالات مفهومة: مستلم، قيد المعالجة، مكتمل، يحتاج تدخلاً، أو مستبعد بسبب معروف. لا تجعل الاستجابة الناجحة للمصدر مساوية تلقائياً لنجاح العمل النهائي.
يحدد التصميم متى يمكن تأكيد الاستلام، وكيف يحفظ العمل المطلوب قبل التأكيد، وكيف يتعامل مع تعطل المعالج في منتصف الخطوة. اختيار الآلية يعتمد على المزوّد والبنية؛ المطلوب من المشتري أن يرى سلوكاً مثبتاً، لا أسماء تقنيات فقط.
ضمن مراقبة الأنظمة وهندسة الموثوقية، اربط التنبيه بعمر العملية غير المكتملة وعدد الحالات التي تحتاج تدخلاً، لا بعدد أخطاء السجل فقط. قد يبقى النظام «متاحاً» بينما تتراكم الأعمال دون تنفيذ. سمِّ من يتلقى التنبيه ومتى يصعّد، ولا تفترض وجود متابعة على مدار الساعة دون اتفاق.
إعادة المحاولة تحتاج حدوداً وأثراً آمناً
قسّم أسباب الفشل إلى مؤقتة، وأخطاء بيانات، وصلاحيات، وحالات تحتاج مراجعة. لا تعِد إرسال بيانات خاطئة إلى الأبد. اكتب الحد الذي تتحول عنده الحالة إلى قائمة استثناءات، ومن يستطيع إصلاحها وإعادة تشغيلها، وما الدليل على أن الأثر لم يحدث سابقاً.
إذا كانت النتيجة غير معروفة، افحصها قبل التكرار. قد يكون الطرف الآخر أنجز العملية ثم انقطع الرد. ينبغي أن يعرض سجل نظام العمليات الداخلي المرجع والحالة والإجراء المتاح للمسؤول المخول، دون كشف مفاتيح سرية أو دفع المستخدم إلى معالجة عمياء.
لا تعد بتنفيذ «مرة واحدة تماماً» على امتداد أنظمة متعددة لمجرد وجود فحص تكرار. اشرح بدلاً من ذلك الحدود المختبرة، ومتى يلزم التحقق أو التدخل البشري، وما الحالات التي لم يشملها الاختبار.
حزمة قبول قبل التشغيل
اطلب من اختبار وضمان جودة البرمجيات تجربة تكرار الإشعار، ووصول حدثين خارج الترتيب، وتعطل الوجهة، واستلام رسالة غير صالحة، ورفض إشعار لم يجتز التحقق من المصدر أو التوقيع بحسب الآلية المعتمدة، وإعادة تشغيل المعالج بعد فشل جزئي. أضف حالة لا يصل فيها الحدث، ثم تحقق أن المطابقة تكتشف غياب النتيجة.
لكل تجربة، سجّل عدد الآثار التجارية لا عدد الرسائل فقط، والوقت والحالة النهائية ومرجع التتبع. اختبر إجراء الاستعادة بحساب المسؤول الذي سيستخدمه فعلاً. ويشمل القبول سياسة الإبقاء على سجل منع التكرار، وحدود إعادة تشغيل الأحداث القديمة، وصاحب قرار التعامل مع الاستثناءات؛ كلها قرارات مرتبطة بواقع التشغيل لا قيم ثابتة تُنسخ من مشروع آخر.
أسئلة شائعة
هل منع تكرار رقم الطلب يكفي؟
قد يمنع تحديثات صحيحة إذا احتاج الطلب عدة أحداث. ميّز بين هوية الحدث وهوية الأثر المطلوب، واختبر القاعدة على الإنشاء والتعديل معاً.
هل نعيد المحاولة عند كل خطأ؟
لا. بعض الأخطاء تحتاج تصحيح بيانات أو صلاحية. صنّفها وحدد مسارها، ولا تستخدم الإعادة غير المحدودة كبديل عن المعالجة.
كيف نكتشف حدثاً لم يصل؟
بمطابقة مصدر موثوق للعمليات المستحقة مع النتائج المتوقعة، ضمن الإمكانات والصلاحيات المتاحة. مراقبة الرسائل التي وصلت لا تكشف وحدها ما لم يصل.
هل المراقبة تعني دعماً مستمراً؟
المراقبة تنتج إشارات وأدلة. الاستجابة تحتاج مالكاً وساعات تغطية وصلاحيات متفقاً عليها. لا تخلط تركيب التنبيه مع التزام استجابة غير متعاقد عليه.
قبل قبول الربط، اطلب تشغيل سيناريو فشل واحد من بدايته حتى تسوية نتيجته. هذه التجربة تكشف جودة التعافي أكثر من إعادة عرض المسار الناجح.
المصدر الفني
- Stripe: ترتيب الأحداث والتكرار ومعالجة webhooks، روجع في 26 أكتوبر 2026. السيناريو ومعايير القبول مقترحات مستقلة وليست وصفاً لتنفيذ فعلي.
