> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# تواصل الخدمات Microservices: REST وgRPC أم الرسائل؟
- URL: https://arabroot.io/articles/تواصل-الخدمات-microservices-rest-و-grpc-ام-الرسائل/
- Published: 2026-11-18T12:30:48.000Z
- Updated: 2026-11-18T13:31:19.000Z
- Description: قسنا نفس طلب الشراء بين ثلاث خدمات عبر REST وgRPC والأحداث، ثم أوقفنا خدمة المخزون لنرى أي أسلوب يسقط النظام كله وكيف تمنع ذلك.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, هندسة البرمجيات والـ Backend, DevOps وCI/CD, الاستضافة الذاتية

قسمت المتجر إلى ثلاث خدمات كما يقول الكتاب: خدمة الطلبات Orders التي يتعامل معها الموقع، وخدمة المدفوعات Payments التي تخصم المبلغ، وخدمة المخزون Inventory التي تحجز الكتب من المستودع. وفي التطبيق الواحد القديم كان إتمام الطلب سطرين في نفس الكود، استدعاء دالة `charge()` ثم دالة `reserve()`، وكل استدعاء يأخذ أجزاءً من الميكروثانية ولا يفشل إلا إذا كان في الكود خطأ. والآن أصبح كل سطر منهما طلباً يخرج من السيرفر ويعبر الشبكة إلى خدمة أخرى لها نشرها وإصداراتها وأعطالها، وفي أول يوم يعمل كل شيء. ثم ينشر فريق المخزون إصداراً جديداً يتجمد عند الاتصال بقاعدة البيانات، فلا يرد ولا يرفض، وبعد دقيقة تتوقف صفحة الطلبات كلها، ثم يبدأ موزع الطلبات Load Balancer بإخراج خدمة الطلبات لأن فحص الصحة Health Check فيها لم يعد يرد، مع أن خدمة الطلبات نفسها لم يتغير فيها سطر واحد.

