كانت نقرة مزدوجة تكلفنا عميلاً: كيف أنقذتنا ‘مفاتيح عدم التكرار’ (Idempotency Keys) من جحيم المعاملات المكررة؟

حكاية فنجان القهوة المُر… والنقرة المزدوجة

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

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

يا إلهي، إنها “الورطة” بعينها. بدأنا فوراً في تحليل السجلات (logs). وجدنا النمط يتكرر: طلبان متطابقان من نوع POST لإنشاء عملية الدفع، يفصل بينهما أجزاء من الثانية فقط. ما الذي حدث؟ هل المستخدمون يضغطون على زر “ادفع الآن” مرتين عمداً؟

الجواب كان أبسط وأكثر خطورة: شبكة إنترنت بطيئة. كان المستخدم يضغط على الزر، لا يرى أي استجابة فورية بسبب بطء الشبكة، فيظن أن النقرة الأولى لم تعمل، فيضغط مرة أخرى… وهكذا تحدث الكارثة. كانت نقرة مزدوجة بريئة على وشك أن تكلفنا سمعتنا، وعميلاً استثمرنا شهوراً طويلة في كسب ثقته. في تلك الليلة، لم يكن هناك حل سحري سوى الاعتذار، وإرجاع المبالغ المكررة يدوياً، ووعد العميل بحل جذري. وكان هذا الحل هو ما يعرف بـ “مفاتيح عدم التكرار” أو Idempotency Keys.

ما هي “عدمية التكرار” (Idempotency) أصلاً؟

قبل أن نغوص في الحل، دعونا نبسط المفهوم. “Idempotency” هي خاصية لعملية ما، تعني أن تكرار تنفيذها عدة مرات يعطي نفس النتيجة كما لو تم تنفيذها مرة واحدة فقط.

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

في عالم واجهات برمجة التطبيقات (APIs)، بعض الطلبات “عديمة التكرار” بطبيعتها:

• GET: طلب جلب البيانات. يمكنك طلبه ألف مرة وستحصل على نفس البيانات (ما لم تتغير على الخادم)، ولن يغير ذلك من حالة النظام.
• PUT: طلب تحديث مورد بالكامل. إذا أرسلت نفس الطلب لتحديث بيانات مستخدم مرتين، فالنتيجة النهائية واحدة: بيانات المستخدم ستكون كما في طلبك الأخير.
• DELETE: طلب حذف مورد. إذا حذفت مستخدماً، فالطلب الثاني لحذفه سيعيد غالباً خطأ “غير موجود” (404 Not Found)، لكن حالة النظام النهائية (المستخدم محذوف) لن تتغير.

المشكلة الحقيقية تكمن في طلبات POST، التي تستخدم لإنشاء موارد جديدة (عملية دفع جديدة، مستخدم جديد، منشور جديد). كل طلب POST يُفترض أن ينشئ شيئاً جديداً. وهنا تكمن خطورة التكرار.

القاتل الصامت: أسباب وويلات الطلبات المكررة

لماذا قد يتكرر طلب ما؟ الأسباب كثيرة وأكثر شيوعاً مما تظن:

• نقرات المستخدم المزدوجة: كما حدث معنا، بسبب واجهة غير سريعة الاستجابة أو شبكة بطيئة.
• إعادة المحاولة التلقائية (Automatic Retries): العديد من مكتبات الشبكات (مثل Axios في جافاسكريبت) أو حتى المتصفحات قد تعيد إرسال الطلب تلقائياً إذا فشل بسبب انقطاع مؤقت في الشبكة.
• بوابات الشبكة (Gateways): أحياناً، قد تقوم مكونات في البنية التحتية بإعادة محاولة إرسال الطلب إذا لم تتلق رداً في الوقت المناسب.

والنتائج؟ كارثية على أقل تقدير:

• خصم مبالغ مضاعفة من العملاء.
• إنشاء حسابات مستخدمين مكررة بنفس البريد الإلكتروني.
• إرسال إشعارات أو رسائل بريد إلكتروني مكررة.
• فوضى في المخزون إذا كان النظام لمتجر إلكتروني.

طوق النجاة: كيف تعمل مفاتيح عدم التكرار (Idempotency Keys)؟

الحل يكمن في جعل طلبات POST “عديمة التكرار” بشكل مصطنع. نفعل ذلك عبر “مفتاح عدم التكرار”، وهو ببساطة مُعرّف فريد (unique identifier) يتم إنشاؤه من طرف العميل (Client-side) لكل عملية فريدة يريد تنفيذها.

الآلية خطوة بخطوة

1. العميل يُنشئ المفتاح: قبل إرسال طلب إنشاء عملية الدفع، يقوم تطبيق العميل (سواء كان تطبيق ويب أو موبايل) بإنشاء سلسلة نصية فريدة. عادة ما تكون UUID (Universally Unique Identifier).
2. العميل يُرسل المفتاح: يرسل العميل هذا المفتاح مع الطلب، غالباً في ترويسة (Header) خاصة مثل Idempotency-Key.
3. الخادم يستقبل ويفحص: عندما يستقبل الخادم الطلب، أول شيء يفعله هو قراءة هذا المفتاح.
4. الخادم يتخذ القرار:
   • إذا كان المفتاح جديداً: يقوم الخادم بمعالجة الطلب كالمعتاد (إنشاء عملية الدفع). ولكن قبل أن يرسل الرد الناجح (e.g., 201 Created)، يقوم بتخزين المفتاح مع نتيجة العملية (الرد الذي سيرسله) في قاعدة بيانات أو ذاكرة تخزين مؤقت (Cache).
   • إذا كان المفتاح موجوداً مسبقاً: هنا يكمن السحر. الخادم لا يقوم بإعادة تنفيذ العملية. بدلاً من ذلك، يتجاهل كل شيء في الطلب الجديد، ويذهب مباشرة إلى المكان الذي خزّن فيه نتيجة الطلب الأصلي، ويعيد نفس الرد الذي أرسله في المرة الأولى.

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

