مهلة البناء مقابل مهلة واجهة API: لماذا لا يمكن لطلب يستغرق 700 ثانية أن ينتهي داخل بناء مدته 600 ثانية

المشكلة ليست مجرد طلب بطيء

قد يبدو النشر بسيطاً: يجلب البناء بيانات من واجهة API ثم يحوّلها وينتج صفحات ثابتة. لكن إذا سُمح للطلب بالانتظار 700 ثانية بينما توقف المنصة البناء عند 600 ثانية، فالنتيجة محسومة قبل أن يبدأ الطلب.

هذه ليست مشكلة عشوائية. إنها تعارض بين المهل الزمنية. والأسوأ أن طلب البيانات ليس العمل الوحيد داخل البناء؛ فالتثبيت، والترجمة، وكتابة المخرجات ورفعها تستهلك من الحد نفسه.

أقصر مهلة هي التي تحكم

توجد عادة طبقات متعددة من المهلات:

الطبقة	مثال
الحد الأقصى للبناء في المنصة	600 ثانية
مهمة CI	15 دقيقة
مهلة جلب البيانات في الإطار	60 ثانية
مهلة عميل HTTP	700 ثانية
وكيل أو API خارجي	30 ثانية

أصغر مهلة قابلة للتطبيق هي التي تنهي العملية. تغيير مهلة العميل إلى 700 ثانية لا يمدد منصة تقتل العملية عند 600 ثانية.

ابدأ بخط زمني للبناء

قبل رفع رقم المهلة، سجل وقت بداية البناء، وبداية الطلب، ووقت أول بايت، وحالة HTTP، ومعرّف الطلب لدى الخدمة، وعدد المحاولات، والطبقة التي أصدرت رسالة الفشل. استخدم معرّف ربط يصل إلى الـ API، ولا تسجل الرموز أو الترويسات الحساسة.

خصص ميزانية لكل عملية

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

async function fetchJson(url, { timeoutMs = 15_000, ...options } = {}) {
  const response = await fetch(url, {
    ...options,
    signal: AbortSignal.timeout(timeoutMs),
  });

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

إن كان لدى المستدعي إشارة إلغاء أصلاً، اجمعها مع مهلة الطلب باستخدام AbortSignal.any() بدلاً من استبدالها.

اجعل إعادة المحاولة محدودة

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

أصلح المسار الحرج

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

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

متى تكون زيادة المهلة صحيحة؟

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

قائمة تحقق للنشر

• حدد أول مهلة بين المنصة وCI والوكيل والعميل والخدمة الخارجية.
• احتفظ بوقت بعد الجلب لبقية البناء.
• اضبط مهلة صريحة لكل طلب خارجي.
• قيد إعادة المحاولة بمهلة كلية وتأخير متزايد وتشويش.
• استخدم التخزين المؤقت أو اللقطات للمدخلات البطيئة.
• انقل المعالجة الطويلة إلى مهام خلفية.
• سجل الأزمنة والحالة ومعرّفات الطلبات دون أسرار.

الخلاصة

طلب مدته 700 ثانية داخل بيئة حدها 600 ثانية هو إشارة تصميم، لا مشكلة ضبط رقم. اجعل البيانات أسرع، أو اقبل لقطة مخبأة، أو نفذ العمل البطيء في مكان آخر. عندما تملك كل طبقة ميزانية واقعية، تصبح عمليات النشر قابلة للتنبؤ.