Flutter — تتبع الأخطاء

مقدمة

يلتقط Lerix الأخطاء والاستثناءات من تطبيق Flutter الخاص بك لتتمكّن من تصحيح المشاكل بشكل أسرع. بعد إتمام تثبيت Flutter، استخدم Lerix.throwError لإرسال أخطاء مخصّصة أو استثناءات ملتقطة إلى لوحة التحكم.

تأكّد من تهيئة الـ SDK عبر Lerix.init() قبل الإبلاغ عن الأخطاء.

الإبلاغ عن خطأ

استخدم Lerix.throwError للإبلاغ عن خطأ يدوياً. هذا مفيد عندما تلتقط استثناءً داخل try/catch وتريد إرساله إلى Lerix مع سياق إضافي.

main.dart

try {
  await riskyOperation();
} catch (e, stack) {
  await Lerix.throwError(
    e,
    stack,
    bugSeverity: BugSeverity.high,
    metaData: {
      'userId': '123',
      'action': 'payment',
      'amount': 100.0,
    },
  );
}

المعاملات (Parameters)

المعامل	النوع	مطلوب	الوصف
`error`	`Object`	نعم	كائن الخطأ أو نص الرسالة
`stack`	`StackTrace`	نعم	تتبّع المكدس (Stack trace) المرتبط بالخطأ
`bugType`	`BugType`	لا	تصنيف نوع الخطأ
`bugSeverity`	`BugSeverity`	لا	مستوى الخطورة
`metaData`	`Map<String, dynamic>`	لا	سياق إضافي يُرفق بالتقرير

قيم `BugType`

القيمة	الوصف
`runtimeError`	استثناء غير معالَج يُرمى أثناء التشغيل
`logicBug`	سلوك غير صحيح لا يرمي استثناءً
`uiBug`	خلل بصري أو في التخطيط (layout)
`networkError`	طلب شبكة فاشل أو مُشوَّه
`performance`	بطء، تقطّع (jank)، أو استهلاك موارد مفرط
`compatibility`	خلل يظهر على جهاز أو إصدار نظام أو منصة محدّدة
`validationError`	إدخال غير صالح تجاوز التحقق رغم أنه لا ينبغي
`security`	خلل متعلّق بالأمان
`crash`	توقّف التطبيق بشكل غير متوقّع
`unknown`	لا شيء مما سبق

قيم `BugSeverity`

القيمة	الوصف
`critical`	يعطّل وظيفة أساسية أو يؤثّر على جميع المستخدمين
`high`	تأثير كبير، لكن يوجد حل بديل (workaround)
`medium`	ملحوظ لكن تأثيره محدود
`low`	بسيط أو شكلي
`unknown`	لم يتم تقييم الخطورة بعد

الالتقاط التلقائي للأخطاء

بمجرد تشغيل Lerix.init()، يتم التقاط أخطاء إطار عمل Flutter غير الملتقطة (عبر FlutterError.onError) وأخطاء Dart غير الملتقطة (عبر PlatformDispatcher.instance.onError) وإرسالها تلقائياً — لا حاجة لتغليف تطبيقك بالكامل داخل try/catch للحصول على تغطية أساسية. Lerix.throwError مخصّص للحالات التي تلتقطها بنفسك وتريد إضافة تصنيف أو بيانات وصفية (metadata) لها. يُبلَغ عن الأخطاء غير الملتقطة كأعطال حرجة (critical crashes) على جميع المنصات، بما فيها Flutter Web.

بناءات Flutter Web للإصدار مُصغَّرة (minified). لرؤية ملف Dart ورقم السطر لأخطاء الويب، ارفع خرائط المصدر كما هو موضّح في خرائط المصدر في Flutter. أما بناءات الإصدار على Android وiOS فتُبلغ عنهما دون أي إعداد.

تحقّق من التكامل

أرسل خطأً تجريبياً للتأكّد من أن كل شيء يعمل:

main.dart

await Lerix.throwError(
  Exception('Test error'),
  StackTrace.current,
);

ثم افتح لوحة التحكم — يجب أن يظهر الخطأ خلال ثوانٍ.

ترشيح الأخطاء

يتطلّب lerix_flutter بالإصدار 0.3.0 أو أحدث. يحدّد خياران اختياريان في Lerix.init الأخطاء التي تُرسَل. ينطبقان على كل تقرير: أخطاء Flutter وDart والـ zone غير الملتقطة، وLerix.throwError، والويب.

Lerix.init(
  // ...
  ignoreErrors: [
    'SocketException', // case-insensitive substring
    RegExp(r'^HttpException: 40[13]'), // RegExp, matched with hasMatch
  ],
  beforeSend: (event) {
    if (event.metadata?['test'] == true) return null; // drop it
    return event.copyWith(
      message: event.message.replaceAll(RegExp(r'token=\S+'), 'token=***'),
    );
  },
  builder: () => runApp(const MyApp()),
);

تعمل ignoreErrors (List<Pattern>) أولاً. النص (String) يحذف أي خطأ تحتوي رسالته عليه، دون تمييز حالة الأحرف، وتُتجاوَز النصوص الفارغة أو التي تحتوي مسافات فقط. والتعبير RegExp يحذف أي خطأ تطابقه رسالته.
ثم تستقبل beforeSend كائن LerixErrorEvent (message، stack، type، severity، metadata). أعِده لإرساله، أو أعِد نسخة معدّلة عبر copyWith، أو أعِد null لحذفه. إذا رمت beforeSend استثناءً، يُرسَل التقرير الأصلي ولا يُعاد رمي الاستثناء داخل تطبيقك أبداً.
التقرير المحذوف لا يُرسَل ولا يستدعي onError.
الرسالة التي تطابقها هي عنوان المشكلة، وتتضمّن صنف الخطأ.

كما يجمّع Lerix الأخطاء المتكرّرة في مشكلة واحدة ويرشّح الضوضاء الشائعة على الخادم، لكل إصدارات الـ SDK. راجع كيف تُجمَّع الأخطاء في مشكلات.

البدء

أطر العمل

الوحدات

المطورون

Flutter — تتبع الأخطاء

مقدمة

الإبلاغ عن خطأ

المعاملات (Parameters)

قيم `BugType`

قيم `BugSeverity`

الالتقاط التلقائي للأخطاء

تحقّق من التكامل

ترشيح الأخطاء

​مقدمة

​الإبلاغ عن خطأ

​المعاملات (Parameters)

​قيم BugType

​قيم BugSeverity

​الالتقاط التلقائي للأخطاء

​تحقّق من التكامل

​ترشيح الأخطاء

مقدمة

الإبلاغ عن خطأ

المعاملات (Parameters)

قيم `BugType`

قيم `BugSeverity`

الالتقاط التلقائي للأخطاء

تحقّق من التكامل

ترشيح الأخطاء