مقدمة
بعد إكمال تثبيت NestJS، يُبلَّغ عن الاستثناءات غير المعالَجة تلقائياً. احقنLerixService للإبلاغ عن
الاستثناءات المعالَجة بنفسك مع سياق إضافي.
الالتقاط التلقائي
تسجّلLerixModule أمرين:
- مرشّح استثناءات عام. يمرّ عبره كل استثناء يُلقى من متحكم أو حارس أو
أنبوب أو معترض. يبلّغ افتراضياً عن الاستثناءات التي ليست
HttpException، وعنHttpExceptionبرمز 500 فأكثر. لا يُبلَّغ عن أخطاء العميل المتوقعة مثلNotFoundExceptionأو فشلValidationPipe. ثم يسلّم المرشّح الاستثناء إلى مرشّح Nest الافتراضي، فتبقى استجابة HTTP كما كانت ستكون بدون Lerix. - معالجات على مستوى العملية. يُبلَّغ عن
uncaughtExceptionوunhandledRejection، ويُمنح التقرير مهلةflushTimeoutMsللإرسال، ثم تخرج العملية برمز 1 كما يفعل Node. اضبطexitOnUnhandled: falseلإبقاء العملية حية، أوcaptureUnhandled: falseلتخطي المعالجات.
x-request-id (أو x-correlation-id) إن وُجدت، تحت metadata.request.
تغيير ما يُبلَّغ عنه
تتلقىshouldCapture الاستثناء وكائن سياق يحوي تفاصيل الطلب:
app.module.ts
استخدام مرشّحك الخاص
إن كان تطبيقك يسجّل بالفعلAPP_FILTER شاملاً، فاضبط
captureHttpExceptions: false وأبلغ من ذلك المرشّح:
all-exceptions.filter.ts
LerixExceptionFilter وتجاوز catch لتخصيص الاستجابة مع
الإبقاء على الإبلاغ.
ترشيح الأخطاء
يتطلّب@lerix-dev/lerix-nestjs بالإصدار 1.4.0 أو أحدث.
يحدّد خياران ما يغادر العملية (process). ينطبقان على كل تقرير أياً كان
مصدره: المرشّح العام، والاستثناءات غير الملتقطة والوعود المرفوضة غير
المعالَجة، وcaptureException / captureMessage. استخدمهما للترشيح حسب
الرسالة، واستخدم shouldCapture (أعلاه) للقرار حسب الاستثناء أو الطلب.
app.module.ts
- تعمل
ignoreErrorsأولاً، ثم لا ترىbeforeSendإلا ما تبقّى. - الرسالة التي تُطابَق وتُمرَّر إلى
beforeSendهي عنوان المشكلة المعروض في لوحة التحكم، مثلTypeError: Cannot read properties of undefined. - يحتوي الحدث على
messageوstack(أسطرat ...) وtype(BugType) وseverity(BugSeverity) وmetadata(ما مرّرته إلى دالة الالتقاط، أو سياق الطلب من المرشّح). تُضاف تفاصيل الجهاز والتطبيق وبيئة التشغيل بعد الدالة. - إذا رمت
beforeSendاستثناءً، يُرسَل الحدث الأصلي ويُسجَّل الخطأ فقط، ولا يُبلَّغ عنه ولا يُعاد رميه أبداً. - التقرير المحذوف لا يثبّت (pin) تتبّع الطلب الخاص به.
HttpException التي تقل عن 500 تُتجاوَز أصلاً عبر
shouldCapture الافتراضية.
كما يجمّع Lerix الأخطاء المتكرّرة في مشكلة واحدة ويرشّح الضوضاء الشائعة على
الخادم، لكل إصدارات الـ SDK. راجع
كيف تُجمَّع الأخطاء في مشكلات.
الإبلاغ عن خطأ يدوياً
orders.service.ts
captureException استثناءً أبداً وتكتمل عند قبول التقرير أو التخلي
عنه. استخدم captureMessage لشيء لم يُلقَ كاستثناء:
المعاملات
قيم BugType
قيم BugSeverity
ما يُرفق بالتقرير
ملفات TypeScript وأرقام الأسطر
تُعاد تتبّعات المكدس (stack traces) إلى كود TypeScript المصدري تلقائياً. عند الإبلاغ عن خطأ، يقرأ الـ SDK ملفات.js.map التي يكتبها nest build بجانب
الكود المُترجَم، فيُبلَّغ عن إطار مثل dist/src/orders/orders.service.js:58
على أنه src/orders/orders.service.ts:42.
لا شيء لرفعه، ولا خيار (flag) لـ Node.js، ولا شيء لإعداده. يفعّل Nest الخيار
"sourceMap": true في tsconfig.json افتراضياً. تعمل أيضاً خرائط المصدر
المضمّنة (inline) وحزم nest build --webpack.
تُجعل المسارات نسبية إلى مجلد العمل (working directory) للتطبيق (وهو عادةً جذر
المستودع)، فتُقرأ كمسارات داخل المستودع. تظهر إطارات الاعتماديات
(dependencies) بصيغة node_modules/....
دوال LerixService الأخرى
التعطيل في الاختبارات
مرّرenabled: false لتحويل كل استدعاء إلى لا شيء دون تغيير الكود: