Outbox معاملاتي: آثار جانبية مع كتابة العمل

باختصار: الكتابة إلى قاعدة البيانات ثم استدعاء واجهة بريد أو webhook أو ERP كتابة مزدوجة: قد ينجح أيّ من الخطوتين وحده. ضعوا صف الـ outbox (صندوق الصادر) في المعاملة نفسها مع تغيّر العمل. يقرأ مرحّل منفصل الصفوف المثبَّتة ويسلّم مرة واحدة على الأقل؛ ويجب أن يكون المستقبِلون idempotent.

مخطط الـ outbox المعاملاتي: يعالج الطلب فيكتب صف العمل وصف الـ outbox في معاملة قاعدة بيانات واحدة؛ بعد التثبيت يستطلع المرحّل الـ outbox أو يتتبّع سجله ويسلّم البريد أو الـ webhook أو دفعات ERP مرة واحدة على الأقل؛ ويطبّق المستقبِلون بوابة idempotency. ملاحظة سفلية تحذّر من تثبيت كتابة العمل ثم استدعاء الشبكة بلا outbox دائم.
الشكل 1. كتابة العمل وصف الـ outbox في معاملة واحدة؛ يتولى المرحّل التسليم بعد التثبيت.

1.0 مشكلة الكتابة المزدوجة

المعالج الذي يحفظ طلباً ثم يرسل بريد تأكيد يكتب إلى نظامين: قاعدة البيانات ومزوّد البريد. يظهر الشكل نفسه عند دفع مستند إلى ERP أو إصدار webhook لشريك.

إذا ثبّتت قاعدة البيانات وفشل استدعاء الشبكة، فحالة العمل صحيحة ولم يُبلَّغ أحد. إذا بلّغتم أولاً وفشل التثبيت، فقد تصرّف الطرف الآخر على شيء لم يوجد قط. الالتزام على مرحلتين عبر قاعدة البيانات وواجهة البريد نادراً ما يتوفر وغالباً غير مرغوب. هذه مشكلة الكتابة المزدوجة التي يعالجها نمط الـ outbox المعاملاتي (انظر شرح Chris Richardson وصفحة AWS Prescriptive Guidance في المراجع).

2.0 ما يدخل في معاملة واحدة

الكتابةهل هي في المعاملة نفسها مع تغيّر العمل؟
صف العمل (طلب، دفعة، تذكرة، …)نعم
صف الـ outbox (type، message id، payload، status)نعم
استدعاء HTTP للبريد / الـ webhook / ERPلا — بعد التثبيت، عبر المرحّل
تعليم صف الـ outbox published / حذفهبعد محاولة مرحّل ناجحة (أو تنظيف بتتبّع السجل)

صف الـ outbox ليس سجلاً لما حدث أصلاً على السلك. إنه النية الدائمة لأداء أثر جانبي، ولا يُسجَّل إلا إذا ثُبِّتت كتابة العمل.

3.0 المرحّل: استطلاع أو تتبّع السجل

عملية منفصلة (أو عامل في الخدمة نفسها) تنقل صفوف الـ outbox المثبَّتة إلى العالم الخارجي.

النهجكيف يجد العملالمقايضة المعتادة
ناشر بالاستطلاعSELECT للصفوف المعلّقة مرتَّبة حسب id أو created_atبسيط؛ يعمل على SQL عادي؛ يزداد التأخير والحمل مع فترة الاستطلاع وحجم الجدول
تتبّع سجل المعاملاتقراءة الإدراجات من سجل القاعدة (WAL، binlog، streams)تأخير أقل؛ يحتاج أدواتاً خاصة بالقاعدة؛ ما زال مرة واحدة على الأقل

يوثّق microservices.io الاثنين كمرافقين للـ outbox. ابقوا على الاستطلاع حتى يفرض الحجم أو التأخير الاستثمار في تتبّع السجل. وفي الحالتين عاملوا النشر على أنه مرة واحدة على الأقل: التعطّل بين «نجح الإرسال» و«عُلِّم الصف مكتملاً» يعيد الإرسال.

4.0 شكل الصف الذي نبقيه مستقراً

احتفظوا بأعمدة كافية لتجيب العمليات عن «ما الذي علق؟» دون قراءة ذاكرة التطبيق:

  • id — متزايد أو ULID؛ للترتيب ونقاط تفتيش المرحّل.
  • message_id / مفتاح idempotency — ثابت لهذا الأثر الجانبي المنطقي؛ يزيل المستقبِلون التكرار به.
  • type — أي معالج مرحّل يعمل (email.order_paid، erp.order_push، …).
  • aggregate_key — معرّف الطلب أو العميل المحتمل أو الجهاز؛ للترتيب واستعلامات الدعم.
  • payload — JSON بإصدار يحتاجه المعالج؛ لا تضعوا أسراراً فيه.
  • status — pending → publishing (إيجار اختياري) → published / failed_terminal.
  • attempts وnext_attempt_at وlast_error — للتراجع التدريجي والتنبيهات.
  • created_at — واختيارياً published_at.

