ابرووا
شروع رایگان
☰ فهرست مستندات · راهبردهای مدیریت خطا

بهترین روش‌های مدیریت خطا

ده راهکار برای ردیابی مؤثر خطا: initWithZone، stack trace، context، breadcrumb، تشخیص کرش و این‌که چه چیزی را گزارش کنیم.

به‌روزرسانی: ۵ آبان ۱۴۰۵

بهترین روش‌ها برای پیاده‌سازی ردیابی مؤثر خطا در اپلیکیشن شما. این ۱۰ راهکار را دنبال کنید تا بیشترین بهره را از ابرووا تریس ببرید.

۱. برای گرفتن همه‌ی خطاها از initWithZone() استفاده کنید#

همه‌ی انواع خطا را می‌گیرد، از جمله exceptionهای Dart، خطاهای async، rejectهای Future و exceptionهای پلتفرم.

✓ توصیه‌شده

dart
void main() async {
  await AbrovaTrace.initWithZone(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: 'production',
      release: '1.0.0',
      captureUncaughtErrors: true,
    ),
    () async {
      WidgetsFlutterBinding.ensureInitialized();
      runApp(MyApp());
    },
  );
}

✗ ساده (خطاهای async را از دست می‌دهد)

dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // This only catches some errors
  await AbrovaTrace.init(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: 'production',
    ),
  );
  runApp(MyApp());
}

۲. همیشه stack trace را بفرستید#

وقتی exception را دستی ثبت می‌کنید، همیشه پارامتر stack trace را بدهید؛ این context برای debug حیاتی است.

dart
try {
  await riskyOperation();
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace, // Always include this!
    message: 'Failed to complete operation',
  );
}

۳. context معنادار اضافه کنید#

با پارامتر extra داده‌های مرتبط را بفرستید تا شرایط رخ دادن خطا را بفهمید.

dart
try {
  await processPayment(orderId, amount);
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Payment processing failed',
    extra: {
      'order_id': orderId,
      'amount': amount,
      'payment_method': paymentMethod,
      'user_tier': userTier,
    },
  );
}
نکته. داده‌هایی بفرستید که به بازتولید خطا کمک کنند، اما از اطلاعات حساس مثل رمز عبور یا شماره‌ی کارت بانکی پرهیز کنید.

۴. خطاها را با breadcrumbها همراه کنید#

کارهای کاربر را تا لحظه‌ی خطا ثبت کنید تا یک خط زمانی کامل داشته باشید.

dart
// Track user actions
AbrovaTrace.addBreadcrumb(
  'User opened checkout screen',
  type: BreadcrumbType.navigation,
);

AbrovaTrace.addBreadcrumb(
  'User selected credit card payment',
  type: BreadcrumbType.user,
  data: {'payment_type': 'credit_card'},
);

try {
  await submitOrder();
} catch (e, stackTrace) {
  // Error will include all breadcrumbs above
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Order submission failed',
  );
}

۵. تشخیص کرش#

ثبت کرش نیتیو روی iOS و Android خودکار است: SDK فلاتر SDKهای نیتیو ابرووا تریس را همراه خود دارد و آن‌ها را هنگام init() / initWithZone() راه‌اندازی می‌کند. کد اضافه‌ای لازم نیست.

نحوه‌ی کار: روی iOS، کتابخانه‌ی PLCrashReporter کرش‌های signal و Mach exception را روی دیسک ذخیره می‌کند؛ روی Android، یک uncaught exception handler به‌همراه ApplicationExitInfo (API 30+) کرش‌ها و ANRها را ثبت می‌کنند. گزارش در اجرای بعدی اپ فرستاده می‌شود و به‌صورت یک مشکل نمایش داده می‌شود. دسکتاپ و وب ثبت کرش نیتیو ندارند.

برای تشخیص کرش به AbrovaTrace.close() نیازی نیست. این متد لاگ‌های در انتظار را می‌فرستد و SDK را می‌بندد، پس فقط وقتی صدایش بزنید که اپ واقعاً در حال بسته شدن است.

