المستوى 6 · في الممارسة

6.2إصلاح سريع

الهدف: تحويل الإتقان التقني لـ Node إلى منعكسات إنتاج موثوقة وفعالة وآمنة.

الوقت المقدّر: 14 دقيقة · إذا كان لديك 5 دقائق فقط: اقرأ «الأساسي في 30 ثانية» + المخطط.

الأساسي في 30 ثانية

المنعكس : عرض = أسباب محتملة = إجراء مستهدف — نشخص قبل إعادة التشغيل.
الحلقة : خادم يتجمد أو يسقط يشير غالباً إلى البرمجة غير المتزامنة (Asynchronous) أو الأخطاء غير المدبرة.
الإنتاج : كل فرق بين المحلي والإنتاج يُعالج بالحاويات ومتغيرات البيئة والسجلات (Logs).

خيط ساليم — الدليل الملصق بجانب الشاشة

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

عرض ملاحظ، وأسباب متحقق منها، وإجراءات بالترتيب : المنعكس يتم في ثلاثة أوقات.

التشخيص قبل إعادة التشغيل

مشكلة Node نادراً ما تُحل عشوائياً : لكل عرض أسباب نمطية وإجراء مستهدف. الجدول أدناه يجمع الحالات الأكثر شيوعاً، من غير المتزامن إلى النشر.

العَرَض	الأسباب المحتملة	الإجراءات
أحصل على undefined بدل نتيجتي	شيفرة غير متزامنة مدبرة بشكل سيئ : النتيجة غير جاهزة في السطر التالي	استعمل await (دالة async) أو .then() ؛ فكر « عندما يجهز » ؛ أحط بـ try/catch ‏(1.2)
UnhandledPromiseRejection / الخادم يسقط	وعد (Promise) مرفوض غير مدبر ؛ لا تدبير مركزي للأخطاء	أحط await بـ try/catch ؛ وسيط أخطاء مركزي (err, req, res, next) ؛ دبّر حدث «error» ‏(4.4)
الخادم « يتجمد » حالما يتعدد المستخدمون	عملية متزامنة (fs.*Sync) أو حساب ثقيل على المعالج (CPU) يحجب حلقة الأحداث (Event loop)	مرر إلى غير المتزامن (fs.promises) ؛ فوّض المعالج الثقيل إلى خيوط العمال (Worker threads) ؛ لا تحجب الحلقة أبداً (2.1/5.2)
Cannot find module / خطأ استيراد	مسار خاطئ، أو node_modules غائب، أو خلط CommonJS / ESM	npm install ؛ تحقق من ./ للمحلي مقابل الاسم لـ npm ؛ اتساق require مقابل import ‏('type':'module') ‏(1.3)
req.body غير معرف في Express	وسيط تحليل (Parsing) غائب أو موضوع بعد المسارات	أضف app.use(express.json()) قبل المسارات ؛ تحقق من Content-Type ‏(3.1)
تكرارات أو بيانات غير متسقة في القاعدة	لا قيد ولا تحقق ؛ لا بحث قبل الإنشاء	مخطط متحقق منه (required وunique) ؛ ابحث ثم أنشئ / حدّث ؛ اربط بدل التكرار (3.3)
ثغرة محتملة : حقن / بيانات غير موثوقة	دمج مدخلات في طلب ؛ مدخلات غير متحقق منها	طلبات مُوسَطة أو ORM ؛ تحقق من المدخلات (Zod/Joi) ؛ لا تثق بالعميل أبداً (3.4/4.2)
واجهتي بطيئة تحت الحمل	طلبات غير محسنة (N+1، ولا فهرس) ؛ لا تخزين مؤقت (Cache) ؛ نواة واحدة مستعملة	حلّل (Profiler) قبل اللمس ؛ فهرس وحسّن الطلبات ؛ تخزين مؤقت (Redis) ؛ عنقدة (Clustering) ‏(PM2) ‏(5.2)
« يعمل عندي » لكن لا يعمل في الإنتاج	بيئة مختلفة (نسخة Node، وتبعيات، وإعداد)	حوّل إلى حاويات (Docker) ؛ إعداد بمتغيرات البيئة ؛ تحقق من النسخ (5.3)
سر تسرب (مفتاح/API في الشيفرة أو Git)	سر مكشوف في الشيفرة أو منسخ	أعد توليد المفتاح فوراً ؛ انقله إلى متغير بيئة (.env متجاهل من Git) ؛ لا تنسخ .env أبداً (1.4/4.2)

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

