طلباتنا كانت تُنفذ مرتين: كيف أنقذنا ‘مفتاح عدم التكرار’ (Idempotency Key) من جحيم العمليات المكررة؟

يا مية أهلا وسهلا فيكم يا جماعة الخير. اسمي أبو عمر، مبرمج فلسطيني قضيت سنين طويلة من عمري بين الأكواد والشاشات، وخصوصًا في عالم الذكاء الاصطناعي والأنظمة المعقدة. اليوم حابب أحكيلكم قصة صارت معي، قصة فيها شوية توتر، وشوية قهوة، ودرس تعلمته بالطريقة الصعبة، درس عن إشي اسمه “مفتاح عدم التكرار” أو الـ Idempotency Key.

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

في هاي اللحظة، كل الحماس تبخر. “ولعت الدنيا” زي ما بنحكي. فورا فتحت السجلات (logs) وبديت أحقق في الموضوع. الطلب الأول من العميل وصلنا، نظامنا عالجه، وخصم المبلغ من بطاقته بنجاح. بس… قبل ما السيرفر تبعنا يبعت رسالة “تمام، العملية نجحت 200 OK”، الشبكة عملت حركتها الواطية وقطعت! يا إما таймаوت (timeout)، يا إما بروكسي قرر ينام شوي. من جهة العميل، كل اللي شافه هو رسالة خطأ، “فشلت العملية”.

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

بعد ليلة طويلة من البحث والتمحيص، لقينا الحل اللي أنقذنا من هذا الجحيم. الحل كان أبسط مما توقعت، ولكنه قوي جدًا: مفتاح عدم التكرار (Idempotency Key).

ما هو “عدم التكرار” (Idempotency) وشو قصته؟

قبل ما ندخل في تفاصيل المفتاح، خلينا نفهم الكلمة الغريبة هاي: “Idempotency”.

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

تخيل حالك كبست على زر المصعد عشان تطلع على طابقك. كبستك الأولى بتخلي المصعد يستجيب ويجيك. لو رجعت كبست على الزر عشر مرات زيادة، هل رح يجيك عشر مصاعد؟ طبعًا لأ. النتيجة النهائية وحدة: المصعد رح يوصلك. هاي العملية “Idempotent”.

بالمقابل، تخيل إنك بتسحب مصاري من الصراف الآلي. لو طلبت سحب 100 دينار، رح يطلعلك 100 دينار. لو كررت العملية، رح يطلعلك 100 دينار ثانية، ويصير مجموع المسحوب 200. هاي العملية “Non-idempotent” (غير متكررة)، وكل تنفيذ إلها تأثير جديد.

في عالم الـ APIs، طلبات مثل GET و PUT و DELETE مصممة لتكون Idempotent بطبيعتها. أما طلبات POST، فهي بطبيعتها غير متكررة، لأنها مصممة لإنشاء شيء جديد في كل مرة، زي إنشاء طلبية جديدة أو عملية دفع جديدة. ومشكلتنا كانت بالضبط مع طلبات الـ POST.

المشكلة اللي “ولّعت الدنيا”: كوابيس الشبكة والطلبات المكررة

عشان نلخص المشكلة تقنياً، السيناريو الكارثي كان كالتالي:

1. العميل (Client) يرسل طلب دفع: POST /api/v1/payments مع تفاصيل الدفع.
2. الخادم (Server) يستقبل الطلب: يبدأ في معالجة الدفع، يتواصل مع بوابة الدفع، ويخصم المبلغ بنجاح.
3. الشبكة تقرر أن تمزح معنا: قبل أن يتمكن الخادم من إرسال رد 200 OK، ينقطع الاتصال (Network Timeout).
4. العميل في حيرة: من وجهة نظره، الطلب فشل لأنه لم يستلم أي رد. فيقوم نظامه (أو هو يدويًا) بإعادة إرسال نفس الطلب مرة أخرى.
5. الخادم يستقبل الطلب “الجديد”: من وجهة نظر الخادم، هذا طلب POST جديد تمامًا. لا يوجد لديه ذاكرة عن الطلب الأول الذي انقطع رده. فيقوم بمعالجة الدفع مرة أخرى.
6. النتيجة: تم خصم المبلغ من العميل مرتين. يا فرحة ما تمت!