مثال كود بسيط (Node.js/Express)

لتقريب الصورة، هذا مثال توضيحي باستخدام Express.js. تخيل أن لدينا مخزناً بسيطاً (in-memory) لتتبع المفاتيح والردود.

const express = require('express');
const { v4: uuidv4 } = require('uuid'); // لتوليد المفاتيح

const app = express();
app.use(express.json());

// مخزن مؤقت للمفاتيح والردود (في الواقع ستستخدم Redis أو قاعدة بيانات)
const idempotencyStore = new Map();

// Middleware لمعالجة مفاتيح عدم التكرار
const idempotencyMiddleware = (req, res, next) => {
  const idempotencyKey = req.get('Idempotency-Key');

  if (!idempotencyKey) {
    // إذا لم يوجد مفتاح، اكمل كالمعتاد (أو يمكنك رفض الطلب)
    return next();
  }

  // هل رأينا هذا المفتاح من قبل؟
  if (idempotencyStore.has(idempotencyKey)) {
    console.log(`[Idempotency] مفتاح مكرر: ${idempotencyKey}. إعادة الرد المخزن.`);
    const cachedResponse = idempotencyStore.get(idempotencyKey);
    // أعد إرسال نفس الرد المخزن
    return res.status(cachedResponse.statusCode).json(cachedResponse.body);
  }

  // هذا مفتاح جديد، نحتاج لتخزين الرد بعد اكتمال الطلب
  const originalJson = res.json;
  const originalStatus = res.status;

  res.status = (statusCode) => {
    res.locals.statusCode = statusCode;
    return originalStatus.call(res, statusCode);
  };
  
  res.json = (body) => {
    // خزن الرد قبل إرساله
    const responseToCache = {
      statusCode: res.locals.statusCode || 200,
      body: body,
    };
    idempotencyStore.set(idempotencyKey, responseToCache);
    console.log(`[Idempotency] مفتاح جديد: ${idempotencyKey}. تخزين الرد.`);
    
    // أرسل الرد الأصلي
    return originalJson.call(res, body);
  };

  next();
};


// تطبيق الـ Middleware على المسارات الحساسة
app.post('/api/payments', idempotencyMiddleware, (req, res) => {
  // هنا منطق معالجة الدفع الحقيقي...
  // ...
  // ...
  console.log("... جاري معالجة عملية دفع جديدة ...");

  const paymentResult = { 
    transactionId: `txn_${Date.now()}`, 
    amount: req.body.amount, 
    status: 'completed' 
  };
  
  // الـ Middleware سيقوم بتخزين هذا الرد تلقائياً
  res.status(201).json(paymentResult);
});

// مثال من طرف العميل (Client-side)
// const idempotencyKey = uuidv4(); // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
// fetch('/api/payments', {
//   method: 'POST',
//   headers: {
//     'Content-Type': 'application/json',
//     'Idempotency-Key': idempotencyKey
//   },
//   body: JSON.stringify({ amount: 100 })
// });

ملاحظة: هذا الكود هو لغرض التوضيح. في بيئة الإنتاج الحقيقية، ستحتاج إلى معالجة حالات أكثر تعقيداً مثل سباق البيانات (Race Conditions) واستخدام مخزن دائم مثل Redis أو قاعدة بيانات.

نصائح أبو عمر العملية للتطبيق

من خبرتي في هذا المجال، إليك بعض النصائح العملية “من الآخر” لتطبيق هذه الآلية بشكل صحيح:

1. توليد المفاتيح من طرف العميل

يجب أن يكون العميل (تطبيق الويب أو الموبايل) هو المسؤول عن توليد المفتاح. استخدم دائماً خوارزمية قوية لتوليد مُعرّفات فريدة عالمياً مثل UUID v4. هذا يضمن عدم حدوث أي تصادم بين مفاتيح مستخدمين مختلفين.

2. اختر مكان التخزين بحكمة

• Redis (أو أي مخزن In-memory): هو الخيار الأفضل في معظم الحالات. إنه سريع جداً ويدعم بشكل أصيل تعيين “وقت انتهاء الصلاحية” (TTL) للمفاتيح، وهو أمر حيوي.
• قاعدة البيانات (Database): خيار جيد إذا كنت تحتاج إلى ضمان بقاء البيانات بشكل دائم. يمكنك إنشاء جدول بسيط (idempotency_key, response_body, status_code, created_at). لكنه أبطأ من Redis.

3. لا تحتفظ بالمفاتيح إلى الأبد!

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

4. تعامل مع حالات السباق (Race Conditions)

ماذا لو وصل طلبان متطابقان بنفس المفتاح في نفس الملي ثانية؟ قد يحاول نظامك معالجتهما معاً. الحل هو استخدام آلية قفل (Locking). عندما يصل الطلب الأول، قم بـ “قفل” المفتاح (سواء بقفل في قاعدة البيانات أو باستخدام أمر مثل SETNX في Redis). الطلب الثاني الذي يصل سيرى المفتاح مقفلاً، فينتظر قليلاً أو يعيد الرد المخزن إذا كان الطلب الأول قد انتهى.

الخلاصة يا جماعة الخير 👍

في عالم الأنظمة الموزعة والشبكات غير الموثوقة، لم تعد “عدمية التكرار” رفاهية، بل هي حجر أساس لبناء أنظمة قوية وموثوقة، خاصة تلك التي تتعامل مع بيانات حساسة أو معاملات مالية.

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