احجزوا صفاً بتحديث ذرّي (pending → publishing مع مالك وانتهاء إيجار) حتى لا يرسل عاملا مرحّل البريد نفسه. عند النجاح علّموا published (أو احذفوا إن فضّلتم جدولاً صغيراً واعتمدتم النسخ الاحتياطية للتدقيق). عند فشل قابل لإعادة المحاولة زيدوا attempts واضبطوا next_attempt_at. بعد حدّ مُعدّ انتقلوا إلى failed_terminal ونبّهوا شخصاً.

5.0 الترتيب والتكرارات

لمجمّع واحد انشروا بترتيب معرّفات الـ outbox (أو أرقام التسلسل) المعطاة، حتى لا يرى الشريك «شُحِن» قبل «أُنشئ». عبر المجمّعات، العمال المتوازيون مقبولون.

التكرارات متوقَّعة. اقرؤوا هذه المذكّرة مع الـ idempotency في webhooks: المفاتيح وإعادة المحاولة والآثار الجانبية: يضمن الـ outbox أن الأثر الجانبي يُحاول بعد كتابة عمل ناجحة؛ ومخزن إزالة التكرار عند المستقبِل يضمن أنه يُطبَّق مرة واحدة. دفعات ERP تحتاج الانضباط نفسه في الطرف الآخر — مفتاح عمل ثابت على المستند، كما في ربط الطلبات بنظام ERP: مراجعة يدوية، وإرسال متكرر الأثر، وسجل مزامنة.

6.0 ما لا يوضع على مسار الطلب

  • لا تفتحوا معاملة قاعدة بيانات، ثم تستدعوا واجهة HTTP لطرف ثالث، ثم تثبّتوا. انتهاء المهلة والأقفال يجعلان أنماط الفشل صعبة التفسير.
  • لا تطلقوا goroutine أو نشراً إلى طابور بطريقة fire-and-forget من دون outbox دائم (أو ما يعادله) إن كان فقدان ذلك الأثر الجانبي عند التعطّل غير مقبول.
  • لا تعاملوا «HTTP 200 من واجهة البريد» على أنه سجل رسمي لـ «أُبلِغ العميل» ما لم تثبتوا تلك النتيجة أيضاً. الأفضل: outbox منشور ومعرّف رسالة المزوّد محفوظ على الصف.

7.0 قابلية الملاحظة

  • المقاييس: عمر الـ pending (p50/p95)، معدّلات نجاح/فشل النشر، الإخفاقات النهائية، تأخير المرحّل.
  • التنبيهات: أقدم pending/publishing فوق عتبة؛ ارتفاع مفاجئ في الإخفاقات النهائية بعد نشر.
  • الدعم: ابحثوا بـ aggregate_key واعرضوا حالة الـ outbox بجانب سجل العمل.

إن كنتم تربطون آثاراً جانبية للمدفوعات أو ERP أو سحابات الأجهزة، فراجعوا الويب والسحابة وإدارة الأجهزة، أو حدثونا عن مشروعكم.

المراجع

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

هل الـ outbox هو نفسه طابور الرسائل؟

الـ outbox جدول (أو حقل في مستند) في قاعدة البيانات نفسها التي تُكتب فيها بيانات العمل، فتُثبَّت الكتابتان معاً أو تُلغَيان معاً. الطابور أو الوسيط يأتي بعد المرحّل. وُجد الـ outbox حتى لا ينجح النشر دون كتابة العمل، ولا العكس.

هل ما زلنا نحتاج إلى idempotency عند المستقبِل؟

ما زلنا نحتاجها. قد ينشر المرحّل أكثر من مرة: قد يتعطل بعد إرسال ناجح وقبل تعليم الصف مكتملاً. على المستهلكين معاملة التسليم على أنه مرة واحدة على الأقل، مثلاً بمفتاح idempotency ونافذة الاحتفاظ كما في مذكّرتنا عن الـ webhooks.

هل نستطيع استدعاء واجهة البريد داخل معاملة قاعدة البيانات؟

يُفضَّل تجنّب ذلك. إبقاء معاملة قاعدة البيانات مفتوحة أثناء انتظار استدعاء شبكة يطيل الأقفال، وانتهاء المهلة يترككم بلا يقين إن خرج البريد أم لا. اكتبوا صف الـ outbox وثبّتوا، ثم دعوا المرحّل يتولى عمل الشبكة.

استطلاع جدول الـ outbox يبدو هدراً. هل من خيار آخر؟

الاستطلاع يعمل على أي قاعدة SQL ويكفي عادةً عند حجم متوسط. وحيث تدعم القاعدة ذلك، يقلّل تتبّع سجل المعاملات (مثل قراءة WAL أو binlog لإدراجات الـ outbox) من التأخير والحمل. والطريقتان تسلّمان مرة واحدة على الأقل.

ماذا يوضع في حمولة الـ outbox؟

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