الحل السحري: “مفتاح عدم التكرار” (Idempotency-Key)

هنا يأتي دور البطل، الـ Idempotency-Key. الفكرة عبقرية في بساطتها. إنها عبارة عن “هوية” فريدة لكل عملية نحاول تنفيذها، ونحن نتفق (كمطورين للعميل والخادم) على استخدام هذه الهوية لمنع التكرار.

آلية العمل تسير على النحو التالي:

• جهة العميل (Client-Side): قبل إرسال أي عملية حساسة (مثل الدفع)، يقوم العميل بإنشاء معرف فريد وخاص بهذه العملية. عادةً ما يكون هذا المعرف عبارة عن UUID (Universally Unique Identifier). مثلاً: f1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6.
• إرسال الطلب: يقوم العميل بإرفاق هذا المعرف الفريد في هيدر (Header) خاص ضمن الطلب. الهيدر المتعارف عليه هو Idempotency-Key.
• جهة الخادم (Server-Side): عندما يستقبل الخادم طلبًا يحتوي على هذا الهيدر، يقوم بالآتي:
  1. التحقق من المفتاح: يبحث في قاعدة بيانات مؤقتة (مثل Redis أو جدول في قاعدة البيانات) عن هذا المفتاح.
  2. إذا كان المفتاح جديدًا (غير موجود):
     • هذه هي المرة الأولى التي نرى فيها هذه العملية.
     • يقوم الخادم بتنفيذ العملية المطلوبة (مثل معالجة الدفع).
     • بعد نجاح العملية، يقوم بتخزين نتيجة الرد (Response Body و Status Code) مقابل هذا المفتاح.
     • يرسل الرد المخزن إلى العميل.
  3. إذا كان المفتاح موجودًا بالفعل:
     • هذا يعني أننا قمنا بمعالجة هذه العملية من قبل (وهذا الطلب الحالي هو مجرد إعادة محاولة).
     • الخادم لا ينفذ العملية مرة أخرى.
     • بدلاً من ذلك، يقوم مباشرة بجلب الرد الذي تم تخزينه مسبقًا عند المعالجة الأولى، ويرسله للعميل كما هو.

بهذه الطريقة، حتى لو أرسل العميل الطلب 100 مرة بسبب أخطاء الشبكة، العملية الحقيقية (الدفع) ستنفذ مرة واحدة فقط! وفي كل مرة من الـ 99 المتبقية، سيحصل العميل على نفس الرد الناجح الذي حصل عليه في المرة الأولى، مما يضمن تجربة سلسة وآمنة.

مثال كود: كيف نطبّقها عمليًا؟

لتقريب الصورة، هي مثال بسيط باستخدام Node.js و Express. تخيل أننا نبني Middleware لمعالجة هذه المفاتيح.

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

// Middleware للتعامل مع مفتاح عدم التكرار
function idempotencyMiddleware(req, res, next) {
  // نهتم فقط بطلبات POST و PATCH وغيرها من الطلبات التي تغير البيانات
  if (req.method === 'GET') {
    return next();
  }

  const idempotencyKey = req.headers['idempotency-key'];

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

  // هل هذا المفتاح موجود في مخزننا؟
  if (idempotencyStore.has(idempotencyKey)) {
    console.log(`مفتاح مكرر! ${idempotencyKey}. سنقوم بإرجاع الرد المخزن.`);
    const cachedResponse = idempotencyStore.get(idempotencyKey);
    // نرجع الرد المحفوظ سابقًا
    return res.status(cachedResponse.status).json(cachedResponse.body);
  }

  // هذا مفتاح جديد. نحتاج لتخزين الرد بعد اكتمال العملية
  // نتجاوز دالة res.json الأصلية لنتمكن من التقاط الرد
  const originalJson = res.json;
  res.json = (body) => {
    // نخزن الرد للمستقبل
    const responseToCache = {
      status: res.statusCode,
      body: body,
    };
    idempotencyStore.set(idempotencyKey, responseToCache);
    
    // بعد التخزين، نرسل الرد بشكل طبيعي
    originalJson.call(res, body);
  };

  // الآن، اسمح للطلب بإكمال مساره الطبيعي
  next();
}

