Flutter异常捕获与日志管理插件Catcher的使用

简介

Catcher 是一个Flutter插件，它可以自动捕获错误/异常并处理它们。Catcher提供了多种方式来处理错误，并支持Android、iOS、Web、Linux、Windows和MacOS平台。

安装

在pubspec.yaml中添加依赖：

dependencies:
  catcher: ^0.8.0

然后运行命令安装依赖包：

$ flutter packages get

接下来添加导入语句：

import 'package:catcher/catcher.dart';

基本示例

以下是一个基本的例子，它展示了如何使用Dialog Report Mode和Console Handler进行调试配置，以及使用Dialog Report Mode和Email Manual Handler进行发布配置。

步骤1：创建Catcher配置

CatcherOptions debugOptions = CatcherOptions(DialogReportMode(), [ConsoleHandler()]);
CatcherOptions releaseOptions = CatcherOptions(DialogReportMode(), [
  EmailManualHandler(["support@email.com"])
]);

步骤2：传递根组件和Catcher配置

Catcher(rootWidget: MyApp(), debugConfig: debugOptions, releaseConfig: releaseOptions);

步骤3：添加navigator key到MaterialApp或CupertinoApp

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Catcher.navigatorKey,
      home: Scaffold(
          appBar: AppBar(
            title: const Text('Plugin example app'),
          ),
          body: ChildWidget()),
    );
  }
}

测试代码

class ChildWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Container(
        child: TextButton(
            child: Text("Generate error"),
            onPressed: () => generateError()));
  }

  generateError() async {
    throw "Test exception";
  }
}

如果你运行这段代码，你会看到屏幕上有一个“Generate error”的按钮。点击这个按钮后，它将生成一个测试异常，该异常会被Catcher捕获。在用户确认对话框之前，Catcher不会将报告发送给处理器；一旦用户确认，报告将被发送到控制台处理器，后者会将错误信息记录到控制台。

更多功能

报告模式（Report Modes）

Catcher支持四种报告模式：

• Silent Report Mode：默认模式，不询问用户许可直接处理日志。
• Notification Report Mode：已移除，因为与Firebase不兼容。
• Dialog Report Mode：显示包含错误信息的对话框，用户可以选择接受或取消。
• Page Report Mode：显示新的页面，包含错误信息和堆栈跟踪视图。

处理器（Handlers）

Catcher支持多种处理器来处理错误报告：

• Console Handler：将日志输出到控制台。
• Email Manual Handler：允许用户手动发送电子邮件报告。
• Email Auto Handler：自动发送带有错误报告的电子邮件。
• Http Handler：将报告发送到外部服务器。
• File Handler：将日志存储在文件中。
• Toast Handler：以短消息形式展示错误信息。
• Sentry Handler：将错误发送到Sentry.io。
• Slack Handler：将消息发送到Slack工作区。
• Discord Handler：将消息发送到Discord服务器。
• Snackbar Handler：显示自定义的Snackbar消息。

其他特性

• Localization：支持多语言本地化。
• Explicit Exception Handlers Map：为特定异常设置专门的处理器。
• Explicit Exception Report Modes Map：为特定异常设置专门的报告模式。
• Error Widget：替换默认的红色死亡屏幕。
• Current Config：获取当前使用的配置。
• Update Config：运行时更新Catcher配置。
• Screenshots：自动创建并包含截图在报告中。

示例代码

以下是完整的示例代码，结合了上述所有配置：

import 'package:catcher/catcher.dart';
import 'package:flutter/material.dart';

void main() {
  final debugOptions = CatcherOptions(
    DialogReportMode(),
    [
      HttpHandler(HttpRequestType.post, Uri.parse('https://jsonplaceholder.typicode.com/posts'), printLogs: true),
      ConsoleHandler(),
    ],
  );

  final releaseOptions = CatcherOptions(
    PageReportMode(),
    [
      SentryHandler(SentryClient(SentryOptions(dsn: '<DSN>'))),
      ConsoleHandler(),
    ],
  );

  Catcher(
    runAppFunction: () {
      runApp(const MyApp());
    },
    debugConfig: debugOptions,
    releaseConfig: releaseOptions,
  );
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  State<StatefulWidget> createState() {
    return _MyAppState();
  }
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Catcher.navigatorKey,
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Catcher example'),
        ),
        body: const ChildWidget(),
      ),
    );
  }
}

class ChildWidget extends StatelessWidget {
  const ChildWidget({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return TextButton(
      onPressed: generateError,
      child: const Text('Generate error'),
    );
  }

  Future<void> generateError() async {
    Catcher.sendTestException();
  }
}

通过以上步骤，你可以在Flutter项目中集成Catcher插件，实现强大的异常捕获和日志管理功能。