ضمانات تسليم الويب

خطوط الويب هي إشعارات غير متزامنة من نظام إلى مشترك عبر HTTP (S). الشبكة غير موثوقة: تضيع الاستجابات، وتأتي الحزم مكررة أو معطلة. وبالتالي، فإن ضمانات التسليم ليست مبنية «على برنامج التعاون الفني»، بل على مستوى بروتوكول الخطاف الشبكي وحجية المجال.

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

1) مستويات الضمان

أفضل جهد - محاولة لمرة واحدة، دون عودة. مقبول فقط للأحداث «غير المهمة».
مرة واحدة على الأقل (موصى بها) - من الممكن تكرار الحدث وخارج الطلب، ولكن سيتم تسليم الحدث بشرط أن يكون المشترك متاحًا في غضون وقت معقول.
بشكل فعال - مرة واحدة بالضبط (على مستوى التأثير) - يتم تحقيقه من خلال مزيج من الخصوصية والتخزين على جانب المشترك/المرسل. نقل HTTP «مرة واحدة بالضبط» غير ممكن.

2) عقد الويب: الحد الأدنى المطلوب

X-Webhook-Id: 5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21  # глобальный ID события
X-Delivery-Attempt: 3                 # номер попытки
X-Event-Type: payment.authorized.v1          # тип/версия
X-Event-Time: 2025-10-31T12:34:56Z          # ISO8601
X-Partition-Key: psp_tx_987654            # ключ порядка
X-Seq: 418                      # монотонный номер по ключу
X-Signature-Alg: HMAC-SHA256
X-Signature: t=1730378096,v1=hex(hmac(secret, t        body))
Content-Type: application/json

json
{
"id": "5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21",
"type": "payment.authorized.v1",
"occurred_at": "2025-10-31T12:34:56Z",
"partition_key": "psp_tx_987654",
"sequence": 418,
"data": {
"payment_id": "psp_tx_987654",
"amount": "10.00",
"currency": "EUR",
"status": "AUTHORIZED"
},
"schema_version": 1
}

شرط المتلقي: الرد بسرعة «2xx» بعد تخزين التوقيع والتحقق من صحته، والقيام بمعالجة الأعمال التجارية بشكل غير متزامن.

3) الترتيب والسببية

الترتيب الرئيسي: الضمان «لن يترك» داخل واحد فقط «التقسيم _ المفتاح» (على سبيل المثال «player _ id»، «wallet _ id'،» psp _ tx _ id').
النظام العالمي غير مضمون.
على جانب المرسل، هناك قائمة انتظار مع تسلسل حسب المفتاح (مستهلك واحد/شحن)، على جانب المستلم يوجد صندوق الوارد مع «(المصدر، event_id)» وينتظر اختياريًا «seq» المفقود.

إذا كانت الفجوات حرجة - توفير Pull-API 'GET/الأحداث ؟ بعد = نقطة تفتيش «للحاق بالركب والتشاور».

4) الخصوصية والتفريط

يحمل كل خط ويب «معرف X-Webhook-Id» ثابتًا.
صندوق الوارد (event_id): PK - 'source + event_id'; تكرر → عدم العملية.
الآثار الجانبية (الكتابة إلى قاعدة البيانات/المحفظة) يتم إجراؤها مرة واحدة فقط عندما يتم «رؤية» الحدث لأول مرة.
بالنسبة للأوامر ذات التأثير، استخدم Idempotency-Key وذاكرة التخزين المؤقت للنتيجة لمدة نافذة إعادة الدفع.

5) Retrai، التراجع والنوافذ

• إعادة التدريب إلى «5xx/timeout/connection error/409-Conflict (قابل للإعادة )/429».
• لا تتراجع عن «4xx» باستثناء «409/423/429» (وفقط بدلالات متسقة).
• التراجع الأسي + النبض الكامل: 0. 5s، 1s، 2s، 4s، 8s،... حتى 'الحد الأقصى = 10-15 دقيقة' ؛ TTL إعادة تشغيل النوافذ: على سبيل المثال، 72 ساعة.
• احترام «إعادة المحاولة بعد» من المتلقي.
• لديك موعد نهائي مشترك: «تعرف على الحدث على أنه لم يتم تسليمه» ونقله إلى DLQ.

yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]

6) DLQ и إعادة التوليد

DLQ - «مقبرة» الأحداث السامة أو التي انتهت صلاحيتها مع معلومات فوقية كاملة (حمولة، رؤوس، أخطاء، محاولات، تجزئة).
وحدة تحكم الويب/واجهة برمجة التطبيقات لإعادة التوليد (إعادة تسليم النقطة) مع نقطة النهاية الاختيارية/التحرير السري.
إعادة التوليد المحدودة المعدل وإعادة الدفعة مع إعطاء الأولوية.