// كيف نستخدمه في تطبيق Express
// app.use(idempotencyMiddleware);

// مثال على مسار دفع
app.post('/api/payments', idempotencyMiddleware, (req, res) => {
  // ... منطق معالجة الدفع هنا ...
  // هذا الكود سينفذ مرة واحدة فقط لنفس المفتاح
  console.log('جاري معالجة عملية دفع جديدة...');
  
  const paymentResult = { transactionId: 'txn_' + Date.now(), status: 'completed' };

  res.status(201).json(paymentResult);
});

هذا مجرد مثال توضيحي، التطبيق الحقيقي يحتاج معالجة أفضل للحالات الحرجة وتخزين موثوق.

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

بعد ما انحرقنا مرة، تعلمنا الدرس كويس. إليكم شوية نصائح من خبرتي المتواضعة عشان تطبقوا هالمبدأ صح من أول مرة:

1. وين نخزّن المفاتيح؟ (Where to store the keys?)

المخزن اللي استخدمته في المثال (Map) هو للتعليم فقط لأنه يضيع مع إعادة تشغيل السيرفر. في الواقع، أفضل خيار هو Redis. ليش؟ لأنه سريع جدًا ويدعم ميزة تحديد مدة صلاحية للمفتاح (TTL) بشكل أصيل، وهذا بالضبط ما نحتاجه.

2. مدة صلاحية المفتاح (Key Expiration)

لا تترك المفاتيح في مخزنك إلى الأبد! هذا سيؤدي إلى تضخم مساحة التخزين بلا فائدة. القاعدة العامة هي تحديد مدة صلاحية معقولة، عادة 24 ساعة. هذا يعطي العميل وقتًا كافيًا لإعادة المحاولة في حال حدوث خطأ، وفي نفس الوقت يضمن تنظيف المخزن تلقائيًا.

3. متى نستخدمه؟ (When to use it?)

لا تستخدمه على كل طلب! هذا حمل إضافي بلا داعي. استخدمه فقط على العمليات الحساسة وغير المتكررة بطبيعتها (non-idempotent) والتي لا تريد أن تتكرر أبدًا. أفضل المرشحين هم:

• إنشاء عمليات دفع (POST /payments)
• إنشاء طلبات شراء (POST /orders)
• إرسال رسائل حساسة لا يجب أن تصل مرتين (POST /messages)

4. توليد المفتاح (Key Generation)

يجب أن تكون مسؤولية توليد المفتاح على جهة العميل. يجب أن يكون المفتاح فريدًا بما فيه الكفاية لتجنب التصادم. المعيار الذهبي هنا هو استخدام UUID v4. وعلى العميل أن يتأكد من استخدام نفس المفتاح لجميع محاولات إعادة إرسال نفس العملية.

5. التعامل مع الحالات الحرجة (Handling Race Conditions)

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

الخلاصة: لا تترك الشبكة تدمر شغلك

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

مفتاح عدم التكرار (Idempotency Key) ليس مجرد تقنية للمطورين المحترفين، بل هو ضرورة أساسية لأي نظام يتعامل مع عمليات حساسة. إنه استثمار صغير في الكود يمنحك راحة بال كبيرة ويحميك من كوارث مالية، وفنية، ومن إحراج كبير مع عملائك.

منذ تلك الليلة، أصبح هيدر Idempotency-Key صديقنا الصدوق في كل مشروع جديد. تعلمناه بالطريقة الصعبة، لكن أتمنى أن تكون قصتي هذه قد علمتكم إياه بالطريقة الأسهل.

يلا يا جماعة، شدّوا حيلكم وخلّوا تطبيقاتكم حديد! 💪