Idempotency: السر وراء APIs مالية آمنة

Retries تجعل Idempotency متطلبًا ماليًا

الشبكات تكرر الطلبات: العميل يعيد بعد Timeout، والبوابة قد تعيد الإرسال، والWorker يعيد الرسالة، والمستخدم يضغط الإرسال مرة أخرى. في API مالية لا يكفي «غالبًا مرة واحدة». Idempotency تجعل عمليات التسليم المتعددة للأمر المنطقي نفسه تؤدي إلى نتيجة مرجعية واحدة.

اختر هوية العملية

استخدم Idempotency Key من المستدعي ومقيدًا بالحساب/المستأجر ونوع العملية.
خزن المفتاح وبصمة الطلب والحالة والنتيجة في تخزين دائم.
إعادة استخدام المفتاح مع Body مختلف تعارض وليست نجاحًا مكررًا.
احجز المفتاح ذريًا قبل تنفيذ أي أثر غير قابل للعكس.
أعد الاستجابة المخزنة للطلب المكرر المكتمل وحدد سلوكًا واضحًا للحالة قيد التنفيذ.

مسار الطلب الأول والطلب المكرر

يُفحص المفتاح ويُحجز قبل تنفيذ العمل، ثم ترى المحاولات اللاحقة النتيجة الدائمة نفسها بدل تنفيذ التحويل مرة ثانية.

Diagram

أمر دفع آمن أمام التكرار

POST + Idempotency Key

حجز ذري للمفتاح

التحقق من البصمة

تنفيذ الدفع

حفظ الاستجابة

الإعادة ترجع النتيجة المخزنة

مثال إنشاء دفعة

المفتاح الفريد هو حارس التزامن

قيد Unique في قاعدة البيانات يمنع عاملين من امتلاك الأمر المنطقي نفسه.

CREATE TABLE api_idempotency (
  tenant_id text NOT NULL,
  operation text NOT NULL,
  idem_key text NOT NULL,
  request_hash text NOT NULL,
  status text NOT NULL,
  response_ref text,
  PRIMARY KEY (tenant_id, operation, idem_key)
);

أنماط Idempotency الزائفة

قائمة تطبيق Idempotency

حدد نطاق المفتاح ومدة الاحتفاظ.
خزن بصمة Canonical للطلب.
اجعل حجز المفتاح ذريًا ومحميًا من التزامن.
خزن الحالة النهائية ومرجع الاستجابة.
اختبر Duplicate متزامنًا ومحاكاة ضياع الاستجابة.