يرسل العميل الطلب POST /payments. يخصم الخادم المبلغ من البطاقة، ويسجّل العملية في قاعدة البيانات، ويبدأ في إرسال الرد. ثم ينقطع الاتصال. من وجهة نظر العميل، فشل الطلب. ومن وجهة نظر الخادم، نجح. يعيد العميل المحاولة، فيُخصم المبلغ من العميل مرتين.
هذه ليست حالة نادرة. شبكات الموبايل، ومهلات موازن الأحمال، وعمليات النشر، وفقدان الحزم العادي، كلها تُنتجها. أي واجهة API تُنشئ شيئًا أو تحرّك أموالًا تحتاج إجابة واضحة عن سؤال واحد: ماذا يحدث عندما يصل الطلب نفسه مرتين؟
ما معنى idempotent فعلًا
تكون العملية idempotent (آمنة عند التكرار) عندما يكون تنفيذها عدة مرات له الأثر نفسه على الخادم كتنفيذها مرة واحدة. بروتوكول HTTP يعرّف GET وPUT وDELETE كطرق idempotent أصلًا: ضبط مورد على قيمة مرتين يتركه على تلك القيمة، وحذف شيء مرتين يتركه محذوفًا.
المشكلة في POST. عملية "إنشاء دفعة" بطبيعتها ليست idempotent؛ كل استدعاء يُنشئ دفعة جديدة. ولكي تصبح إعادة المحاولة آمنة، يجب أن نعطي الخادم طريقة ليتعرّف على أن طلبين هما العملية المنطقية نفسها.
لاحظ أن الـ idempotency تتعلق بالأثر لا بالرد. قد يعيد طلب DELETE الثاني 404 بدل 204؛ ولا مشكلة في ذلك طالما لم يحدث شيء إضافي.
نمط مفتاح التكرار (Idempotency Key)
يولّد العميل مفتاحًا فريدًا لكل عملية منطقية (يكفي UUID) ويرسله مع الطلب:
POST /payments HTTP/1.1
Idempotency-Key: 7f3c2a8e-0c4b-4b8e-9a51-3f1d2c6e9b10
Content-Type: application/json
{"amount": 4200, "currency": "EUR", "customer": "cus_123"}إذا أُعيد الطلب، يرسل العميل المفتاح نفسه. يخزّن الخادم المفتاح مع نتيجة المحاولة الأولى، وعند التكرار يعيد تلك النتيجة المخزنة بدل تنفيذ العمل مرة أخرى.
ثلاث قواعد تجعل هذا يعمل:
- المفتاح محصور النطاق. خزّنه لكل عميل أو مستأجر (tenant)، حتى لا يتصادم مفتاحان لعميلين مختلفين.
- المفتاح مرتبط بالطلب. خزّن بصمة (hash) لمحتوى الطلب. إذا وصل المفتاح نفسه بمحتوى مختلف، فهذا خطأ عند العميل ويجب أن يفشل بـ
422، لا أن يعيد النتيجة القديمة بصمت. - المفاتيح تنتهي صلاحيتها. إعادة المحاولة تحدث خلال دقائق أو ساعات. الاحتفاظ بالمفاتيح 24 ساعة نافذة شائعة ومعقولة.
التعامل مع التكرار المتزامن
الحالة الدقيقة هي وصول طلبين متطابقين في اللحظة نفسها، مثلًا من عميل يعيد المحاولة بإلحاح. كلاهما يبحث عن المفتاح، وكلاهما لا يجده، وكلاهما ينفّذ العمل.
الحل هو حجز المفتاح بشكل ذرّي قبل تنفيذ العمل، باستخدام ضمان التفرّد في قاعدة البيانات:
CREATE TABLE idempotency_keys (
tenant_id uuid NOT NULL,
key text NOT NULL,
request_hash bytea NOT NULL,
status text NOT NULL DEFAULT 'in_progress', -- in_progress | completed
response_code int,
response_body jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, key)
);يُدخل المعالج الصف أولًا. طلب واحد فقط ينجح في الإدخال؛ والبقية يواجهون تعارضًا، فإما أن ينتظروا أو يعيدوا 409 Conflict ليطلبوا من العميل إعادة المحاولة بعد قليل.
func (s *Server) CreatePayment(ctx context.Context, tenant uuid.UUID, key string, req PaymentRequest) (Response, error) {
hash := sha256.Sum256(req.CanonicalJSON())
claimed, err := s.db.ClaimKey(ctx, tenant, key, hash[:])
if err != nil {
return Response{}, err
}
if !claimed {
existing, err := s.db.GetKey(ctx, tenant, key)
if err != nil {
return Response{}, err
}
switch {
case !bytes.Equal(existing.RequestHash, hash[:]):
return Response{Code: 422, Body: errorBody("idempotency key reused with a different request")}, nil
case existing.Status == "in_progress":
return Response{Code: 409, Body: errorBody("request with this key is still being processed")}, nil
default:
return Response{Code: existing.ResponseCode, Body: existing.ResponseBody}, nil
}
}
resp, err := s.chargeAndRecord(ctx, tenant, req)
if err != nil {
// Release the key so a retry can try again; the work did not complete.
_ = s.db.DeleteKey(ctx, tenant, key)
return Response{}, err
}
return resp, s.db.CompleteKey(ctx, tenant, key, resp.Code, resp.Body)
}الدالة ClaimKey هي أمر INSERT … ON CONFLICT DO NOTHING واحد يخبرك هل أُدخل صف أم لا.
أبقِ الآثار الجانبية داخل المعاملة قدر الإمكان
ما زالت في المثال السابق ثغرة: إذا توقفت العملية بعد خصم المبلغ وقبل CompleteKey، يبقى المفتاح في حالة in_progress وتصبح النتيجة مجهولة.
عندما يكون العمل كتابات في قاعدة البيانات فقط، فالحل الأنظف هو إكمال المفتاح في المعاملة نفسها مع كتابات العمل. إما أن يُثبَّت الاثنان معًا أو لا شيء.
وعندما يستدعي العمل نظامًا خارجيًا، مثل مزوّد خدمة دفع، لا يمكنك وضعه داخل معاملتك. هنا تساعد تقنيتان:
- مرّر مفتاح التكرار إلى المزوّد. كثير من المزوّدين يقبلون مفتاح idempotency خاصًا بهم. اشتقاقه من مفتاحك يعني أن المزوّد سيحذف تكرار محاولاتك أيضًا.
- سجّل النية أولًا ونفّذ لاحقًا. اكتب العملية المقصودة في جدول outbox داخل المعاملة، ودع عاملًا خلفيًا (worker) ينفّذ الاستدعاء الخارجي مع إعادة المحاولة. هذا هو نمط الـ transactional outbox، وهو يحوّل سؤال "هل حدث ذلك؟" إلى "سيحدث مرة واحدة بالضبط من وجهة نظر المزوّد".
الـ Idempotency خارج HTTP
التفكير نفسه ينطبق في أي مكان يمكن أن تُسلَّم فيه الرسائل أكثر من مرة:
- الـ Webhooks من المزوّدين تُسلَّم مرة واحدة على الأقل. احذف المكرر بمعرّف الحدث لدى المزوّد قبل التنفيذ.
- مستهلكو الطوابير قد يرون الرسالة مرة أخرى بعد عطل أو انتهاء مهلة الظهور. اجعل المعالج idempotent، أو سجّل معرّفات الرسائل التي عولجت.
- عمليات الاستيراد بالدفعات التي يمكن إعادة تشغيلها يجب أن تستخدم upsert بمعرّف طبيعي، لا إدخالًا أعمى.
عمليًا، التسليم "مرة واحدة بالضبط" نادرًا ما يكون متاحًا. ما يمكنك بناؤه هو تسليم مرة واحدة على الأقل مع معالجة idempotent، وله الأثر الظاهر نفسه.
قائمة مراجعة
- كل نقطة نهاية غير idempotent قد يعيد العملاء محاولتها تقبل
Idempotency-Key. - المفاتيح محصورة لكل مستأجر أو عميل ومرتبطة ببصمة الطلب.
- يُحجز المفتاح بشكل ذرّي قبل بدء العمل.
- التكرار المتزامن يحصل على
409واضح، والمحتوى غير المطابق على422. - يُعاد الرد المخزن عند التكرار، بما في ذلك رمز الحالة الأصلي.
- تنتهي صلاحية المفاتيح بعد نافذة زمنية موثقة.
- الآثار الجانبية الخارجية تستخدم مفاتيح idempotency لدى المزوّد أو نمط outbox.
- مستهلكو الـ Webhooks والطوابير يحذفون المكرر بمعرّفات الرسائل.
تصميم هذا من الإصدار الأول يكلّف القليل جدًا. أما إضافته بعد أول خصم مزدوج فأغلى بكثير، في وقت المهندسين وفي ثقة العملاء معًا.