۶. برای هر محیط پیکربندی جداگانه داشته باشید#

dart
void main() async {
  const environment = String.fromEnvironment(
    'ENV', defaultValue: 'development',
  );

  await AbrovaTrace.initWithZone(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: environment,
      release: '1.0.0',
      captureUncaughtErrors: environment == 'production',
      enabled: environment != 'development',
    ),
    () async {
      WidgetsFlutterBinding.ensureInitialized();
      runApp(MyApp());
    },
  );
}

۷. وضعیت خطاها را در داشبورد مدیریت کنید#

  • باز: خطاهای جدیدی که باید بررسی شوند
  • در حال بررسی: خطاهایی که الان رویشان کار می‌کنید
  • حل‌شده: خطاهای رفع‌شده (اگر دوباره رخ دادند، دوباره بازشان کنید)
  • نادیده‌گرفته: مشکل‌های شناخته‌شده‌ای که تصمیم گرفته‌اید رفعشان نکنید
  • بایگانی‌شده: خطاهای قدیمی که می‌خواهید نگه دارید اما در فهرست فعال نبینید

۸. خطاهای async را درست مدیریت کنید#

dart
// Catching Future errors
Future<void> loadData() async {
  try {
    final data = await fetchFromAPI();
    processData(data);
  } catch (e, stackTrace) {
    await AbrovaTrace.captureException(
      e, stackTrace: stackTrace,
      message: 'Failed to load data',
    );
  }
}

// Handling Stream errors
void listenToStream() {
  myStream.listen(
    (data) => processData(data),
    onError: (e, stackTrace) async {
      await AbrovaTrace.captureException(
        e, stackTrace: stackTrace,
        message: 'Stream error occurred',
      );
    },
  );
}

۹. بیش از حد گزارش نکنید#

گزارش نکنید
  • خطاهای اعتبارسنجی مورد انتظار
  • لغو کردن کاربر
  • timeoutهای شبکه در حالت آفلاین
  • رد شدن مجوزها
گزارش کنید
  • exceptionهای غیرمنتظره (null reference، index out of bounds)
  • خطاهای API (خطای 500 سرور، پاسخ‌های بدشکل)
  • خراب شدن داده‌ها
  • کرش‌های نیتیو

۱۰. ردیابی خطا را تست کنید#

پیش از deploy به production، مطمئن شوید ردیابی خطا کار می‌کند (رویداد در ابرووا تریس ← مشکلات دیده می‌شود):

dart
// Add a test button in debug builds
if (kDebugMode) {
  ElevatedButton(
    onPressed: () async {
      try {
        throw Exception('Test error from debug menu');
      } catch (e, stackTrace) {
        await AbrovaTrace.captureException(
          e,
          stackTrace: stackTrace,
          message: 'Test error',
        );
      }
    },
    child: Text('Test Error Tracking'),
  );
}

SDK خطای یکسانی (با همان پیام و پلتفرم) را که ظرف یک دقیقه دوباره فرستاده شود کنار می‌گذارد، پس اگر چند بار پشت سر هم تست می‌کنید پیام را تغییر دهید.

چک‌لیست خلاصه#

  • ✓برای گرفتن همه‌ی خطاها از initWithZone() استفاده کنید
  • ✓در ثبت دستی همیشه stack trace را بفرستید
  • ✓با پارامتر extra context معنادار اضافه کنید
  • ✓خطاها را با breadcrumbها همراه کنید تا مسیر کاربر را ببینید
  • ✓روی build واقعی iOS/Android تست کنید تا کرش‌های نیتیو ثبت شوند
  • ✓برای هر محیط پیکربندی جداگانه داشته باشید
  • ✓وضعیت خطاها را در داشبورد به‌خوبی مدیریت کنید
  • ✓خطاهای async را درست مدیریت کنید
  • ✓فقط خطاهایی را گزارش کنید که قابل‌اقدام‌اند
  • ✓پیش از production ردیابی خطا را تست کنید
این صفحه مفید بود؟
گزارش مشکل