Idempotency في APIs: لماذا يجب ألا يكرر Retry عملية الدفع أو الإنشاء؟

العميل قد يرسل طلب دفع أو إنشاء Order ثم ينقطع الاتصال قبل استلام الرد. من وجهة نظره لا يعرف هل العملية نجحت أم لا، فيعيد الطلب. إذا تعامل الخادم مع Retry كعملية جديدة فقد ينشئ طلبين أو يخصم مرتين. Idempotency تعني أن إعادة نفس العملية المنطقية تنتج أثرًا واحدًا حتى لو وصل request أكثر من مرة. هذا مهم في أي API ذات side effects لا يمكن تجاهل تكرارها.

المشكلة ليست في Retry نفسها

Retry ضرورية في الأنظمة الموزعة لأن timeouts والانقطاعات طبيعية. المشكلة أن POST جديد قد يمثل عملية جديدة. لذلك يجب أن يعرف الخادم أن الطلب الثاني هو محاولة لنفس العملية، وليس أمرًا جديدًا من المستخدم.

Idempotency Key تربط المحاولات بنفس العملية

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

التحقق من payload مهم

لا تسمح باستخدام نفس key مع body مختلفة؛ هذا خطأ يجب رفضه. خزّن hash للمدخلات أو الحقول الأساسية مع key، حتى لا تتحول إعادة استخدام المفتاح إلى تحديث غير مقصود.

التزامن يحتاج قفلًا أو قيدًا ذريًا

قد يصل طلبان بنفس key في اللحظة نفسها. فحص ثم إنشاء بسلسلة غير ذرية يترك race condition. استخدم unique constraint أو transaction أو atomic insert/lock بحسب قاعدة البيانات حتى يفوز تنفيذ واحد فقط.

حدد معنى الفشل

إذا فشلت العملية قبل أي أثر، يمكن السماح بإعادة التنفيذ. إذا حدث أثر خارجي ثم فشل حفظ الرد، يجب أن تستطيع الاستعلام عن الحالة أو استعادة النتيجة بدل التكرار. تكاملات الدفع تحتاج reconciliation مع provider، لا مجرد إعادة POST.

اختبر الانقطاع عمدًا

اقطع الاتصال بعد إرسال request مباشرة، أو اجعل client timeout أقصر من زمن المعالجة، ثم أعد الطلب بنفس key. الاختبار الناجح هو وجود record واحدة وأثر واحد مع response متسقة، لا مجرد status 200.