وهذا السيناريو ليس نادراً، فهو ما يحدث تقريباً لكل فريق في أول شهر بعد التقسيم، والسبب أن السؤال الذي يبدأ به الأغلب «هل نستخدم REST أم gRPC؟» ليس السؤال الأول. والسؤال الأهم هو: هل يجب أن تنتظر خدمة الطلبات رد الخدمة الأخرى قبل أن ترد على العميل، أم يكفي أن تخبرها بما حدث وتكمل؟ وقد شرحنا متى يستحق التقسيم ثمنه في مقال [Monolith أم Microservices](https://arabroot.io/articles/monolith-%D8%A7%D9%85-microservices-%D9%82%D8%B1%D8%A7%D8%B1-%D8%B5%D8%A7%D8%AF%D9%82-%D9%84%D9%84%D9%81%D8%B1%D9%82-%D8%A7%D9%84%D8%B5%D8%BA%D9%8A%D8%B1%D8%A9-%D9%88%D8%A7%D9%84%D9%83%D8%A8%D9%8A%D8%B1%D8%A9/)، وشرحنا تصميم واجهة REST وgRPC نفسها والتوافق بين الإصدارات في [مقال تصميم واجهات API](https://arabroot.io/articles/%D8%AA%D8%B5%D9%85%D9%8A%D9%85-%D9%88%D8%A7%D8%AC%D9%87%D8%A7%D8%AA-api-rest-%D9%88-grpc-%D9%88-graphql/)، وهذا المقال يأخذ الخطوة التالية: كيف تتكلم الخدمات مع بعضها في تدفق حقيقي، وماذا يكلفك كل أسلوب بالأرقام، وماذا يحدث لكل أسلوب عندما تسقط خدمة واحدة.

وسوف نناقش في هذا المقال ما يلي:

- ما الذي يتغير عندما يصبح استدعاء الدالة طلباً على الشبكة، ولماذا تضرب نسب التوفر في بعضها.
- الفرق بين الاتصال المتزامن Synchronous وغير المتزامن Asynchronous، والاقتران الزمني Temporal Coupling الذي يخفيه الأول.
- كيف يعمل الاستدعاء عبر REST وعبر gRPC من الداخل، وما الذي يتغير عندما ترسل رسالة إلى وسيط Broker بدلاً من طلب.
- الأوامر Commands والأحداث Events، والتنسيق المركزي Orchestration والتنسيق بالأحداث Choreography.
- العقود Contracts المكتوبة لكل أسلوب: OpenAPI وprotobuf وAsyncAPI، وما الذي يخل بالتوافق في كل منها.
- تجربة عملية لنفس تدفق الطلب بين ثلاث خدمات بالأساليب الثلاثة: زمن الاستجابة وحجم البيانات على الشبكة، ثم نوقف خدمة المخزون ونرى السقوط المتتالي Cascading Failure ونصلحه.
- جدول اختيار تحدد به أسلوب كل تواصل في نظامك.

## ما الذي يتغير عندما يصبح استدعاء الدالة طلباً على الشبكة؟

استدعاء الدالة داخل نفس البرنامج له خصائص لا تفكر فيها لأنها مضمونة: إما أن ينجح أو يرمي استثناءً Exception تعرف سببه، وزمنه ثابت تقريباً، ولا يمكن أن ينفذ مرتين دون أن تطلب ذلك، ولا يمكن أن ينفذ دون أن تعرف. وعندما تنقل الدالة إلى خدمة أخرى تفقد هذه الخصائص كلها في نفس اللحظة، فالطلب قد يصل وينفذ ويضيع الرد في الطريق، فلا تعرف هل خصم المبلغ أم لا، وقد يتأخر الرد ثانية أو دقيقة أو لا يأتي أبداً، وقد تعيد المحاولة فينفذ مرتين. وهذه الحالات لا تظهر في بيئة التطوير لأن الخدمات كلها على جهازك، وتظهر في الإنتاج Production عندما يزدحم سيرفر أو يعاد تشغيل Container أو ينشر فريق آخر إصداره.

وقد جمع Peter Deutsch وزملاؤه في Sun Microsystems في التسعينات هذه الافتراضات الخاطئة في قائمة مشهورة تسمى مغالطات الحوسبة الموزعة Fallacies of Distributed Computing، وأولها أن الشبكة موثوقة، وثانيها أن زمن الاستجابة Latency صفر، وثالثها أن عرض النطاق Bandwidth لا ينتهي. وكل أسلوب تواصل في هذا المقال هو في الحقيقة طريقة للتعامل مع هذه المغالطات، وقد شرحنا الجانب النظري للفشل في الأنظمة الموزعة في [مقال الأنظمة الموزعة للمبتدئين](https://arabroot.io/articles/%D8%A7%D9%84%D8%A7%D9%86%D8%B8%D9%85%D8%A9-%D8%A7%D9%84%D9%85%D9%88%D8%B2%D8%B9%D8%A9-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86-cap-%D9%88%D8%A7%D9%84%D8%A7%D8%AA%D8%B3%D8%A7%D9%82-%D9%88%D8%A7%D9%84%D8%A7%D8%AC%D9%85%D8%A7%D8%B9/)، وهنا نهتم بالجانب الذي يكتبه المطور كل يوم: الطلب بين خدمتين.

### لماذا تضرب نسب التوفر في بعضها؟

لنفرض أن كل خدمة من الخدمات الثلاث متاحة 99.9% من الوقت، وهو رقم جيد يعني حوالي 43 دقيقة توقف في الشهر لكل خدمة. فإذا كانت خدمة الطلبات لا تستطيع أن تكمل طلباً إلا إذا ردت عليها المدفوعات والمخزون في نفس اللحظة، فإن توفر عملية الطلب هو حاصل ضرب الثلاثة: 0.999 × 0.999 × 0.999 = 0.997، أي 99.7%، وهذا يعني حوالي ساعتين و10 دقائق توقف في الشهر بدلاً من 43 دقيقة. والسبب أن أعطال الخدمات لا تحدث في نفس الوقت، فكل توقف في أي خدمة منها يصبح توقفاً لعملية الطلب كلها. ومع عشر خدمات في سلسلة واحدة يصبح الرقم 99%، أي أكثر من سبع ساعات في الشهر، وهذا هو الثمن الخفي للسلسلة الطويلة من الاستدعاءات المتزامنة، وقد شرحنا معنى هذه النسب وكيف تتفق عليها مع فريقك في [مقال أهداف الخدمة SLO](https://arabroot.io/articles/%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D8%B9%D9%86%D9%8A-99-9-%D8%A7%D9%87%D8%AF%D8%A7%D9%81-%D8%A7%D9%84%D8%AE%D8%AF%D9%85%D8%A9-slo-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/).

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

## متزامن أم غير متزامن؟ Synchronous vs Asynchronous

الاتصال المتزامن Synchronous يعني أن الخدمة المستدعية ترسل الطلب ثم تنتظر الرد قبل أن تكمل عملها، مثل المكالمة الهاتفية: لا تستطيع أن تنهي المكالمة قبل أن تسمع الجواب. والاتصال غير المتزامن Asynchronous يعني أن الخدمة ترسل رسالة إلى وسيط الرسائل Message Broker ثم تكمل عملها دون أن تنتظر من سوف يستقبلها ومتى، مثل الرسالة النصية: ترسلها وتعود لعملك، والطرف الآخر يقرأها عندما يتفرغ، ولو كان هاتفه مغلقاً الآن فسوف تصله عندما يفتحه.

ويجب أن تفرق هنا بين أمرين يخلط بينهما كثيرون: الكود غير المتزامن مثل `async/await` في Python وJavaScript، والتواصل غير المتزامن بين الخدمات. فخدمة تستدعي خدمة أخرى عبر REST بكود `await client.post(...)` ما زالت تتواصل بشكل متزامن، لأنها لا ترد على عميلها حتى يصلها الرد، وكل ما فعله `await` أنه حرر الخيط Thread ليخدم طلبات أخرى أثناء الانتظار. أما التواصل غير المتزامن فمعناه أن الرد على العميل لا يعتمد على أن الخدمة الأخرى حاضرة الآن.

### الاقتران الزمني Temporal Coupling

في [مقال الاقتران والتماسك](https://arabroot.io/articles/%D8%A7%D9%84%D8%A7%D9%82%D8%AA%D8%B1%D8%A7%D9%86-coupling-%D9%88%D8%A7%D9%84%D8%AA%D9%85%D8%A7%D8%B3%D9%83-cohesion-%D9%83%D9%8A%D9%81-%D8%AA%D9%82%D8%B3%D9%85-%D8%A7%D9%84%D9%83%D9%88%D8%AF-%D8%A7%D9%84%D9%89-%D9%88%D8%AD%D8%AF%D8%A7%D8%AA/) رأينا أنواع الاقتران داخل الكود، وهنا يظهر نوع لا تراه في الكود أبداً، وهو الاقتران الزمني Temporal Coupling: أن تحتاج خدمتان أن تكونا شغالتين في نفس اللحظة لكي تنجح العملية. والاستدعاء المتزامن يفرض هذا الاقتران دائماً، مهما كانت الواجهة نظيفة والعقد واضحاً، فإذا كانت خدمة المخزون في منتصف النشر لمدة عشرين ثانية فإن كل طلب يصل في هذه الثواني يفشل أو ينتظر. أما الرسالة غير المتزامنة فتفك هذا الاقتران، لأن الوسيط يحفظ الرسالة حتى تعود خدمة المخزون، وبالتالي تصبح العملية «متاحة» ما دام الوسيط متاحاً، ولو تأخر إكمالها.

ولكن هذا الفك له ثمن لا يجب أن تتجاهله، فالعميل لم يعد يعرف النتيجة النهائية عند الرد، والطلب يصبح «قيد المعالجة PENDING» ثم يتغير لاحقاً، فتحتاج الواجهة طريقة لعرض الحالة، وتحتاج أن تتعامل مع حالة الفشل بعد أن قلت للعميل إن طلبك استلم، مثل أن تكتشف خدمة المخزون بعد دقيقة أن الكتاب نفد. وهذا ما يجعل القرار قراراً في تصميم المنتج أيضاً، وليس في التقنية فقط.

![مخططان لنفس تدفق الطلب: في الأعلى خدمة الطلبات تستدعي المدفوعات ثم المخزون وتنتظر كل رد قبل أن ترد على العميل، وتوفر العملية 99.7%. وفي الأسفل خدمة الطلبات تنشر الحدث orders.placed إلى الوسيط وترد على العميل فوراً بالحالة PENDING، ثم تستهلك المدفوعات الحدث وتنشر payments.charged، ثم يستهلكه المخزون](https://arabroot.io/content/images/2026/11/service-communication-01-sync-async.webp)

في الاتصال المتزامن يجب أن تكون الخدمات الثلاث حاضرة في نفس اللحظة، وفي غير المتزامن يكفي أن يكون الوسيط حاضراً

### الأمر Command والحدث Event

عندما تتواصل الخدمات بالرسائل فهناك نوعان من الرسائل يختلفان في المعنى وفي الاقتران. الأمر Command رسالة تطلب من خدمة محددة أن تفعل شيئاً، واسمه فعل أمر مثل `ReserveStock`، والمرسل يعرف من سوف يستقبله وينتظر أن ينفذ. والحدث Event رسالة تخبر أن شيئاً حدث فعلاً، واسمه فعل ماض مثل `orders.placed`، والمرسل لا يعرف من سوف يستقبله ولا يهمه ذلك، فقد يستقبله المخزون والمدفوعات وخدمة الإشعارات وخدمة التحليلات، وتضيف خدمة جديدة غداً دون أن تعدل خدمة الطلبات. لذلك الحدث أقل اقتراناً من الأمر، لأن المرسل لا يحمل أي معرفة عن المستقبلين، ولكن هذا نفسه يجعل تتبع ما يحدث بعد الحدث أصعب، لأنك لا تجد في كود خدمة الطلبات أي سطر يقول لك من يعمل بعدها.

### التنسيق المركزي Orchestration أم التنسيق بالأحداث Choreography؟

عندما تمتد العملية على عدة خدمات فهناك طريقتان لترتيب خطواتها. في التنسيق المركزي Orchestration توجد خدمة واحدة تعرف كل الخطوات وتطلب كل خطوة بدورها، مثل قائد الفرقة الموسيقية، وخدمة الطلبات في مثالنا عندما تستدعي المدفوعات ثم المخزون هي المنسق. وفي التنسيق بالأحداث Choreography لا يوجد قائد، وكل خدمة تستمع إلى حدث وتنشر حدثاً بعد أن تنهي عملها، فالمدفوعات تستمع إلى `orders.placed` وتنشر `payments.charged`، والمخزون يستمع إلى `payments.charged` وينشر `inventory.reserved`، مثل الراقصين الذين يعرف كل منهم حركته من حركة من قبله.

والتنسيق المركزي أسهل في الفهم والمراقبة لأن التدفق كله مكتوب في مكان واحد، ولكنه يجعل المنسق يعرف كل الخدمات، والتنسيق بالأحداث أقل اقتراناً ولكن التدفق موزع على عدة خدمات ولا تراه إلا بأدوات التتبع. ويمكن أن يكون التنسيق المركزي غير متزامن أيضاً، أي أن المنسق يرسل أوامر عبر الوسيط وينتظر أحداث الرد، وهذا ما تفعله أدوات مثل Temporal. وقد شرحنا كيف تلغي الخطوات السابقة عندما تفشل خطوة في المنتصف بنمط Saga في [مقال Saga وOutbox](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D8%B9%D8%A7%D9%85%D9%84%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D9%88%D8%B2%D8%B9%D8%A9-saga-%D9%88%D9%86%D9%85%D8%B7-outbox/)، لذلك لن نكرر ذلك هنا.

## الاستدعاء المتزامن عبر REST

REST هو الأسلوب الذي يبدأ به أغلب الفرق، والسبب أن كل لغة فيها مكتبة HTTP، وكل مطور يعرف JSON، وتستطيع أن تجرب أي طلب بأداة `curl` من الطرفية، وقد شرحنا شكل الطلب والرد ورموز الحالة Status Codes في [مقال ما هي واجهة API](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%8A-%D9%88%D8%A7%D8%AC%D9%87%D8%A9-api-%D8%A7%D9%84%D8%B7%D9%84%D8%A8-%D9%88%D8%A7%D9%84%D8%A7%D8%B3%D8%AA%D8%AC%D8%A7%D8%A8%D8%A9-%D9%88%D8%B1%D9%85%D9%88%D8%B2-%D8%A7%D9%84%D8%AD%D8%A7%D9%84%D8%A9-status-codes/). وما يهمنا هنا هو ما يحدث تحت هذا الاستدعاء عندما يتكرر آلاف المرات في الثانية بين خدمتين:

- **الاتصال Connection**: كل طلب HTTP/1.1 يحتاج اتصال TCP، وفتح اتصال جديد لكل طلب يضيف ذهاباً وعودة كاملين على الشبكة Round Trip قبل أن يرسل أي بايت، وأكثر من ذلك مع TLS. لذلك تستخدم مكتبات HTTP مجمعاً للاتصالات Connection Pool يعيد استخدام الاتصال المفتوح، ويجب أن تتأكد أن الكلاينت في كودك مشترك بين الطلبات وليس جديداً في كل طلب.
- **الترويسات Headers**: كل طلب يحمل ترويساته نصاً كاملاً في HTTP/1.1، مثل `content-type` و`user-agent` و`host`، وفي الطلبات الصغيرة بين الخدمات قد تكون الترويسات أكبر من الجسم نفسه كما سوف نرى في التجربة.
- **الترميز Serialization**: الجسم JSON نصي، فأسماء الحقول تتكرر في كل رسالة، والأرقام تكتب حرفاً حرفاً، والتحويل من وإلى JSON يأخذ وقتاً من المعالج في الطرفين.
- **رأس الطابور Head-of-line Blocking**: الاتصال الواحد في HTTP/1.1 يحمل طلباً واحداً في كل لحظة، فإذا كان عندك 50 طلباً متوازياً إلى نفس الخدمة فأنت تحتاج 50 اتصالاً.

وREST مع ذلك أسرع مما تحتاج في أغلب الأنظمة، والوقت الذي تقضيه الخدمة في الاستعلام من قاعدة البيانات أكبر غالباً من وقت الترميز والنقل. ولكنه يعني أن الفرق بين REST وgRPC يظهر في الأنظمة التي تتبادل فيها الخدمات آلاف الرسائل الصغيرة في الثانية، وليس في كل نظام.

## gRPC: العقد أولاً فوق HTTP/2

gRPC إطار من Google لاستدعاء الدوال عن بعد Remote Procedure Call، يبدأ من ملف عقد بلغة Protocol Buffers واختصاراً protobuf، فيه الخدمات والدوال والرسائل وأنواع حقولها، ثم يولد منه كود الكلاينت والسيرفر بأي لغة تدعمها. والفرق الأول عن REST أن الرسالة تكتب بالترميز الثنائي Binary لـ protobuf، فكل حقل يكتب برقمه وليس باسمه، والأرقام تكتب بترميز متغير الطول Varint، فالرقم 23750 يأخذ ثلاثة بايتات بدلاً من خمسة حروف، كما يشرح [توثيق الترميز في protobuf](https://protobuf.dev/programming-guides/encoding/?ref=arabroot.io). والفرق الثاني أن gRPC يعمل فوق HTTP/2، الذي يحمل عشرات الطلبات المتوازية على اتصال TCP واحد، ويضغط الترويسات المتكررة بخوارزمية HPACK، فلا تتكرر الترويسات نفسها في كل طلب.

والفرق الثالث، وهو الأهم في موضوعنا، أن gRPC يتعامل مع الزمن كجزء من العقد عبر المهلة النهائية Deadline، فالكلاينت يحدد متى يجب أن ينتهي الاستدعاء، وتنتقل هذه المهلة مع الطلب إلى السيرفر، والسيرفر يستطيع أن يمررها إلى الاستدعاءات التي يقوم بها بدوره، فإذا انتهت المهلة توقف العمل في كل السلسلة ورجع الخطأ `DEADLINE_EXCEEDED`. وينبه [دليل المهل في gRPC](https://grpc.io/docs/guides/deadlines/?ref=arabroot.io) إلى أن المهلة الافتراضية في أغلب لغات gRPC غير محدودة، أي أن الكلاينت ينتظر للأبد إذا لم تحدد مهلة، وسوف نرى ذلك في التجربة. ولـ gRPC أيضاً قائمة ثابتة من [رموز الحالة](https://grpc.io/docs/guides/status-codes/?ref=arabroot.io) مثل `UNAVAILABLE` و`DEADLINE_EXCEEDED` و`RESOURCE_EXHAUSTED`، وكل رمز يقول للكلاينت هل إعادة المحاولة مفيدة أم لا.

أما نقاط الضعف فهي أن الرسالة الثنائية لا تقرأها بعينك، فتحتاج أداة مثل `grpcurl` بدلاً من `curl`، وأن المتصفح لا يستطيع أن يستدعي gRPC مباشرة إلا عبر طبقة gRPC-Web، وأن بعض موزعات الطلبات القديمة توزع اتصالات HTTP/2 وليس طلباتها، فيذهب كل الضغط من كلاينت واحد إلى سيرفر واحد لأنه يرسل كل طلباته على اتصال واحد. لذلك يستخدم gRPC غالباً بين الخدمات في الداخل، ويبقى REST للواجهة التي يستدعيها المتصفح وتطبيق الجوال والشركاء.

## الرسائل غير المتزامنة عبر وسيط Broker

في الأسلوب الثالث لا تكلم خدمة الطلبات أي خدمة أخرى، وإنما تنشر Publish رسالة إلى وسيط الرسائل مثل RabbitMQ أو NATS أو Kafka، والوسيط يحفظها ويوصلها إلى كل مستهلك Consumer مشترك في هذا الموضوع، وقد شرحنا الطوابير وأنواعها في [مقال مفاهيم الطوابير](https://arabroot.io/articles/%D9%85%D9%81%D8%A7%D9%87%D9%8A%D9%85-%D8%A7%D9%84%D8%B7%D9%88%D8%A7%D8%A8%D9%8A%D8%B1-queue-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/)، والفرق بين الطابور وبث الأحداث في [مقال الطابور أم بث الأحداث](https://arabroot.io/articles/%D8%A7%D9%84%D8%B7%D8%A7%D8%A8%D9%88%D8%B1-%D8%A7%D9%85-%D8%A8%D8%AB-%D8%A7%D9%84%D8%A7%D8%AD%D8%AF%D8%A7%D8%AB-message-queue-%D9%88-event-streaming/). والتغيير الذي يحدث في نظامك عندما تنتقل إلى الرسائل أكبر من تغيير مكتبة، وفيما يلي ما يتغير:

- **الرد على العميل**: خدمة الطلبات ترد فوراً بعد أن يؤكد الوسيط أنه حفظ الرسالة، ورمز الحالة المناسب في REST هو 202 Accepted وليس 201 Created، لأن العملية لم تكتمل بعد.
- **ضمان التوصيل Delivery Guarantee**: أغلب الوسطاء يضمنون التوصيل مرة واحدة على الأقل At-least-once، فالمستهلك يؤكد استلام الرسالة Ack بعد أن ينهي عمله، فإذا سقط قبل التأكيد أعاد الوسيط الرسالة، وهذا يعني أن نفس الرسالة قد تصل مرتين، ويجب أن يكون المستهلك آمناً عند التكرار Idempotent كما شرحنا في [مقال Idempotency](https://arabroot.io/articles/idempotency-%D9%83%D9%8A%D9%81-%D8%AA%D8%AC%D8%B9%D9%84-%D8%A7%D9%84%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D8%A7%D9%85%D9%86%D8%A9-%D8%B9%D9%86%D8%AF-%D8%AA%D9%83%D8%B1%D8%A7%D8%B1%D9%87%D8%A7/).
- **الترتيب Ordering**: الوسيط يحفظ ترتيب الرسائل داخل الطابور أو القسم Partition الواحد، ولكن إذا كان عندك عدة مستهلكين يعملون بالتوازي فقد تنتهي رسالة متأخرة قبل رسالة سابقة.
- **الضغط العكسي Back-pressure**: إذا كانت خدمة المخزون أبطأ من خدمة الطلبات تتراكم الرسائل في الوسيط بدلاً من أن تتراكم الطلبات المعلقة في الذاكرة، وهذا أفضل كثيراً، ولكن التراكم Backlog نفسه يجب أن تراقبه وتنبه عليه.
- **الوسيط نفسه**: أصبح عندك نظام جديد يجب أن يعمل دائماً، وإذا توقف فلن تستطيع خدمة الطلبات أن تنشر شيئاً، وسوف نرى في التجربة ماذا يحدث عندها.

واخترنا في التجربة NATS مع طبقة الحفظ JetStream لأنه خفيف ويعمل من ملف تنفيذي واحد، وقد شرحناه في [دليل NATS](https://arabroot.io/articles/nats-%D8%B1%D8%B3%D8%A7%D8%A6%D9%84-%D8%B3%D8%B1%D9%8A%D8%B9%D8%A9-%D9%88%D8%AE%D9%81%D9%8A%D9%81%D8%A9-%D9%84%D9%84%D8%AE%D8%AF%D9%85%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B5%D8%BA%D8%B1%D8%A9/)، ونفس الأفكار تنطبق على RabbitMQ وKafka، وإذا كنت تختار بينها فالمقارنة في [مقال RabbitMQ أم Kafka أم NATS](https://arabroot.io/articles/rabbitmq-%D8%A7%D9%85-kafka-%D8%A7%D9%85-nats-%D9%83%D9%8A%D9%81-%D8%AA%D8%AE%D8%AA%D8%A7%D8%B1-%D9%88%D8%B3%D9%8A%D8%B7-%D8%A7%D9%84%D8%B1%D8%B3%D8%A7%D8%A6%D9%84/).

## العقود Contracts: OpenAPI وprotobuf وAsyncAPI

عندما كان الكود في برنامج واحد كان المترجم Compiler يخبرك إذا غيرت توقيع دالة ونسيت مكاناً يستدعيها، وعندما انتقلت الدالة إلى خدمة أخرى اختفى هذا الفحص، فقد يعدل فريق المدفوعات اسم حقل في الرد، وينشر، ولا يكتشف أحد المشكلة حتى تفشل الطلبات في الإنتاج. والعقد Contract هو ملف يصف الواجهة بين خدمتين بدقة، يكتب مرة ويقرؤه الطرفان، وتولد منه الأكواد والتوثيق والاختبارات، ولكل أسلوب من الأساليب الثلاثة صيغة عقد معروفة:

- **OpenAPI لـ REST**: ملف YAML أو JSON يصف المسارات والطرق والمعاملات وشكل الجسم بمخطط JSON Schema وردود الأخطاء، والإصدار المستخدم في أغلب الأدوات اليوم هو [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0?ref=arabroot.io). وقد رأينا في مقال تصميم API أن الملف الذي يولده الإطار من الكود لا يصف دائماً ما قصدته، لذلك اكتبه أو راجعه بيدك.
- **protobuf لـ gRPC**: ملف `.proto` هو العقد والمصدر الذي يولد منه الكود، فلا يمكن أن يختلف الكود عن العقد، وقواعد التوافق فيه مكتوبة في [دليل proto3](https://protobuf.dev/programming-guides/proto3/?ref=arabroot.io).
- **AsyncAPI للرسائل**: صيغة تشبه OpenAPI ولكنها للرسائل، فتصف القنوات Channels أي المواضيع، والرسائل التي تمر فيها، ومن يرسل ومن يستقبل، وشكل كل رسالة وترويساتها، وآخر إصدار رئيسي منها هو [AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0?ref=arabroot.io). وأهميتها أكبر مما تبدو، لأن الحدث في التنسيق بالأحداث لا يظهر في كود المرسل من يستقبله، فيكون ملف AsyncAPI هو المكان الوحيد الذي يرى فيه الفريق كل الرسائل وأصحابها.

### ما الذي يخل بالتوافق Compatibility في كل عقد؟

القاعدة العامة في الصيغ الثلاث واحدة: الإضافة آمنة والحذف والتغيير خطيران. فإضافة حقل اختياري جديد لا تضر المستهلك القديم الذي يتجاهله، أما حذف حقل يستخدمه أو تغيير نوعه أو معناه فيعطله. ولكن التفاصيل تختلف بين الصيغ، وهي التفاصيل التي تسبب الأخطاء في الواقع:

- في JSON يعرف الحقل باسمه، فتغيير الاسم من `amount` إلى `amount_halalas` يعني أن المستهلك القديم يقرأ قيمة فارغة دون أي خطأ، وقد يحسب الطلب بصفر ريال. لذلك تحقق من الجسم الذي يصلك بمخطط، وارفض ما لا يطابق بدلاً من أن تفترض قيماً افتراضية.
- في protobuf يعرف الحقل برقمه وليس باسمه، فتغيير الاسم آمن على الشبكة، أما تغيير الرقم أو إعادة استخدام رقم حقل محذوف لحقل جديد فهو أخطر خطأ ممكن، لأن الرسائل القديمة سوف تقرأ بالمعنى الجديد دون أي خطأ. لذلك احجز أرقام الحقول المحذوفة بالكلمة `reserved`، واستخدم أداة مثل `buf breaking` في خط CI لترفض أي تعديل يخل بالتوافق.
- في الرسائل المحفوظة في الوسيط يوجد بعد إضافي لا يوجد في الطلبات: الرسالة التي كتبت أمس بالإصدار القديم ما زالت في الطابور أو في سجل Kafka، وسوف يقرؤها المستهلك الجديد. لذلك يجب أن يقرأ المستهلك الإصدارين معاً لمدة تساوي على الأقل أطول مدة تبقى فيها الرسائل، وهذا ما تساعد عليه سجلات المخططات Schema Registry مثل Apicurio وConfluent Schema Registry التي ترفض نشر مخطط جديد غير متوافق.

وهناك أسلوب مكمل يسمى العقود التي يقودها المستهلك Consumer-driven Contracts، وأشهر أدواته Pact، وفكرته أن كل مستهلك يكتب الاختبارات التي تصف ما يستخدمه فعلاً من الواجهة، ويشغلها فريق المزود في خط CI قبل كل نشر، فيعرف قبل أن ينشر أن تعديله يعطل مستهلكاً محدداً. والعقد المكتوب لا يغني عن هذه الاختبارات ولا هي تغني عنه، فالعقد يقول ما تعد به الواجهة، والاختبار يقول ما يعتمد عليه المستهلك منها.

![ثلاثة أعمدة للعقود: OpenAPI يصف المسار POST /charge والجسم بمخطط JSON Schema، وprotobuf يصف الدالة Charge والرسالة بأرقام الحقول 1 و2 و3 و4، وAsyncAPI يصف القناة orders.placed والرسالة والمرسل والمستقبل. وتحت كل عمود ما يخل بالتوافق: تغيير اسم الحقل في JSON، وتغيير رقم الحقل في protobuf، والرسائل القديمة الباقية في الوسيط في AsyncAPI](https://arabroot.io/content/images/2026/11/service-communication-02-contracts.webp)

العقد الواحد يكتب مرة ويولد منه الكود والتوثيق، وما يخل بالتوافق يختلف في كل صيغة

## تجربة عملية Lab: نفس الطلب بثلاث طرق

الآن سوف نبني المتجر الذي بدأنا به المقال: خدمة الطلبات Orders التي يستدعيها العميل، وخدمة المدفوعات Payments، وخدمة المخزون Inventory، وكل خدمة منها تفهم الأساليب الثلاثة في نفس الوقت: REST على المنفذ 8000، وgRPC على المنفذ 50051، والأحداث عبر NATS JetStream. وبهذا الشكل يكون الفرق الوحيد بين القياسات هو أسلوب التواصل، أما الكود والبيانات والجهاز فواحد. والخدمات مكتوبة بلغة Python مع FastAPI وgrpcio وnats-py، وكل خدمة تقضي 2 ملي ثانية في «العمل» لكل طلب حتى لا يكون الزمن صفراً غير واقعي. والأرقام في هذا القسم من جهاز واحد تعمل عليه أشياء أخرى، فهي للمقارنة بين الأساليب على نفس الجهاز، وليست قياساً لأداء أي أداة.

### ملفات التجربة

نبدأ بالعقد في الملف `shop.proto`، وهو مصدر كود gRPC في الخدمات الثلاث:

```protobuf
syntax = "proto3";

package shop.v1;

// The two calls the orders service makes for every order.
service Payments {
  rpc Charge(ChargeRequest) returns (ChargeReply);
}

service Inventory {
  rpc Reserve(ReserveRequest) returns (ReserveReply);
}

message Item {
  string sku = 1;
  int32 qty = 2;
}

message ChargeRequest {
  string order_id = 1;
  string customer_id = 2;
  int64 amount_halalas = 3;
  string currency = 4;
}

message ChargeReply {
  string payment_id = 1;
  string status = 2;
}

message ReserveRequest {
  string order_id = 1;
  repeated Item items = 2;
  string warehouse = 3;
}

message ReserveReply {
  string reservation_id = 1;
  string status = 2;
}
```

ونسخ المكتبات في `requirements.txt`:

```text
fastapi==0.121.2
uvicorn==0.38.0
httpx==0.28.1
grpcio==1.76.0
grpcio-tools==1.76.0
protobuf==6.33.1
nats-py==2.12.0
```

والملف `Dockerfile` يولد كود gRPC من العقد أثناء بناء ال Image، فلا يمكن أن يختلف الكود عن العقد:

```dockerfile
FROM python:3.13.18-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY shop.proto .
# generate shop_pb2.py and shop_pb2_grpc.py from the contract
RUN python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. shop.proto
COPY *.py ./
```

الملف التالي `downstream.py` هو خدمة المدفوعات وخدمة المخزون معاً، ويحدد المتغير `ROLE` أيهما يعمل:

```python
# payments or inventory (ROLE), reachable three ways:
#   REST on :8000, gRPC on :50051, and as a JetStream consumer of the previous event
import asyncio, json, os, threading, time, uuid
from concurrent import futures
from contextlib import asynccontextmanager

import grpc, nats
from fastapi import FastAPI
import shop_pb2 as pb, shop_pb2_grpc as rpc

ROLE = os.environ["ROLE"]                       # payments | inventory
WORK_MS = float(os.environ.get("WORK_MS", "2"))  # simulated work per call
PARALLEL = os.environ.get("PARALLEL") == "1"     # handle several events at once
LISTEN, EMIT = {"payments": ("orders.placed", "payments.charged"),
                "inventory": ("payments.charged", "inventory.reserved")}[ROLE]
handled = {"rest": 0, "grpc": 0, "event": 0}

def work(kind):
    time.sleep(WORK_MS / 1000)
    handled[kind] += 1
    return ("pay_" if ROLE == "payments" else "res_") + uuid.uuid4().hex[:10]

# ---- gRPC ----
class Payments(rpc.PaymentsServicer):
    def Charge(self, req, ctx):
        return pb.ChargeReply(payment_id=work("grpc"), status="CAPTURED")

class Inventory(rpc.InventoryServicer):
    def Reserve(self, req, ctx):
        return pb.ReserveReply(reservation_id=work("grpc"), status="RESERVED")

def serve_grpc():
    s = grpc.server(futures.ThreadPoolExecutor(max_workers=40))
    if ROLE == "payments":
        rpc.add_PaymentsServicer_to_server(Payments(), s)
    else:
        rpc.add_InventoryServicer_to_server(Inventory(), s)
    s.add_insecure_port("[::]:50051")
    s.start()
    s.wait_for_termination()

# ---- events ----
async def consume():
    nc = await nats.connect(os.environ.get("NATS_URL", "nats://nats:4222"))
    js = nc.jetstream()
    running = set()
    async def handle(msg):
        evt = json.loads(msg.data)
        ref = await asyncio.to_thread(work, "event")
        evt["payment_id" if ROLE == "payments" else "reservation_id"] = ref
        evt[ROLE + "_at"] = time.time()
        await js.publish(EMIT, json.dumps(evt).encode(),
                         headers={"Nats-Msg-Id": f"{EMIT}:{evt['order_id']}"})
        await msg.ack()
    async def on_msg(msg):
        if PARALLEL:   # return at once so the next event is delivered while this one works
            t = asyncio.create_task(handle(msg))
            running.add(t)
            t.add_done_callback(running.discard)
        else:
            await handle(msg)
    await js.subscribe(LISTEN, durable=ROLE, cb=on_msg, manual_ack=True)
    while True:
        await asyncio.sleep(3600)

@asynccontextmanager
async def lifespan(app):
    threading.Thread(target=serve_grpc, daemon=True).start()
    task = asyncio.create_task(consume())
    yield
    task.cancel()

app = FastAPI(lifespan=lifespan)

# ---- REST ----
@app.post("/charge", status_code=201)
def charge(body: dict):
    return {"payment_id": work("rest"), "status": "CAPTURED"}

@app.post("/reserve", status_code=201)
def reserve(body: dict):
    return {"reservation_id": work("rest"), "status": "RESERVED"}

@app.get("/stats")
def stats():
    return handled
```

في الكود أعلاه لاحظ التالي:

- نفس الدالة `work()` تخدم الأساليب الثلاثة، والقاموس `handled` يعد كم طلباً وصل من كل أسلوب، ونقرؤه من المسار `/stats` لنعرف ماذا نفذت الخدمة فعلاً، وليس ماذا رأى الكلاينت.
- المدفوعات تستمع إلى `orders.placed` وتنشر `payments.charged`، والمخزون يستمع إلى `payments.charged` وينشر `inventory.reserved`، أي أن مسار الأحداث تنسيق بالأحداث Choreography لا يعرف فيه أحد الخطوة التالية.
- المستهلك يؤكد الرسالة `msg.ack()` بعد أن ينشر الحدث التالي وليس قبله، فإذا سقط في المنتصف أعاد الوسيط الرسالة، وهذا هو التوصيل مرة واحدة على الأقل At-least-once.
- كل نشر يحمل الترويسة `Nats-Msg-Id` المبنية من رقم الطلب، وJetStream يستخدمها ليتجاهل النشر المكرر لنفس الرسالة خلال نافذة زمنية، وسوف نرى أثرها وحدودها.
- المتغير `PARALLEL` يجعل المستهلك يعالج عدة أحداث معاً بدلاً من حدث بعد حدث، وهو مطفأ في البداية لسبب سوف يظهر في القياس.

والملف `orders.py` هو خدمة الطلبات، وفيه ثلاثة مسارات لنفس العملية:

```python
# The orders service: one order flow, three ways to talk to payments and inventory
import json, os, threading, time, uuid
from contextlib import asynccontextmanager

import grpc, httpx, nats
from fastapi import FastAPI
from fastapi.responses import JSONResponse
import shop_pb2 as pb, shop_pb2_grpc as rpc

def env_timeout(name):
    v = os.environ.get(name, "none")
    return None if v == "none" else float(v)

HTTP_TIMEOUT = env_timeout("HTTP_TIMEOUT")      # seconds, "none" = wait forever
GRPC_DEADLINE = env_timeout("GRPC_DEADLINE")
USE_BREAKER = os.environ.get("BREAKER") == "1"
RESERVE_FIRST = os.environ.get("RESERVE_FIRST") == "1"   # reserve stock before taking money

http = httpx.Client(timeout=HTTP_TIMEOUT, limits=httpx.Limits(max_connections=100))
pay_rpc = rpc.PaymentsStub(grpc.insecure_channel("payments:50051"))
inv_rpc = rpc.InventoryStub(grpc.insecure_channel("inventory:50051"))

class Breaker:
    """Opens after 5 failures in a row, stays open 10 s, then lets one call try."""
    def __init__(self, name, threshold=5, cooldown=10.0):
        self.name, self.threshold, self.cooldown = name, threshold, cooldown
        self.fails, self.opened_at, self.lock = 0, 0.0, threading.Lock()
    def allow(self):
        with self.lock:
            if self.fails < self.threshold:
                return True
            if time.monotonic() - self.opened_at >= self.cooldown:
                self.opened_at = time.monotonic()   # half-open: one trial call
                return True
            return False
    def result(self, ok):
        with self.lock:
            if ok:
                self.fails = 0
            else:
                self.fails += 1
                if self.fails == self.threshold:
                    self.opened_at = time.monotonic()
                    print(f"breaker {self.name}: OPEN", flush=True)

breakers = {"payments": Breaker("payments"), "inventory": Breaker("inventory")}

class Unavailable(Exception):
    pass

def call(name, fn):
    b = breakers[name]
    if USE_BREAKER and not b.allow():
        raise Unavailable(f"{name}: circuit open")
    try:
        out = fn()
        b.result(True)
        return out
    except Exception:
        b.result(False)
        raise

def new_order(body):
    oid = "ord_" + uuid.uuid4().hex[:10]
    amount = sum(i["qty"] * i["price_halalas"] for i in body["items"])
    return oid, amount

nc = js = None

@asynccontextmanager
async def lifespan(app):
    global nc, js
    nc = await nats.connect(os.environ.get("NATS_URL", "nats://nats:4222"))
    js = nc.jetstream()
    yield
    await nc.close()

app = FastAPI(lifespan=lifespan)

def run(pay, reserve):
    if RESERVE_FIRST:
        r = reserve()
        return pay(), r
    p = pay()
    return p, reserve()

def fail(e, t0):
    ms = round((time.perf_counter() - t0) * 1000)
    code = 503 if isinstance(e, Unavailable) else 504
    return JSONResponse({"error": type(e).__name__, "detail": str(e)[:120], "ms": ms}, status_code=code)

@app.post("/orders/rest", status_code=201)
def order_rest(body: dict):
    t0 = time.perf_counter()
    oid, amount = new_order(body)
    def pay():
        return http.post("http://payments:8000/charge", json={
            "order_id": oid, "customer_id": body["customer_id"],
            "amount_halalas": amount, "currency": "SAR"}).raise_for_status().json()
    def reserve():
        return http.post("http://inventory:8000/reserve", json={
            "order_id": oid, "warehouse": "main",
            "items": [{"sku": i["sku"], "qty": i["qty"]} for i in body["items"]]}).raise_for_status().json()
    try:
        p, r = run(lambda: call("payments", pay), lambda: call("inventory", reserve))
    except Exception as e:
        return fail(e, t0)
    return {"order_id": oid, "payment_id": p["payment_id"], "reservation_id": r["reservation_id"],
            "downstream_ms": round((time.perf_counter() - t0) * 1000, 2)}

@app.post("/orders/grpc", status_code=201)
def order_grpc(body: dict):
    t0 = time.perf_counter()
    oid, amount = new_order(body)
    def pay():
        return pay_rpc.Charge(pb.ChargeRequest(order_id=oid, customer_id=body["customer_id"],
                              amount_halalas=amount, currency="SAR"), timeout=GRPC_DEADLINE)
    def reserve():
        return inv_rpc.Reserve(pb.ReserveRequest(order_id=oid, warehouse="main",
                               items=[pb.Item(sku=i["sku"], qty=i["qty"]) for i in body["items"]]),
                               timeout=GRPC_DEADLINE)
    try:
        p, r = run(lambda: call("payments", pay), lambda: call("inventory", reserve))
    except Exception as e:
        return fail(e, t0)
    return {"order_id": oid, "payment_id": p.payment_id, "reservation_id": r.reservation_id,
            "downstream_ms": round((time.perf_counter() - t0) * 1000, 2)}

@app.post("/orders/async", status_code=202)
async def order_async(body: dict):
    oid, amount = new_order(body)
    evt = {"order_id": oid, "customer_id": body["customer_id"], "amount_halalas": amount,
           "currency": "SAR", "items": body["items"], "placed_at": time.time()}
    ack = await js.publish("orders.placed", json.dumps(evt).encode(),
                           headers={"Nats-Msg-Id": f"orders.placed:{oid}"})
    return {"order_id": oid, "status": "PENDING", "stream_seq": ack.seq}

@app.get("/health")
def health():
    return {"ok": True}
```

في الكود أعلاه لاحظ التالي:

- المهلة في REST وgRPC تأتي من متغيرات البيئة، والقيمة الافتراضية `none` تعني الانتظار دون حد، وهذا ليس افتراضاً غريباً: مكتبة requests في Python لا تضع مهلة إلا إذا طلبتها كما يقول [توثيقها](https://requests.readthedocs.io/en/latest/user/advanced/?ref=arabroot.io)، وgRPC لا يضع مهلة افتراضية كما رأينا. أما httpx فتضع 5 ثوان افتراضياً كما في [صفحة المهل](https://www.python-httpx.org/advanced/timeouts/?ref=arabroot.io)، لذلك ألغيناها صراحة لنرى أسوأ حالة.
- مسارا REST وgRPC معرفان بالكلمة `def`، فيعملان في مجمع خيوط Thread Pool يديره FastAPI، وحجمه الافتراضي 40 خيطاً، وفحص الصحة `/health` يعمل في نفس المجمع. وهذا يشبه أغلب سيرفرات التطبيقات التي تخدم الطلبات من عدد ثابت من العمال Workers.
- الكلاس `Breaker` قاطع دائرة Circuit Breaker بسيط: بعد خمسة فشل متتالية يرفض الاستدعاءات فوراً لمدة 10 ثوان، ثم يسمح بمحاولة واحدة، وقد شرحنا حالاته الثلاث وأنواعه في [مقال أنماط الحماية](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D9%85%D9%86%D8%B9-%D8%AE%D8%AF%D9%85%D8%A9-%D8%A8%D8%B7%D9%8A%D8%A6%D8%A9-%D9%85%D9%86-%D8%A7%D8%B3%D9%82%D8%A7%D8%B7-%D9%86%D8%B8%D8%A7%D9%85%D9%83-%D9%83%D9%84%D9%87/#circuit-breaker).
- الدالة `run()` تحدد ترتيب الاستدعاءين: الدفع ثم الحجز في البداية، والحجز ثم الدفع مع `RESERVE_FIRST=1`، وهذا الترتيب سوف يكون أحد أهم نتائج التجربة.
- مسار الأحداث `async def` ينتظر فقط تأكيد JetStream أنه حفظ الرسالة، ويرد بالرمز 202 والحالة `PENDING` ورقم الرسالة في ال Stream.
- كل رد ناجح في REST وgRPC يحمل `downstream_ms`، وهو الوقت الذي قضته خدمة الطلبات تنتظر الخدمتين، فنفصل به زمن التواصل عن زمن خدمة الطلبات نفسها.

وأداة القياس `bench.py` ترسل عدداً من الطلبات من عدة كلاينتات متوازية، والعميل يتخلى عن الطلب بعد 10 ثوان مثل المستخدم الحقيقي، ومع `--probe` تسأل فحص الصحة كل نصف ثانية كما يفعل موزع الطلبات، وفي أسلوب الأحداث تستمع إلى `inventory.reserved` وتحسب الزمن من لحظة قبول الطلب إلى لحظة حجز المخزون:

```python
# Sends N orders with C parallel clients to one mode of the orders service and prints latency percentiles.
#   python bench.py MODE N C [--probe]      MODE = rest | grpc | async
# For async it also waits for inventory.reserved of every order and reports the end-to-end time.
import asyncio, json, statistics, sys, threading, time
from concurrent.futures import ThreadPoolExecutor
import httpx, nats

MODE, N, C = sys.argv[1], int(sys.argv[2]), int(sys.argv[3])
PROBE = "--probe" in sys.argv
GIVE_UP = 10.0                     # a user waits at most 10 s
ORDER = {"customer_id": "cus_8841", "items": [
    {"sku": "BOOK-AR-0042", "qty": 1, "price_halalas": 8900},
    {"sku": "PEN-BLUE-0007", "qty": 3, "price_halalas": 450},
    {"sku": "BAG-CANVAS-01", "qty": 1, "price_halalas": 6500}]}

def pct(xs, p):
    xs = sorted(xs)
    return xs[min(len(xs) - 1, int(len(xs) * p))] if xs else float("nan")

def line(label, xs):
    return (f"{label:<9} n={len(xs):<5} p50={pct(xs, .50):7.1f}ms p90={pct(xs, .90):7.1f}ms "
            f"p99={pct(xs, .99):7.1f}ms max={max(xs) if xs else 0:7.1f}ms")

e2e = []   # placed_at (orders) to inventory_at (inventory), both stamped by the services
async def watch(stop):
    nc = await nats.connect("nats://nats:4222")
    async def cb(msg):
        evt = json.loads(msg.data)
        e2e.append((evt["inventory_at"] - evt["placed_at"]) * 1000)
    await nc.subscribe("inventory.reserved", cb=cb)
    while not stop.is_set():
        await asyncio.sleep(0.05)
    await nc.close()

probe_ok, probe_fail = [], 0
def probe(stop):
    global probe_fail
    with httpx.Client(timeout=2.0) as c:
        while not stop.is_set():
            t0 = time.perf_counter()
            try:
                c.get("http://orders:8000/health").raise_for_status()
                probe_ok.append((time.perf_counter() - t0) * 1000)
            except Exception:
                probe_fail += 1
            time.sleep(0.5)

lock = threading.Lock()
hop = []   # time orders spent waiting for payments + inventory
client = httpx.Client(timeout=GIVE_UP, limits=httpx.Limits(max_connections=C))
lat, failed, codes = [], [], {}
def one(_):
    t0 = time.perf_counter()
    try:
        r = client.post(f"http://orders:8000/orders/{MODE}", json=ORDER)
        code = r.status_code
        if code == 201:
            hop.append(r.json()["downstream_ms"])
    except httpx.TimeoutException:
        code = "gave-up"
    except httpx.HTTPError as e:
        code = type(e).__name__
    ms = (time.perf_counter() - t0) * 1000
    with lock:
        codes[code] = codes.get(code, 0) + 1
        (lat if code in (201, 202) else failed).append(ms)

stop = threading.Event()
loop = asyncio.new_event_loop()
if MODE == "async":
    threading.Thread(target=lambda: loop.run_until_complete(watch(stop)), daemon=True).start()
    time.sleep(0.5)
if PROBE:
    threading.Thread(target=probe, args=(stop,), daemon=True).start()

t_start = time.perf_counter()
with ThreadPoolExecutor(C) as ex:
    list(ex.map(one, range(N)))
wall = time.perf_counter() - t_start
print(f"mode={MODE} orders={N} clients={C} wall={wall:.1f}s rate={N / wall:.0f}/s codes={codes}")
print(line("accepted" if MODE == "async" else "order", lat))
if failed:
    print(line("failed", failed))
if MODE == "async":
    deadline = time.time() + 60
    while len(e2e) < len(lat) and time.time() < deadline:
        time.sleep(0.2)
    print(line("end2end", e2e), f"completed={len(e2e)}/{len(lat)}")
elif hop:
    print(line("two calls", hop))
if PROBE:
    print(f"health    ok={len(probe_ok)} failed={probe_fail}", line("", probe_ok)[10:] if probe_ok else "")
stop.set()
```

والملف `bench.sh` يشغلها ويقرأ عدادات بطاقة الشبكة في Container المدفوعات قبل القياس وبعده، فنعرف كم بايتاً عبر الشبكة لكل طلب فعلاً، بكل الترويسات وإطارات TCP:

```bash
#!/usr/bin/env bash
# bench.sh MODE N C [--probe]: runs bench.py and prints the bytes that crossed the network card of payments
set -e
rxtx() { docker exec sw5-sc-payments cat /proc/net/dev | awk '/eth0/ {print $2, $10}'; }
read rx0 tx0 < <(rxtx)
docker compose run --rm -T bench "$@"
read rx1 tx1 < <(rxtx)
echo "payments eth0: in=$(( (rx1 - rx0) / $2 )) B/order out=$(( (tx1 - tx0) / $2 )) B/order"
```

وأخيراً `compose.yaml`:

```yaml
name: sw5-sc
x-app: &app
  image: sw5-sc-app:lab
  build: .
  depends_on: [nats]
services:
  nats:
    image: nats:2.15.0-alpine
    container_name: sw5-sc-nats
    command: ["-js", "-sd", "/data", "-m", "8222"]
  payments:
    <<: *app
    container_name: sw5-sc-payments
    environment: { ROLE: payments, PARALLEL: "${PARALLEL:-0}" }
    command: ["uvicorn", "downstream:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "warning"]
  inventory:
    <<: *app
    container_name: sw5-sc-inventory
    environment: { ROLE: inventory, PARALLEL: "${PARALLEL:-0}" }
    command: ["uvicorn", "downstream:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "warning"]
  orders:
    <<: *app
    container_name: sw5-sc-orders
    environment:
      HTTP_TIMEOUT: ${HTTP_TIMEOUT:-none}
      GRPC_DEADLINE: ${GRPC_DEADLINE:-none}
      BREAKER: ${BREAKER:-0}
      RESERVE_FIRST: ${RESERVE_FIRST:-0}
    command: ["uvicorn", "orders:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "warning"]
    ports: ["127.0.0.1:18080:8000"]
  bench:
    <<: *app
    profiles: [tools]
    entrypoint: ["python", "bench.py"]
```

### التشغيل وأول طلب بكل أسلوب

نبني ال Image ونشغل NATS أولاً، ثم ننشئ ال Stream الذي يحفظ الأحداث الثلاثة بأداة `nats` من Container الأدوات nats-box، ثم نشغل الخدمات:

```bash
docker compose build
docker compose up -d nats
docker run --rm --network sw5-sc_default natsio/nats-box:0.20.0 nats -s nats://nats:4222 \
  stream add SHOP --subjects 'orders.>,payments.>,inventory.>' --storage file \
  --retention limits --max-age 24h --dupe-window 2m --defaults
docker compose up -d
```

والجزء المهم من مخرج إنشاء ال Stream:

```text
Stream SHOP was created

                     Subjects: orders.>, payments.>, inventory.>
                     Replicas: 1
                      Storage: File
                    Retention: Limits
              Acknowledgments: true
             Duplicate Window: 2m0s
                  Maximum Age: 1d0h0m0s
```

لاحظ السطر `Duplicate Window: 2m0s`، فهو المدة التي يتذكر فيها JetStream قيم `Nats-Msg-Id` ليرفض تكرارها، وبعدها ينساها. ثم نرسل طلباً واحداً بكل أسلوب، والملف `order.json` فيه عميل وثلاثة منتجات:

```json
{"customer_id": "cus_8841", "items": [
  {"sku": "BOOK-AR-0042", "qty": 1, "price_halalas": 8900},
  {"sku": "PEN-BLUE-0007", "qty": 3, "price_halalas": 450},
  {"sku": "BAG-CANVAS-01", "qty": 1, "price_halalas": 6500}]}
```

```text
$ curl -s -w ' -> %{http_code} %{time_total}s\n' -H 'content-type: application/json' --data @order.json localhost:18080/orders/rest
{"order_id":"ord_fb3e6ed2f1","payment_id":"pay_9f1938f88c","reservation_id":"res_968ce765c6","downstream_ms":75.15} -> 201 0.167035s
$ curl -s -w ' -> %{http_code} %{time_total}s\n' -H 'content-type: application/json' --data @order.json localhost:18080/orders/grpc
{"order_id":"ord_a06593cb6a","payment_id":"pay_432617617d","reservation_id":"res_7b503c1cf6","downstream_ms":99.34} -> 201 0.191589s
$ curl -s -w ' -> %{http_code} %{time_total}s\n' -H 'content-type: application/json' --data @order.json localhost:18080/orders/async
{"order_id":"ord_67a8f0d2dc","status":"PENDING","stream_seq":33430} -> 202 0.152315s
```

الطلبان الأولان رجعا 201 ومعهما رقم الدفع ورقم الحجز، أي أن العملية اكتملت قبل الرد، أما الثالث فرجع 202 والحالة `PENDING` ورقم الرسالة في ال Stream، أي أن خدمة الطلبات لا تعرف بعد هل نجح الدفع والحجز أم لا. وهذا الفرق في الرد هو أول ما يجب أن تتعامل معه الواجهة الأمامية إذا انتقلت إلى الأحداث.

### زمن الاستجابة Latency وحجم البيانات

نبدأ بكلاينت واحد يرسل 2000 طلب، واحداً بعد الآخر، لكل أسلوب:

```bash
for m in rest grpc async; do bash bench.sh $m 2000 1; done
```

```text
mode=rest orders=2000 clients=1 wall=77.0s rate=26/s codes={201: 2000}
order     n=2000  p50=   25.3ms p90=   72.1ms p99=  225.0ms max= 1082.0ms
two calls n=2000  p50=   18.5ms p90=   55.2ms p99=  197.0ms max=  412.1ms
payments eth0: in=494 B/order out=380 B/order

mode=grpc orders=2000 clients=1 wall=48.1s rate=42/s codes={201: 2000}
order     n=2000  p50=   18.8ms p90=   43.3ms p99=   83.4ms max=  127.7ms
two calls n=2000  p50=   12.3ms p90=   29.6ms p99=   60.5ms max=  124.1ms
payments eth0: in=165 B/order out=159 B/order

mode=async orders=2000 clients=1 wall=15.0s rate=133/s codes={202: 2000}
accepted  n=2000  p50=    5.3ms p90=   14.4ms p99=   28.0ms max=   51.9ms
end2end   n=2000  p50=   82.8ms p90=  161.7ms p99=  244.7ms max=  280.4ms completed=2000/2000
payments eth0: in=717 B/order out=750 B/order
```

في المخرج أعلاه لاحظ التالي:

- السطر `two calls` هو زمن الاستدعاءين فقط من داخل خدمة الطلبات: الوسيط 18.5 ملي ثانية في REST و12.3 في gRPC، والفرق يظهر أوضح في الذيل p99، 197 مقابل 60.5\. والسبب الرئيسي أن gRPC يرسل كل الطلبات على اتصال HTTP/2 واحد مفتوح، والترويسات مضغوطة، والرسالة أصغر.
- عدادات الشبكة هي أوضح فرق: الطلب الواحد أدخل إلى المدفوعات 494 بايتاً وأخرج 380 في REST، و165 و159 في gRPC، أي حوالي ثلث REST في المجموع، 324 بايتاً مقابل 874\. وهذه الأرقام تشمل الترويسات وإطارات TCP، وهي ما تدفعه في كل استدعاء بين الخدمات.
- في الأحداث قبلت خدمة الطلبات الطلب في 5.3 ملي ثانية في الوسيط، لأنها لا تنتظر إلا تأكيد الحفظ، ولكن الحجز نفسه حدث بعد 82.8 ملي ثانية في الوسيط، لأن الحدث يمر بالوسيط مرتين وكل خدمة تؤكد وتنشر. أي أن الأحداث أسرع في الرد على العميل، وأبطأ في إكمال العملية.
- حركة الشبكة في المدفوعات مع الأحداث أكبر من REST نفسه، 717 و750 بايتاً، لأن الرسالة تحمل الطلب كاملاً ومعه رسائل التأكيد Ack وتأكيد النشر، فالأحداث لا توفر البايتات، وإنما توفر الانتظار.

ولماذا الرسالة في gRPC أصغر؟ الأداة `sizes.py` ترمز نفس الطلبين بالطريقتين وتطبع البايتات:

```python
# The same two requests as JSON (REST) and as protobuf (gRPC): body sizes in bytes
import json
import shop_pb2 as pb

charge = {"order_id": "ord_2c4f08795e", "customer_id": "cus_8841", "amount_halalas": 23750, "currency": "SAR"}
items = [{"sku": "BOOK-AR-0042", "qty": 1}, {"sku": "PEN-BLUE-0007", "qty": 3}, {"sku": "BAG-CANVAS-01", "qty": 1}]
reserve = {"order_id": "ord_2c4f08795e", "warehouse": "main", "items": items}

for name, body, msg in [
    ("ChargeRequest", charge, pb.ChargeRequest(**charge)),
    ("ReserveRequest", reserve, pb.ReserveRequest(order_id=reserve["order_id"], warehouse="main",
                                                  items=[pb.Item(**i) for i in items]))]:
    j = json.dumps(body).encode()
    p = msg.SerializeToString()
    print(f"{name:<15} json={len(j):>4} B  protobuf={len(p):>4} B  ratio={len(j) / len(p):.1f}x")
print("protobuf bytes of ChargeRequest:", pb.ChargeRequest(**charge).SerializeToString().hex(" "))
```

```text
ChargeRequest   json= 101 B  protobuf=  35 B  ratio=2.9x
ReserveRequest  json= 169 B  protobuf=  78 B  ratio=2.2x
protobuf bytes of ChargeRequest: 0a 0e 6f 72 64 5f 32 63 34 66 30 38 37 39 35 65 12 08 63 75 73 5f 38 38 34 31 18 c6 b9 01 22 03 53 41 52
```

اقرأ البايتات من اليسار: `0a` تعني الحقل رقم 1 من نوع نص، ثم `0e` طوله 14 حرفاً، ثم حروف `ord_2c4f08795e`. وبعده `12 08` الحقل 2 بطول 8 أحرف، ثم `18 c6 b9 01` الحقل 3 وقيمته 23750 بترميز Varint في ثلاثة بايتات فقط. ولا يوجد في الرسالة أي اسم حقل، لذلك هي أصغر بمرتين إلى ثلاث، ولذلك أيضاً لا تستطيع أن تقرأها دون ملف العقد.

### مشكلة واجهتنا: عشرة كلاينتات معاً

الآن نفس القياس بعشرة كلاينتات متوازية، وهو أقرب إلى ما يحدث في الإنتاج:

```bash
for m in rest grpc async; do bash bench.sh $m 2000 10; done
```

```text
mode=rest orders=2000 clients=10 wall=27.8s rate=72/s codes={201: 2000}
order     n=2000  p50=  128.9ms p90=  212.5ms p99=  320.4ms max=  430.8ms
two calls n=2000  p50=   95.3ms p90=  165.4ms p99=  247.1ms max=  353.2ms
payments eth0: in=501 B/order out=383 B/order

mode=grpc orders=2000 clients=10 wall=15.7s rate=128/s codes={201: 2000}
order     n=2000  p50=   61.5ms p90=  129.5ms p99=  377.4ms max=  698.0ms
two calls n=2000  p50=   24.4ms p90=   72.2ms p99=  255.3ms max=  538.1ms
payments eth0: in=177 B/order out=168 B/order

mode=async orders=2000 clients=10 wall=13.2s rate=151/s codes={202: 2000}
accepted  n=2000  p50=   51.3ms p90=  133.8ms p99=  252.0ms max=  415.8ms
end2end   n=2000  p50= 4287.7ms p90= 7407.0ms p99= 9211.7ms max= 9363.1ms completed=2000/2000
payments eth0: in=710 B/order out=747 B/order
```

الأرقام في REST وgRPC منطقية، فالطلبات أصبحت تنتظر بعضها وارتفع الزمن، وما زال gRPC أسرع في الوسيط بحوالي أربع مرات في الاستدعاءين، 24.4 مقابل 95.3 ملي ثانية. ولكن انظر إلى سطر `end2end` في الأحداث: الوسيط 4.3 ثانية والأقصى 9.4 ثانية، مع أن خدمة الطلبات قبلت كل طلب في أقل من ربع ثانية. والسبب في الكود وليس في NATS: مكتبة nats-py تستدعي دالة المستهلك `on_msg` لرسالة واحدة في كل مرة، والدالة تنتظر العمل ثم النشر ثم التأكيد قبل أن تعود، فكل خدمة تعالج حدثاً واحداً في كل لحظة، والطلبات كانت تصل بمعدل 151 في الثانية، وهو أسرع مما يستطيع مستهلك يعمل حدثاً بعد حدث. وبالتالي تراكمت الأحداث في الوسيط، وكل حدث جديد ينتظر كل الذي قبله.

وهذا هو الوجه الآخر لفك الاقتران الزمني: لم يشعر العميل بأي بطء، ولم يفشل أي طلب، ولا يوجد خطأ في أي سجل، والنظام كان يتأخر أكثر فأكثر بصمت. لذلك المقياس الأهم في أي نظام أحداث هو عمر أقدم رسالة لم تعالج Consumer Lag، وليس عدد الأخطاء. والحل أن يعالج المستهلك عدة أحداث في نفس الوقت، وهذا ما يفعله `PARALLEL=1` بإنشاء مهمة asyncio لكل حدث حتى يعود فوراً ويستقبل التالي، والحد الأعلى للأحداث المفتوحة يحدده إعداد المستهلك `Max Ack Pending` وقيمته الافتراضية 1000:

```bash
PARALLEL=1 docker compose up -d payments inventory
bash bench.sh async 2000 10
```

```text
mode=async orders=2000 clients=10 wall=9.1s rate=220/s codes={202: 2000}
accepted  n=2000  p50=   39.9ms p90=   79.0ms p99=  130.3ms max=  184.9ms
end2end   n=2000  p50=   16.2ms p90=   36.6ms p99=   73.1ms max=  116.9ms completed=2000/2000
payments eth0: in=668 B/order out=703 B/order
```

الوسيط من القبول إلى الحجز نزل من 4,288 ملي ثانية إلى 16.2، والأقصى من 9.4 ثانية إلى 117 ملي ثانية، بتغيير سطر واحد في المستهلك. ولكن تذكر أن المعالجة المتوازية لها ثمن، فالأحداث لم تعد تنتهي بالترتيب الذي وصلت به، وهذا لا يهم في طلبات مستقلة، ويهم كثيراً إذا كان الحدثان لنفس الطلب، مثل الإنشاء ثم الإلغاء. والحل المعروف أن تقسم الأحداث بمفتاح الطلب حتى تذهب أحداث نفس الطلب إلى نفس المستهلك بالترتيب، كما تفعل أقسام Kafka.

### نوقف المخزون: السقوط المتتالي Cascading Failure

الآن نعيد الخدمات إلى الإعداد الأول، أي بلا مهلة وبلا قاطع، ونجمد خدمة المخزون بالأمر `docker pause`. والتجميد هنا أسوأ من الإيقاف، لأن الخدمة المتوقفة يرفض نظام التشغيل الاتصال بها فوراً، أما المجمدة فتقبل الاتصال ولا ترد أبداً، وهذا ما يحدث في الواقع عندما يعلق التطبيق على قفل في قاعدة البيانات أو تمتلئ ذاكرته. ثم نرسل 100 طلب من 20 كلاينت مع فحص الصحة:

```bash
docker compose up -d --force-recreate payments inventory orders
docker pause sw5-sc-inventory
docker compose run --rm -T bench rest 100 20 --probe
curl -s -m 3 -o /dev/null -w "health %{http_code} %{time_total}s\n" localhost:18080/health
docker unpause sw5-sc-inventory
```

والمخرج سوف يكون كما يلي، ومعه عدادات الخدمتين قبل فك التجميد وبعده:

```text
mode=rest orders=100 clients=20 wall=50.2s rate=2/s codes={'gave-up': 100}
order     n=0     p50=    nanms p90=    nanms p99=    nanms max=    0.0ms
failed    n=100   p50=10016.4ms p90=10047.0ms p99=10059.6ms max=10059.6ms
health    ok=20 failed=16 n=20    p50=    5.1ms p90=   18.4ms p99=  236.1ms max=  236.1ms
--- after the load stopped:
health 000 3.009774s
health 000 3.016334s
health 000 3.039783s
payments: {"rest":40,"grpc":0,"event":0}
--- after docker unpause:
health 200 0.004978s
payments: {"rest":100,"grpc":0,"event":0}
inventory: {"rest":100,"grpc":0,"event":0}
```

في المخرج أعلاه لاحظ التالي:

- لم ينجح أي طلب من المئة، وكل عميل انتظر عشر ثوان كاملة ثم تخلى عن الطلب.
- فحص الصحة نجح في البداية ثم فشل 16 مرة أثناء الضغط، ثم فشل في كل مرة بعد أن توقف الضغط تماماً. والسبب أن الطلبات الأربعين الأولى أخذت كل خيوط المجمع الأربعين وبقيت تنتظر المخزون للأبد، وفحص الصحة يحتاج خيطاً من نفس المجمع فلا يجده. وموزع الطلبات Load Balancer في هذه الحالة سوف يخرج خدمة الطلبات ويعتبرها معطلة، مع أن العطل في خدمة أخرى، وهذا هو السقوط المتتالي بالضبط.
- المدفوعات خصمت 40 مرة قبل فك التجميد، لأن الكود يدفع أولاً ثم يحجز، أي أن أربعين عميلاً خصمت أموالهم وقيل لهم إن الطلب فشل.
- بعد فك التجميد أصبح العدادان 100 و100: الطلبات التي كانت تنتظر في المجمع أكملت طريقها كلها، فخصمت المدفوعات وحجز المخزون لمئة طلب تخلى عنها أصحابها قبل دقيقة. فإذا أعاد العملاء المحاولة، وهذا ما يفعله أغلبهم، فسوف يدفعون مرتين.

ونفس الشيء يحدث في gRPC دون مهلة، فعشرة طلبات أثناء التجميد انتهت كلها بتخلي العميل:

```text
mode=grpc orders=10 clients=10 wall=10.1s rate=1/s codes={'gave-up': 10}
```

💡

في 7 ديسمبر 2021 تعطلت خدمات كثيرة في منطقة us-east-1 في AWS لساعات، وشرحت AWS في [ملخص الحادثة](https://aws.amazon.com/message/12721/?ref=arabroot.io) أن عملية آلية لزيادة سعة إحدى الخدمات سببت سلوكاً غير متوقع من عدد كبير من الكلاينتات في الشبكة الداخلية، فازدحمت الأجهزة التي تربط الشبكتين، وأعادت الكلاينتات المحاولة فزاد الازدحام، وتأثرت بذلك خدمات لا علاقة لها بالسبب الأصلي، ومنها أدوات المراقبة التي يحتاجها المهندسون لفهم ما يحدث. والدرس أن الاستدعاءات المتزامنة وإعادة المحاولة دون حد تنقل العطل من خدمة إلى كل من يعتمد عليها، كما يشرح فصل [معالجة الأعطال المتتالية](https://sre.google/sre-book/addressing-cascading-failures/?ref=arabroot.io) في كتاب SRE من Google.

### الإصلاح: مهلة Timeout وقاطع دائرة Circuit Breaker والحجز قبل الدفع

نشغل خدمة الطلبات بمهلة نصف ثانية في REST وgRPC، وقاطع الدائرة، والحجز قبل الدفع، ثم نكرر التجربة بثلاثمئة طلب لكل أسلوب:

```bash
HTTP_TIMEOUT=0.5 GRPC_DEADLINE=0.5 BREAKER=1 RESERVE_FIRST=1 docker compose up -d
docker pause sw5-sc-inventory
for m in rest grpc; do docker compose run --rm -T bench $m 300 20 --probe; done
docker compose logs orders | grep -i breaker
docker unpause sw5-sc-inventory
```

```text
mode=rest orders=300 clients=20 wall=1.8s rate=165/s codes={504: 21, 503: 279}
order     n=0     p50=    nanms p90=    nanms p99=    nanms max=    0.0ms
failed    n=300   p50=   74.1ms p90=  183.0ms p99=  630.6ms max=  637.8ms
health    ok=4 failed=0 n=4     p50=   18.2ms p90=  103.1ms p99=  103.1ms max=  103.1ms

mode=grpc orders=300 clients=20 wall=1.3s rate=227/s codes={503: 300}
order     n=0     p50=    nanms p90=    nanms p99=    nanms max=    0.0ms
failed    n=300   p50=   69.5ms p90=  133.3ms p99=  222.3ms max=  242.1ms
health    ok=3 failed=0 n=3     p50=    8.6ms p90=   62.1ms p99=   62.1ms max=   62.1ms

sw5-sc-orders  | breaker inventory: OPEN
while inventory is paused:
payments: {"rest":0,"grpc":0,"event":0}
after unpause:
payments: {"rest":0,"grpc":0,"event":0}
inventory: {"rest":21,"grpc":0,"event":0}
```

في المخرج أعلاه لاحظ التالي:

- كل الطلبات فشلت أيضاً، وهذا متوقع لأن المخزون معطل، ولكنها فشلت بسرعة وبرمز واضح: 21 طلباً بالرمز 504 بعد نصف ثانية، وهي التي كانت في الطريق قبل أن يفتح القاطع، ثم 279 طلباً بالرمز 503 دون أن تحاول أصلاً. وانتهى القياس كله في أقل من ثانيتين بدلاً من خمسين.
- فحص الصحة نجح في كل المرات، فخدمة الطلبات بقيت سليمة وموزع الطلبات لن يخرجها، والعطل بقي في مكانه.
- في gRPC كانت كل الطلبات 503، لأن القاطع واحد لخدمة المخزون مهما كان الأسلوب، وكان ما زال مفتوحاً من تجربة REST قبل ثانيتين.
- المدفوعات لم تستقبل أي طلب، لأن الحجز أصبح قبل الدفع، فإذا فشل الحجز لا يحدث دفع. وهذا الترتيب قاعدة عامة: نفذ أولاً الخطوة التي يسهل التراجع عنها، فإلغاء حجز كتاب أسهل كثيراً من إرجاع مبلغ إلى بطاقة.
- بعد فك التجميد استقبل المخزون 21 طلب حجز عبر REST، وهي نفس الطلبات التي أعطت 504\. فالمهلة في الكلاينت لا تلغي الطلب الذي وصل إلى السيرفر، والسيرفر ينفذه عندما يستطيع، فتبقى حجوزات لطلبات فشلت ويجب أن يلغيها شيء، وهذا هو دور Saga وعمليات التعويض.
- أما في gRPC فلم يستقبل المخزون أي طلب بعد فك التجميد، لأن المهلة تنتقل مع الطلب نفسه في gRPC، والطلب الذي انتهت مهلته لا يبدأ تنفيذه، وهذا فرق حقيقي لصالح gRPC في الأعطال.

وقد شرحنا المهلة وإعادة المحاولة بميزانية والحواجز Bulkheads ورفض الزائد Load Shedding بالتفصيل وبتجربة كاملة في [مقال أنماط الحماية](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D9%85%D9%86%D8%B9-%D8%AE%D8%AF%D9%85%D8%A9-%D8%A8%D8%B7%D9%8A%D8%A6%D8%A9-%D9%85%D9%86-%D8%A7%D8%B3%D9%82%D8%A7%D8%B7-%D9%86%D8%B8%D8%A7%D9%85%D9%83-%D9%83%D9%84%D9%87/)، والمهم هنا أن هذه الأنماط ضرورة في كل استدعاء متزامن، وليست تحسيناً تضيفه لاحقاً.

### نوقف المخزون مع الأحداث

الآن نفس العطل في أسلوب الأحداث: نجمد المخزون، ونرسل 1000 طلب، وبعد 25 ثانية نسأل NATS عن حالة المستهلكين، ثم نفك التجميد:

```bash
docker pause sw5-sc-inventory
docker compose run --rm -T bench async 1000 10 --probe &
sleep 25
docker run --rm --network sw5-sc_default natsio/nats-box:0.20.0 nats -s nats://nats:4222 consumer report SHOP
docker unpause sw5-sc-inventory
```

```text
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                       Consumer report for SHOP with 2 consumers                                      │
├───────────┬──────┬────────────┬──────────┬─────────────┬─────────────┬─────────────┬───────────┬───────────┬─────────┤
│ Consumer  │ Mode │ Ack Policy │ Ack Wait │ Ack Pending │ Redelivered │ Unprocessed │ Ack Floor │ API Level │ Cluster │
├───────────┼──────┼────────────┼──────────┼─────────────┼─────────────┼─────────────┼───────────┼───────────┼─────────┤
│ inventory │ Push │ Explicit   │ 30.00s   │ 1,000       │ 0           │ 0           │ 24,346    │ 0         │         │
│ payments  │ Push │ Explicit   │ 30.00s   │ 0           │ 0           │ 0           │ 26,193    │ 0         │         │
╰───────────┴──────┴────────────┴──────────┴─────────────┴─────────────┴─────────────┴───────────┴───────────┴─────────╯

mode=async orders=1000 clients=10 wall=7.0s rate=144/s codes={202: 1000}
accepted  n=1000  p50=   60.3ms p90=  116.3ms p99=  235.6ms max=  350.0ms
end2end   n=1000  p50=31020.1ms p90=32218.2ms p99=32702.2ms max=32722.3ms completed=1000/1000
health    ok=78 failed=0 n=78    p50=    3.7ms p90=   25.1ms p99=   74.1ms max=   74.1ms
```

في المخرج أعلاه لاحظ التالي:

- خدمة الطلبات قبلت الألف طلب كلها بالرمز 202، وفحص الصحة نجح 78 مرة دون فشل واحد، أي أن العطل لم يصل إليها أبداً.
- المدفوعات عالجت كل الأحداث، والعمود `Ack Pending` للمخزون 1,000، أي أن الوسيط سلم الألف حدث إلى المخزون وينتظر تأكيدها. وفي المستهلك من نوع Push يرسل الوسيط الرسائل إلى الكلاينت دون أن يسأل، حتى يصل إلى حد `Max Ack Pending`، فبقيت الرسائل في انتظار الخدمة المجمدة.
- بعد فك التجميد اكتمل الألف طلب، وكان الوسيط من القبول إلى الحجز 31 ثانية، وهي مدة العطل تقريباً. أي أن العملية تأخرت ولم تضع، وهذا هو الوعد الحقيقي للأحداث.

ثم سألنا الوسيط والخدمتين بعد دقيقة:

```text
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                       Consumer report for SHOP with 2 consumers                                      │
├───────────┬──────┬────────────┬──────────┬─────────────┬─────────────┬─────────────┬───────────┬───────────┬─────────┤
│ Consumer  │ Mode │ Ack Policy │ Ack Wait │ Ack Pending │ Redelivered │ Unprocessed │ Ack Floor │ API Level │ Cluster │
├───────────┼──────┼────────────┼──────────┼─────────────┼─────────────┼─────────────┼───────────┼───────────┼─────────┤
│ inventory │ Push │ Explicit   │ 30.00s   │ 0           │ 0           │ 0           │ 26,420    │ 0         │         │
│ payments  │ Push │ Explicit   │ 30.00s   │ 0           │ 0           │ 0           │ 26,193    │ 0         │         │
╰───────────┴──────┴────────────┴──────────┴─────────────┴─────────────┴─────────────┴───────────┴───────────┴─────────╯

payments: {"rest":0,"grpc":0,"event":1000}
inventory: {"rest":21,"grpc":0,"event":1001}
╭───────────────────────────────────────────────────────╮
│               3 Subjects in stream SHOP               │
├────────────────────┬───────┬──────────────────┬───────┤
│ Subject            │ Count │ Subject          │ Count │
├────────────────────┼───────┼──────────────────┼───────┤
│ inventory.reserved │ 9,140 │ payments.charged │ 9,140 │
│ orders.placed      │ 9,140 │                  │       │
╰────────────────────┴───────┴──────────────────┴───────╯
```

هنا مفاجأة صغيرة لها معنى كبير: المدفوعات عالجت 1000 حدث، والمخزون عالج 1001\. والسبب أن أحد الأحداث تأخر تأكيده أكثر من مدة الانتظار `Ack Wait` وهي 30 ثانية، فاعتبره الوسيط ضائعاً وأرسله مرة أخرى، وكانت الخدمة قد عالجته فعلاً. ولاحظ أن عدد الرسائل في ال Stream متساو في المواضيع الثلاثة، 9,140 لكل منها، لأن الحدث الذي نشره المخزون مرتين له نفس `Nats-Msg-Id` فتجاهل JetStream النسخة الثانية. أي أن منع التكرار في الوسيط حمى ال Stream، ولكنه لم يحم العمل نفسه: الحجز نفذ مرتين. ولكي ترى منع التكرار وحده نرسل نفس الحدث مرتين بنفس المعرف:

```bash
docker run --rm --network sw5-sc_default natsio/nats-box:0.20.0 sh -c 'for i in 1 2; do
  nats -s nats://nats:4222 req orders.placed \
  "{\"order_id\":\"ord_demo000001\",\"customer_id\":\"cus_1\",\"amount_halalas\":100,\"currency\":\"SAR\",\"items\":[],\"placed_at\":0}" \
  -H Nats-Msg-Id:orders.placed:ord_demo000001; done'
```

```text
11:55:18 Sending request on "orders.placed"
11:55:18 Received with rtt 15.643978ms
{"stream":"SHOP","seq":33427}

11:55:18 Sending request on "orders.placed"
11:55:18 Received with rtt 452.125µs
{"stream":"SHOP","seq":33427,"duplicate": true}
```

الرد الثاني يحمل `"duplicate": true` ونفس رقم الرسالة 33427، فلم يحفظ JetStream نسخة ثانية. وهذا مفيد عندما تعيد خدمة الطلبات النشر بعد خطأ في الشبكة، ولكنه لا يغني عن مستهلك آمن عند التكرار يتذكر الأحداث التي عالجها، كما شرحنا في [مقال Idempotency](https://arabroot.io/articles/idempotency-%D9%83%D9%8A%D9%81-%D8%AA%D8%AC%D8%B9%D9%84-%D8%A7%D9%84%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D8%A7%D9%85%D9%86%D8%A9-%D8%B9%D9%86%D8%AF-%D8%AA%D9%83%D8%B1%D8%A7%D8%B1%D9%87%D8%A7/#idempotent-consumer).

### ماذا يحدث إذا توقف الوسيط Broker نفسه؟

نقلنا الاعتماد من المخزون إلى الوسيط، فماذا إذا توقف الوسيط؟

```text
$ docker stop sw5-sc-nats
$ POST /orders/async
Internal Server Error -> 500 in 5.007042s
$ POST /orders/rest
{"order_id":"ord_4ced387ee0","payment_id":"pay_09f6bf49ad","reservation_id":"res_26f6925b6e","downstream_ms":75.4} -> 201 in 0.080840s
$ docker start sw5-sc-nats
{"order_id":"ord_bfc0152239","status":"PENDING","stream_seq":33424} -> 202 in 0.008050s
```

طلب الأحداث انتظر 5 ثوان ثم فشل بالرمز 500، والسجل يقول `nats.errors.TimeoutError: nats: timeout`، أما REST فنجح لأنه لا يمر بالوسيط أصلاً. وبعد أن عاد الوسيط اتصلت به خدمة الطلبات من جديد تلقائياً ونجح الطلب التالي. والدرس أن الوسيط أصبح الاعتماد الوحيد لمسار الأحداث، لذلك يعمل في الإنتاج كعنقود من ثلاث عقد على الأقل، كما شرحنا في [دليل NATS](https://arabroot.io/articles/nats-%D8%B1%D8%B3%D8%A7%D8%A6%D9%84-%D8%B3%D8%B1%D9%8A%D8%B9%D8%A9-%D9%88%D8%AE%D9%81%D9%8A%D9%81%D8%A9-%D9%84%D9%84%D8%AE%D8%AF%D9%85%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B5%D8%BA%D8%B1%D8%A9/). وهناك مشكلة أدق: لو كانت خدمة الطلبات تحفظ الطلب في قاعدة بياناتها ثم تنشر الحدث، وتوقف الوسيط بين الخطوتين، لبقي طلب محفوظ لا يعرف به أحد، وهذا ما يحله نمط Outbox الذي يكتب الحدث في نفس معاملة قاعدة البيانات ثم ينشره عامل منفصل.

### نتحقق من عقد الأحداث AsyncAPI

آخر خطوة أن نكتب عقد الأحداث في الملف `asyncapi.yaml`، وفيه القناتان والرسالتان ومن يرسل ومن يستقبل، وشكل كل رسالة:

```yaml
asyncapi: 3.0.0
info:
  title: Shop order events
  version: 1.0.0
  description: Events that carry one order from the orders service to payments and inventory.
servers:
  lab:
    host: nats:4222
    protocol: nats
channels:
  ordersPlaced:
    address: orders.placed
    messages:
      orderPlaced:
        $ref: '#/components/messages/orderPlaced'
  paymentsCharged:
    address: payments.charged
    messages:
      paymentCharged:
        $ref: '#/components/messages/paymentCharged'
operations:
  publishOrderPlaced:
    action: send
    channel: { $ref: '#/channels/ordersPlaced' }
    summary: orders publishes one event for every accepted order
  consumeOrderPlaced:
    action: receive
    channel: { $ref: '#/channels/ordersPlaced' }
    summary: payments charges the customer, then publishes payments.charged
components:
  messages:
    orderPlaced:
      headers:
        type: object
        properties:
          Nats-Msg-Id: { type: string, description: 'orders.placed:<order_id>, used to drop duplicates' }
      payload:
        type: object
        required: [order_id, customer_id, amount_halalas, currency, items, placed_at]
        properties:
          order_id: { type: string, pattern: '^ord_[0-9a-f]{10}$' }
          customer_id: { type: string }
          amount_halalas: { type: integer, minimum: 1 }
          currency: { type: string, enum: [SAR] }
          placed_at: { type: number, description: Unix time in seconds }
          items:
            type: array
            items:
              type: object
              required: [sku, qty]
              properties:
                sku: { type: string }
                qty: { type: integer, minimum: 1 }
                price_halalas: { type: integer }
    paymentCharged:
      payload:
        allOf:
          - $ref: '#/components/messages/orderPlaced/payload'
          - type: object
            required: [payment_id]
            properties:
              payment_id: { type: string }
              payments_at: { type: number }
```

ثم نتحقق منه بالمكتبة الرسمية @asyncapi/parser بسكربت صغير:

```javascript
// node validate-asyncapi.mjs asyncapi.yaml: checks the contract with the official AsyncAPI parser
import { readFileSync } from 'node:fs';
import { Parser } from '@asyncapi/parser';

const { document, diagnostics } = await new Parser().parse(readFileSync(process.argv[2], 'utf8'));
for (const d of diagnostics) console.log(`${['error', 'warning', 'info', 'hint'][d.severity]}  ${d.code}  ${d.path.join('.')}  ${d.message}`);
if (!document) process.exit(1);
console.log(`valid AsyncAPI ${document.version()}: ${document.channels().length} channels, ${document.messages().length} messages, ${document.operations().length} operations`);
```

```bash
docker run --rm -v "$PWD":/c:ro node:22-alpine sh -c 'mkdir /w && cd /w && \
  npm i --silent @asyncapi/parser@3 && cp /c/asyncapi.yaml /c/validate-asyncapi.mjs . && \
  npm ls @asyncapi/parser | tail -2 && node validate-asyncapi.mjs asyncapi.yaml'
```

```text
`-- @asyncapi/parser@3.6.6

info  asyncapi-latest-version  asyncapi  The latest version of AsyncAPi is not used. It is recommended update to the "3.1.0" version.
valid AsyncAPI 3.0.0: 2 channels, 2 messages, 2 operations
```

العقد صحيح، والمحلل نبهنا إلى أن الإصدار 3.1.0 من المواصفة صدر، وهي ملاحظة وليست خطأ. وشغل نفس الفحص في خط CI مع كل تعديل على ملف العقد، كما تفعل مع `buf breaking` لملفات protobuf، حتى لا يصل عقد غير صحيح إلى الفرق الأخرى.

![مقارنة بالأرقام من التجربة: الاستدعاءان بكلاينت واحد 18.5 ملي ثانية في REST و12.3 في gRPC، والبايتات لكل طلب في بطاقة شبكة المدفوعات 874 في REST و324 في gRPC و1467 في الأحداث، وقبول الطلب في الأحداث 5.3 ملي ثانية والإكمال 82.8](https://arabroot.io/content/images/2026/11/service-communication-03-lab-numbers.webp)

gRPC أصغر وأسرع في الاستدعاء، والأحداث أسرع في الرد على العميل وأبطأ في إكمال العملية، وأرقامها تعتمد على المستهلك أكثر من الوسيط

![ثلاثة خطوط زمنية عند تجميد خدمة المخزون: REST بلا مهلة يفشل فيه كل الطلبات بعد عشر ثوان ويموت فحص الصحة وتخصم المدفوعات 40 مرة، ومع المهلة والقاطع والحجز أولاً يفشل كل طلب خلال نصف ثانية ويبقى فحص الصحة سليماً ولا يخصم شيء، ومع الأحداث تقبل كل الطلبات وتكتمل بعد عودة المخزون مع حدث واحد معالج مرتين](https://arabroot.io/content/images/2026/11/service-communication-04-failure.webp)

نفس العطل بثلاثة إعدادات: الأول ينقل العطل إلى كل النظام، والثاني يحصره، والثالث يؤجله

### حذف المختبر Cleanup

```bash
docker compose down
docker rmi sw5-sc-app:lab
```

## كيف تختار أسلوب كل تواصل؟ Decision Table

لا يوجد أسلوب واحد لكل النظام، والأنظمة الناضجة تستخدم الثلاثة معاً، وكل تواصل بين خدمتين يختار أسلوبه بسؤالين: هل يحتاج المستدعي الجواب ليكمل عمله الآن؟ وهل يجب أن تنجح العملية والخدمة الأخرى معطلة؟ والجدول التالي يجمع ما رأيناه في المقال والتجربة:

| الموقف                                                                              | الأسلوب الأنسب                 | والسبب                                                                                                               |
| ----------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| المتصفح أو تطبيق الجوال أو شريك خارجي يستدعي خدمتك                                  | REST مع OpenAPI                | كل أداة وكل لغة تفهمه، ويمر عبر أي Proxy وCDN، ويقرؤه الإنسان                                                        |
| خدمة تحتاج جواباً فورياً من خدمة داخلية، مثل التحقق من الرصيد قبل عرض زر الدفع      | gRPC مع مهلة نهائية Deadline   | حجم الرسائل على الشبكة حوالي ثلث REST في تجربتنا، واتصال واحد مفتوح، والمهلة تنتقل مع الطلب فلا ينفذ طلب انتهت مهلته |
| استدعاءات كثيرة جداً بين خدمتين داخليتين، أو بث مستمر Streaming                     | gRPC                           | الفرق في البايتات والزمن يصبح مالاً حقيقياً عند ملايين الطلبات                                                       |
| العملية يجب أن تقبل حتى لو كانت الخدمة التالية معطلة، والعميل يحتمل أن تكتمل لاحقاً | حدث عبر وسيط مع AsyncAPI       | رأينا 1000 طلب تقبل والمخزون مجمد، ثم تكتمل كلها بعد عودته                                                           |
| عدة خدمات تهتم بنفس الحدث، والمرسل لا يجب أن يعرفها                                 | حدث، نشر واشتراك Pub/Sub       | تضيف مستهلكاً جديداً دون أن تعدل المرسل                                                                              |
| عملية تمتد على عدة خدمات ويجب أن تتراجع عند الفشل                                   | Saga بأوامر أو أحداث مع Outbox | لا توجد معاملة واحدة تجمع قواعد بيانات الخدمات                                                                       |
| الخدمتان يعدلهما نفس الفريق وتنشران معاً دائماً                                     | ربما لا تحتاج خدمتين           | كل استدعاء شبكي ثمنه الذي رأيته في المقال، والدالة داخل نفس التطبيق أرخص                                             |

![مخطط قرار: هل يحتاج المستدعي الجواب ليكمل عمله الآن؟ لا: حدث عبر وسيط مع مستهلك آمن عند التكرار. نعم: هل المستدعي متصفح أو شريك خارجي؟ نعم: REST مع OpenAPI. لا: gRPC مع مهلة. ومع كل استدعاء متزامن: مهلة وقاطع دائرة وترتيب الخطوات من الأسهل تراجعاً](https://arabroot.io/content/images/2026/11/service-communication-05-decision.webp)

ابدأ بالسؤال عن الانتظار، ثم اختر الصيغة، ولا يوجد استدعاء متزامن دون مهلة

## أخطاء شائعة Common Mistakes

- **استدعاء متزامن دون مهلة**: الافتراضي في requests وgRPC الانتظار للأبد، ورأيت كيف أخذت أربعون طلباً معلقة كل خيوط الخدمة وأسقطت فحص الصحة.
- **سلسلة طويلة من الاستدعاءات المتزامنة**: كل خدمة في السلسلة تنقص من توفر العملية، وعشر خدمات بتوفر 99.9% تعطي عملية بتوفر 99%.
- **تنفيذ الخطوة التي يصعب التراجع عنها أولاً**: الدفع قبل الحجز خصم أموال أربعين عميلاً في تجربتنا ولم يعطهم شيئاً.
- **الاعتقاد أن المهلة تلغي العمل في السيرفر**: في REST نفذ المخزون 21 حجزاً لطلبات انتهت مهلتها عند الكلاينت، لذلك تحتاج عمليات تعويض أو مفتاح Idempotency يكتشف الطلب المكرر.
- **مستهلك يعالج حدثاً واحداً في كل مرة**: لا يظهر أي خطأ، والتأخير يكبر بصمت حتى يصل إلى ثوان، فراقب عمر أقدم رسالة غير معالجة وليس عدد الأخطاء فقط.
- **الاعتماد على منع التكرار في الوسيط**: `Nats-Msg-Id` منع حفظ النسخة الثانية في ال Stream، ولكن المخزون عالج الحدث مرتين، والحماية الحقيقية في المستهلك.
- **نشر الحدث بعد الحفظ في قاعدة البيانات بخطوتين منفصلتين**: إذا توقف الوسيط بينهما يضيع الحدث، واستخدم Outbox.
- **تغيير اسم حقل JSON أو رقم حقل protobuf دون فحص التوافق**: الأول يعطي قيمة فارغة بصمت، والثاني يقرأ الرسائل القديمة بمعنى جديد.
- **أحداث بلا عقد مكتوب**: في التنسيق بالأحداث لا يظهر المستقبلون في كود المرسل، فإذا لم يكن هناك ملف AsyncAPI لا يعرف أحد من سوف يتأثر بالتعديل.
- **استخدام 201 لعملية غير متزامنة**: الرد الصحيح 202 مع حالة PENDING وطريقة للاستعلام عن الحالة لاحقاً.

## قائمة تحقق Checklist

- لكل تواصل بين خدمتين حددت: هل ينتظر المستدعي الجواب، وماذا يحدث إذا كانت الخدمة الأخرى معطلة.
- كل استدعاء متزامن له مهلة أقل من مهلة من يستدعيه، وفي gRPC تمرر المهلة المتبقية مع الطلب.
- كل اعتماد متزامن خلفه قاطع دائرة، وفحص الصحة لا يمر بنفس مجمع الخيوط الذي يمكن أن يمتلئ.
- الخطوات في العملية مرتبة من الأسهل تراجعاً إلى الأصعب، ولكل خطوة عملية تعويض.
- كل مستهلك أحداث آمن عند التكرار، ويعالج عدة أحداث معاً، ومراقب بعمر أقدم رسالة.
- الأحداث تنشر من جدول Outbox في نفس معاملة قاعدة البيانات.
- لكل واجهة عقد مكتوب: OpenAPI أو protobuf أو AsyncAPI، وفحص التوافق يعمل في خط CI.
- الوسيط يعمل كعنقود، ومراقب، وله خطة عندما يتوقف.
- الطلبات بين الخدمات مرئية في أداة تتبع موزع، حتى ترى مسار العملية عبر الخدمات.

## ماذا تقرأ بعد ذلك؟ Next Steps

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

[![](https://arabroot.io/content/images/2026/10/service-discovery-cover-cover.webp)دليلاكتشاف الخدمات وإعداداتها مع Consul وetcdكيف تجد خدماتك بعضها رغم تغير عناوينها، وكيف توزع الإعدادات عليها، وماذا يحدث عندما يفقد العنقود الأغلبية.](https://arabroot.io/articles/%D8%A7%D9%83%D8%AA%D8%B4%D8%A7%D9%81-%D8%A7%D9%84%D8%AE%D8%AF%D9%85%D8%A7%D8%AA-%D9%88%D8%A7%D8%B9%D8%AF%D8%A7%D8%AF%D8%A7%D8%AA%D9%87%D8%A7-%D9%85%D8%B9-consul-%D9%88-etcd/)[![](https://arabroot.io/content/images/2026/10/resilience-patterns-cover-cover.webp)دليلكيف تمنع خدمة بطيئة من إسقاط نظامك كله؟لماذا تسقط خدمة بطيئة واحدة تطبيقك السليم، وكيف تحميه بالمهلة وإعادة المحاولة المحدودة وقاطع الدائرة ورفض الزائد.](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D9%85%D9%86%D8%B9-%D8%AE%D8%AF%D9%85%D8%A9-%D8%A8%D8%B7%D9%8A%D8%A6%D8%A9-%D9%85%D9%86-%D8%A7%D8%B3%D9%82%D8%A7%D8%B7-%D9%86%D8%B8%D8%A7%D9%85%D9%83-%D9%83%D9%84%D9%87/)[![](https://arabroot.io/content/images/2026/10/idempotency-cover-cover.webp)دليلIdempotency: كيف تجعل العملية آمنة عند تكرارهالماذا تصل الرسالة نفسها أكثر من مرة، وكيف تكتب مستهلكاً يطبقها مرة واحدة فقط مهما تكررت.](https://arabroot.io/articles/idempotency-%D9%83%D9%8A%D9%81-%D8%AA%D8%AC%D8%B9%D9%84-%D8%A7%D9%84%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D8%A7%D9%85%D9%86%D8%A9-%D8%B9%D9%86%D8%AF-%D8%AA%D9%83%D8%B1%D8%A7%D8%B1%D9%87%D8%A7/)[![](https://arabroot.io/content/images/2026/10/saga-outbox-cover-cover.webp)دليلالمعاملات الموزعة: Saga ونمط Outbox بدل 2PCكيف تنفذ عملية تمتد على عدة خدمات دون 2PC، بخطوات محلية وتعويضات وجدول Outbox لا يضيع فيه أي حدث.](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D8%B9%D8%A7%D9%85%D9%84%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D9%88%D8%B2%D8%B9%D8%A9-saga-%D9%88%D9%86%D9%85%D8%B7-outbox/)[![](https://arabroot.io/content/images/2026/10/distributed-tracing-cover-cover.webp)دليلالتتبع الموزع Distributed Tracing مع OpenTelemetryكيف ترى طلباً واحداً يمر بعدة خدمات في شجرة زمنية واحدة، فتعرف أين أبطأ وأين فشل دون أن تخمن من السجلات.](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%AA%D8%A8%D8%B9-%D8%A7%D9%84%D9%85%D9%88%D8%B2%D8%B9-distributed-tracing-%D9%85%D8%B9-opentelemetry/)[![](https://arabroot.io/content/images/2026/10/api-design-cover-cover.webp)دليلكيف تصمم API يبقى متوافقاً مع عملائه بعد سنةمبادئ تصميم API يتطور دون أن يعطل التطبيقات التي تعتمد عليه، وكيف تختار الشكل المناسب لنظامك.](https://arabroot.io/articles/%D8%AA%D8%B5%D9%85%D9%8A%D9%85-%D9%88%D8%A7%D8%AC%D9%87%D8%A7%D8%AA-api-rest-%D9%88-grpc-%D9%88-graphql/)

[![](https://arabroot.io/content/images/2026/10/queue-compare-cover-cover.webp)دليلRabbitMQ أم Kafka أم NATS؟ كيف تختار وسيط الرسائلكيف تختار بين RabbitMQ وKafka وNATS بحسب نموذج كل منها وضماناته وتكلفة تشغيله، مع قياس على جهاز واحد.](https://arabroot.io/articles/rabbitmq-%D8%A7%D9%85-kafka-%D8%A7%D9%85-nats-%D9%83%D9%8A%D9%81-%D8%AA%D8%AE%D8%AA%D8%A7%D8%B1-%D9%88%D8%B3%D9%8A%D8%B7-%D8%A7%D9%84%D8%B1%D8%B3%D8%A7%D8%A6%D9%84/)[![](https://arabroot.io/content/images/2026/10/nats-cover-cover.webp)دليلNATS: رسائل سريعة وخفيفة للخدمات المصغرةكيف تربط خدماتك بالطلب والرد عبر NATS، ومتى تحتاج JetStream ليحفظ الرسائل ويتذكر أين وصل كل مستهلك.](https://arabroot.io/articles/nats-%D8%B1%D8%B3%D8%A7%D8%A6%D9%84-%D8%B3%D8%B1%D9%8A%D8%B9%D8%A9-%D9%88%D8%AE%D9%81%D9%8A%D9%81%D8%A9-%D9%84%D9%84%D8%AE%D8%AF%D9%85%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B5%D8%BA%D8%B1%D8%A9/)[![](https://arabroot.io/content/images/2026/11/background-jobs-cover-cover.webp)دليلالمهام الخلفية Background Jobs: لماذا لا ينتظر المستخدم؟كيف تخرج إرسال البريد ومعالجة الملفات من الطلب إلى عامل يعمل في الخلفية، مع تجربة على Celery وRedis تقيس زمن الطلب قبل وبعد وتقتل العامل في منتصف مهمة.](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D9%87%D8%A7%D9%85-%D8%A7%D9%84%D8%AE%D9%84%D9%81%D9%8A%D8%A9-background-jobs-%D9%84%D9%85%D8%A7%D8%B0%D8%A7-%D9%84%D8%A7-%D9%8A%D9%86%D8%AA%D8%B8%D8%B1-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D8%AE%D8%AF%D9%85/)[![](https://arabroot.io/content/images/2026/11/queue-retries-dlq-cover-cover.webp)دليلإعادة المحاولة Retry وDead Letter Queue وPoison Messageكيف تكتب سياسة إعادة محاولة في الطابور لا تملأ ال Dead Letter Queue برسائل سليمة ولا تغرق خدمة متعبة، بسبع سياسات شغلناها على RabbitMQ وSQS أمام نفس العطل.](https://arabroot.io/articles/%D8%A7%D8%B9%D8%A7%D8%AF%D8%A9-%D8%A7%D9%84%D9%85%D8%AD%D8%A7%D9%88%D9%84%D8%A9-retry-%D9%88-dead-letter-queue-%D9%81%D9%8A-%D8%A7%D9%84%D8%B7%D9%88%D8%A7%D8%A8%D9%8A%D8%B1/)[![](https://arabroot.io/content/images/2026/11/webhooks-cover-cover.webp)دليلWebhooks: كيف ترسل الأحداث بين الأنظمة وتستقبلها بأمانكيف تستقبل رسائل الـ Webhook وترسلها دون أن تخدعك رسالة مزورة أو مكررة أو قديمة، مع تجربة تعيد كل عطل من التوقيع الخاطئ إلى ثلاثة إيصالات لدفعة واحدة.](https://arabroot.io/articles/webhooks-%D9%83%D9%8A%D9%81-%D8%AA%D8%B1%D8%B3%D9%84-%D8%A7%D9%84%D8%A7%D8%AD%D8%AF%D8%A7%D8%AB-%D8%A8%D9%8A%D9%86-%D8%A7%D9%84%D8%A7%D9%86%D8%B8%D9%85%D8%A9-%D9%88%D8%AA%D8%B3%D8%AA%D9%82%D8%A8%D9%84%D9%87%D8%A7-%D8%A8%D8%A7%D9%85%D8%A7%D9%86/)

## الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

- السؤال الأول ليس REST أم gRPC، وإنما هل ينتظر المستدعي الجواب، لأن الاستدعاء المتزامن يربط توفر الخدمات ببعضها، وثلاث خدمات بتوفر 99.9% تعطي عملية بتوفر 99.7%.
- REST للواجهات العامة لأن الجميع يفهمه، وgRPC للاستدعاءات الداخلية الكثيرة، وفي تجربتنا كانت بايتاته على الشبكة حوالي ثلث بايتات REST وزمن الاستدعاءين أقل في الوسيط والذيل.
- الأحداث تفك الاقتران الزمني: قبلت خدمة الطلبات 1000 طلب والمخزون مجمد، واكتملت كلها بعد عودته، ولكنها أبطأ في إكمال العملية، وتحتاج مستهلكاً متوازياً، وآمناً عند التكرار، ووسيطاً لا يتوقف.
- بلا مهلة أسقطت خدمة مجمدة خدمة سليمة، وخصمت المدفوعات أموالاً لطلبات فشلت، وبالمهلة والقاطع والحجز قبل الدفع فشلت الطلبات بسرعة وبقيت الخدمة سليمة ولم يخصم شيء.
- المهلة في REST لا تلغي العمل في السيرفر، والمهلة في gRPC تنتقل مع الطلب، ومنع التكرار في الوسيط لا يمنع المعالجة المكررة.
- لكل أسلوب عقده: OpenAPI وprotobuf وAsyncAPI، والإضافة آمنة، والحذف وتغيير الأسماء والأرقام يخل بالتوافق.

## سجل التحديثات Changelog

- 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجارب على Docker Engine 29.8.0 مع Python 3.13.18 وFastAPI 0.121.2 وgrpcio 1.76.0 وnats-py 2.12.0 وNATS 2.15.0 وnats-box 0.20.0 و@asyncapi/parser 3.6.6.