7) السلامة

mTLS (إن أمكن) أو TLS 1. 2+.

1. استخراج '(طابع زمني) من الرأس، تحقق من النافذة المنزلقة (على سبيل المثال، ± 5 دقائق).

8) الحصص وحدود الأسعار والمساواة

قائمة انتظار عادلة لكل مستأجر/مشترك: بحيث لا يسجل مشترك/مستأجر واحد المجموعة الإجمالية.
الحصص والحدود المتفجرة لحركة المرور المنتهية ولايتها ونقطة النهاية الواحدة.
رد الفعل على '429': تكريم 'Retry-After'، تيار القزم ؛ للحدود الطويلة الأجل - التحلل (إرسال أنواع الأحداث الحرجة فقط).

9) دورة حياة الاشتراك

التسجيل/التحقق: نقطة نهاية POST → التحدي/الاستجابة أو التأكيد خارج النطاق.
عقد الإيجار (اختياري): التوقيع ساري المفعول حتى 'صالح - إلى' ؛ الإطالة - صريح.
التناوب السري: "الحالي _ السري"، "التالي _ السري" с "التبديل _ at'.
اختبار ping: حدث اصطناعي لاختبار المسار قبل تشغيل الموضوعات الرئيسية.
العينات الصحية: HEAD/GET الدورية مع الكمون وفحص ملف تعريف TLS.

10) تطور المخططات (نسخ الأحداث)

نوع حدث الإصدار: "الدفع. المأذون به. v1 '→'... v2 '.
التطور - إضافة (حقول جديدة → إصدارات واجهة برمجة التطبيقات الصغيرة)، كسر → نوع جديد.
سجل المخطط (JSON-Schema/Avro/Protobuf) + التحقق التلقائي قبل التقديم.
مطلوب رأس «X-Event-Type» وحقل «schema _ version» في الجسم.

11) إمكانية الرصد و SLO

• «التسليم _ المجموع»، «2xx/4xx/5xx _ rate»، «timeout _ rate»، «signature _ fail _ rate».
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (publish to 2xx).
• «dedup _ rate»، «out _ of _ order _ rate»، «dlq _ rate»، «redrive _ success _ rate».
• "queue _ depth"، "أقدم _ في _ قائمة الانتظار _ ms'،" أحداث دواسة الوقود ".

• حصة عمليات التسليم ≤ 60 (ص 95) - 99. 5٪ للأحداث الحرجة.
• DLQ ≤ 0. 1٪ في 24 ساعة
• فشل التوقيع ≤ 0. 05%.

Логи/трейсинг: 'event _ id', 'partition _ key', 'seq', 'terry', 'endpoint', 'tenant _ id', 'schema _ version', 'trace _ id'.

12) خوارزمية مرجعية المرسل

1. اكتب الحدث إلى صندوق المعاملات الخارجي.
2. تحديد partition_key والمقاييس ؛ قائمة الانتظار.
3. يأخذ العامل بالمفتاح، ويشكل طلبًا، ويوقع، ويرسل مع مهلات (اتصال/اقرأ).
4. باستخدام «2xx» - تم التعرف عليه على أنه تم تسليمه، وقم بإصلاح زمن الوصول ونقطة التفتيش seq.
5. مع «429/5xx/مهلة» - تراجع وفقًا للسياسة.
6. بواسطة TTL → DLQ والتنبيه.

13) معالج مرجعي (جهاز استقبال)

1. قبول الطلب، تحقق من TLS/proto.
2. التصديق على التوقيع والنافذة الزمنية.
3. Fast ACK 2xx (بعد الكتابة المتزامنة إلى صندوق الوارد المحلي/قائمة الانتظار).
4. يقرأ العامل غير المتزامن «inbox»، ويتحقق من «event _ id» (الجد)، إذا لزم الأمر، أوامر من خلال «seq» inside «التقسيم _ المفتاح».
5. يؤدي التأثيرات، يكتب «نقطة تفتيش الأوفست/seq» للتوفيق.
6. في حالة الخطأ - عمليات إعادة التدوير المحلية ؛ المهام «السامة» → DLQ المحلي مع التنبيهات.

14) التوفيق (حلقة البلياردو)

• 'الحصول على/الأحداث ؟ partition_key=...&after_seq=...&limit=...' - لإعطاء كل ما فاتته.
• نقطة تفتيش رمزية: «after = opaque _ token» بدلاً من seq.
• إعادة التسليم الفطري: نفس 'event _ id'، نفس التوقيع على 't' الجديد.

15) عناوين ورموز مفيدة