نص المخطط (SEO / قارئات الشاشة / الترجمة): منهج الدليل : 1) تسمية العرض الملاحظ (undefined، وسقوط، وتجمد، واستيراد، وbody فارغ، وتكرارات، وحقن، وبطء، وفرق الإنتاج، وسر). 2) استبقاء الأسباب المحتملة للجدول دون استنتاج وحيد. 3) تطبيق الإجراءات بالترتيب (await + try/catch، وغير المتزامن، والتحليل، والتحقق، والفهرس، وDocker، و.env). 4) استشارة السجلات والتوثيق لتجنب التكرار. الدرس : عرض يعود يستدعي منعكساً، لا إعادة تشغيل عشوائية.

نص جاهز للقول — تشخيص دون إعادة تشغيل عشوائية (30 ثانية)

« عرضي : [undefined / سقوط / تجمد / body فارغ / بطء / فرق الإنتاج]. أستشير السجلات، وأحدد السبب المحتمل للدليل، وأطبق الإجراء المستهدف وأتحقق. »

نموذج نسخ ولصق — بطاقة عطل سريعة

// بطاقة عطل : await + try/catch + وسيط الأخطاء (Middleware)
async function chargerTache(id) {
  try {
    const tache = await trouverTache(id);
    return tache;
  } catch (erreur) {
    throw new Error("Lecture impossible");
  }
}
function gestionErreurs(err, req, res, next) {
  console.error(err.message);
  res.status(500).json({ erreur: "Erreur interne" });
}
module.exports = { chargerTache, gestionErreurs };

شركة صغيرة جداً / ميزانية صغيرة

لا جدول رسمي : عرض واحد، والسبب المحتمل للدليل، والإجراء والمسؤول مدون.

شركة صغيرة ومتوسطة في الجزائر

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

عن بعد / هجين

إضافة السجلات المكتوبة الفورية إلى الإجراءات : عن بعد، عرض غير مدون يشبه نظاماً يعمل.

بين الثقافات

توضيح الملاحظات كتابة : ما يبدو بديهياً (أي نسخة، وأي بيئة) ليس كذلك للجميع.

حذر: تذكير عام : عند سر مكشوف (مفتاح مكشوف، وتسرب في Git)، أعد توليد المفتاح فوراً، وانقله إلى متغير بيئة واعرض على المرجع المعين ؛ هذا الدليل لا يقدم رأياً قانونياً.

تحدي 48 ساعة — طبّق غداً

حدد عرضاً حالياً واحداً (undefined، وتجمد، وbody فارغ، وبطء)، واملأ بطاقة العطل السريعة وجرّب الإجراء الأول (سجلات + تصحيح مستهدف).

قائمة الخروج من القسم

أعرف ربط العرض بأسبابه المحتملة.
ملأت (أو برمجت) بطاقة عطل سريعة.
أعرف الإحالة نحو المستوى المعمق لحالتي.

تقييم ذاتي 1-5 : تشخيص قبل إعادة التشغيل ؟سجلات وأسرار معالجة بشكل صحيح ؟

← السابق : حالات عملية موجهة (V3)التالي : ممارسات جيدة وفخاخ (V3) →

تحقّق من فهمك

خادم ساليم يتجمد حالما يتصل عدة مستخدمين. أي منعكس يطبق الدليل ؟

💡

نفس العرض الذي يعود ليس عشر أعطال : إنه منعكس ناقص يجب تثبيته (await + try/catch، ولا Sync أبداً في الخادم، والتحليل قبل المسارات، والتحقق، و.env).