مفتاح عدم التكرار (Idempotency Key): منع الإرسال المكرّر للبريد

آلية العمل

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

أهميته للمُرسِلين

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

اعتبارات تشغيلية

ينبغي إنشاء المفاتيح باستخدام UUID أو سلسلة عشوائية عالية الإنتروبيا لتجنب التصادمات. وتنتهي صلاحية هذه المفاتيح عادةً لدى الخوادم بعد 24 ساعة. ويجب على المطوّرين التأكد من ارتباط المفتاح بقصد الرسالة المحدد؛ فتغيير نص الرسالة أو المستلِم مع إبقاء المفتاح نفسه ينبغي أن يؤدي إلى خطأ لا إلى نجاح مخزّن مؤقتًا.

مثال على التنفيذ

ينشئ تطبيق SaaS مفتاحًا فريدًا لرسالة إعادة تعيين كلمة المرور. يستدعي التطبيق واجهة API للبريد لكن الاتصال ينقطع قبل استلام الاستجابة. فيعيد التطبيق محاولة الطلب بالمفتاح نفسه. ترى واجهة API أن المفتاح موجود مسبقًا فتعيد 200 OK دون إرسال رسالة ثانية إلى المستخدم. ويمكن لأدوات SendHQ المجانية أن تساعد المطوّرين على إدارة بنية البريد لديهم بكفاءة.

معالجة الأخطاء

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

أسئلة تطرحها الفرق

المصادر الأساسية

• وثائق SendGrid — Twilio SendGrid
• وثائق Postmark للمطوّرين — Postmark