2xx - مقبول (حتى لو كانت المعالجة التجارية لاحقة).
410 ذهب - تم إغلاق نقطة النهاية (توقف المرسل عن التسليم ووصف الاشتراك بأنه «محفوظ»).
409/423 - الحجب المؤقت للموارد → إعادة الدفع معقول.
429 - في كثير من الأحيان → دواسة الوقود والتراجع.
400/401/403/404 - خطأ في التشكيل ؛ أوقف الريتراي، افتح التذكرة.

16) متعدد المستأجرين والمناطق

قوائم الانتظار الفردية والحدود لكل مستأجر/نقطة النهاية.
الإقامة في مجال البيانات: إرسال البيانات من المنطقة ؛ رؤوس من طرف إلى طرف "X-Tenant'،" X-Region ".
عزل الإخفاقات: لا يؤثر سقوط مشترك واحد على الباقي (مجمعات منفصلة).

17) الاختبار

اختبارات العقد: أمثلة ثابتة للهيئات/التوقيعات، التحقق من الصحة.
الفوضى: إسقاط/تكرار، ترتيب خلط، تأخير الشبكة، أخطاء RST، TLS.
الحمل: عاصفة انفجار، مقاس p95/p99.
الأمن: مكافحة الإعادة، طابع زمني قديم، أسرار خاطئة، تناوب.
DR/Replay: Mass redrive من DLQ في حامل معزول.

18) كتب اللعب (كتب التشغيل)

1. توقيع النمو _ فشل _ معدل

تحقق من انجراف الساعة، «التسامح» المنتهي الصلاحية، تناوب الأسرار ؛ تمكين مؤقتا «سر مزدوج».

2. قائمة الانتظار تتقدم في السن ("الأقدم _ في _ قائمة الانتظار _ ms' ↑)

زيادة عدد العمال، وتمكين تحديد أولويات الموضوعات الحاسمة، وتقليل تواتر الأنواع «الصاخبة» مؤقتًا.

3. العاصفة «429» عند المشترك

تمكين الاختناق والتوقف بين المحاولات ؛ أنواع الأحداث الأقل أهمية.

4. الكتلة '5 × x'

قاطع دائرة مفتوحة لنقطة نهاية محددة، تبديل إلى مؤجل & back; إشارة إلى المشترك.

5. ملء DLQ

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

19) أخطاء نموذجية

المعالجة الثقيلة المتزامنة لاستجابة 2xx → إعادة نسخ ونسخ.
لا يوجد توقيع على نافذة الجسم/الوقت → الاستبدال/إعادة التشغيل.
لا يمكن جعل غياب → 'event _ id' و 'inbox' غير واقعي.
محاولة «النظام العالمي» → أقفال قائمة الانتظار الأبدية.
التراجع دون نفث/الحد → تكثيف الحوادث (قطيع مدوي).
تجمع مشترك واحد لجميع المشتركين → «صاخب» يضع الجميع.

20) قائمة مرجعية قبل البيع

• العقد: "حدث _ معرف"، "تقسيم _ مفتاح"، "seq"، "حدث _ نوع. vN '، توقيع HMAC والطابع الزمني.
• المرسل: outbox، التسلسل حسب المفتاح، إعادة التدوير مع backoff + jitter، TTL، DLQ وإعادة التوليد.
• المتلقي: الكتابة السريعة إلى البريد الوارد + 2xx ؛ والمعاملة الخفية ؛ DLQ المحلي.
• الأمن: TLS، التوقيعات، منع إعادة التشغيل، مزدوج السرية، التناوب.
• الحصص/الحدود: قائمة الانتظار العادلة لكل مستأجر/نقطة النهاية، احترام «إعادة التجربة بعد».
• التوفيق بين واجهات برمجة التطبيقات ونقاط التفتيش ؛ وثائق المشتركين.
• قابلية الرصد: p95/threads/errors/DLQ، تتبع 'event _ id'.
• إصدار الأحداث وسياسة تطور المخطط.
• كتب اللعب الخاصة بالحوادث وزر التوقف/إزالة الجليد العالمي.

خامسا - الاستنتاج

خطوط الويب الموثوقة هي بروتوكول أعلى HTTP، وليس فقط "POST with JSON. "العقد الواضح (المعرف، مفتاح الطلب، التوقيع)، الغباء، إعادة الدرج مع النفاخ، قائمة الانتظار العادلة وكتب اللعب المجهزة جيدًا تحول أفضل الحالات إلى آلية تسليم يمكن التنبؤ بها وقابلية للقياس. قم ببناء مرة واحدة على الأقل + ترتيب المفتاح + التوفيق، وسينجو النظام بهدوء من الشبكة وقمم التحميل والأخطاء البشرية.