Flutter上下文日志记录插件contextual_logging的使用

Flutter上下文日志记录插件contextual_logging的使用

我们都有过打印日志的经历。这些日志通常会打印到控制台或文件中。Dart 提供了一些方法来帮助我们记录信息，比如：

print('A message');
debugPrint('Another message');

这些方法在调试时非常有用。但是，当你需要追踪用户的行为时，仅仅打印信息可能不够。这时就需要添加上下文信息。上下文信息可以帮助我们了解是谁打印了这条信息。

什么是上下文日志记录？

上下文日志记录能够为每条日志消息添加额外的信息，以便更好地理解日志的来源。例如，你可以在每次打印日志时都手动添加上下文信息：

print('My Controller : A message');
debugPrint('My Controller : Another message');

虽然这种方法可行，但每次都写上下文信息可能会很繁琐。这就是 contextual_logging 插件要解决的问题。

日志记录器

混入类

你可以将 ContextualLogging 混入到你的类中，以启用上下文日志记录功能：

class MyController with ContextualLogging {
  Future<void> init() async {
    log.i('Initializing ...'); // 使用 log 字段访问日志功能
    await fetchData();
    log.i('Initialized!');
  }
}

这样，你就可以在控制台看到类似这样的输出：

10:03:00 [I] MyController : Initializing ...
10:03:01 [I] MyController : Initialized!

配置

默认情况下，每个带有 ContextualLogging 混入的类都会创建一个日志记录器。一旦你添加了混入，你就可以配置这个日志记录器。

上下文

logContext 属性用于在日志消息前添加上下文信息。默认情况下，它取值为 this.toString()。你可以覆盖这个属性以自定义上下文信息：

class MyController with ContextualLogging {
  @override
  String get logContext => 'SomeOtherContext';
  
  void test() {
    log.i('Test'); // 19:12:00 [I] SomeOtherContext : Test
  }
}

自定义日志记录器

如果你想要使用自定义的日志记录器，可以覆盖 customLogger 属性：

class MyController with ContextualLogging {
  @override
  Logger get customLogger => Logger(/* 配置日志记录器 */);
  
  void test() {
    log.i('Test'); // 仍然通过 `log` 属性访问
  }
}

默认日志配置

如果你想一次性更改所有对象的日志配置，可以在应用程序启动之前进行如下操作：

// ContextualLogger 混入默认使用这个默认日志记录器来获取附加了混入的对象的日志记录器。
ContextualLoggingConfig.defaultLogger = (forObject) => MyBeautifulLogger(forObject);

这样，所有带有 ContextualLogger 混入的对象都将使用这个新的配置。

上下文日志打印机

这是什么？

当你设置 ContextualLoggingConfig.defaultLogger 属性时，你可以创建一个日志记录器并提供任何你需要的日志打印机。或者你可以使用 ContextualLogger 默认使用的打印机 ContextualLogPrinter。这个打印机使日志消息看起来像这样：

12:01:00 [I] SomeOtherContext : Test

而不是这样：

Test

配置打印机

有很多属性可以修改：

示例

假设你已经覆盖了打印机：

ContextualLoggingConfig.defaultLogger = (forObject) {
  return Logger(
    printer: ContextualLogPrinter(
      forObject: forObject,
      printTime: false, // 注意！
    ),
  );
};

// 这将使你的消息看起来像这样：

[I] MyController : A message

日志级别标签

日志级别标签允许你区分不同级别的日志消息。logger 包提供了以下级别：

你可以覆盖 logLevelLabel 属性来自定义前缀：

ContextualLoggingConfig.defaultLogger = (forObject) {
  return Logger(
    printer: ContextualLogPrinter(
      forObject: forObject,
      logLevelLabel: (level) {
        /* 返回给定级别的前缀 */
      },
    ),
  );
  
// 或者这样做以启用表情符号级别的功能！
ContextualLoggingConfig.defaultLogger = (forObject) {
  return Logger(
    printer: ContextualLogPrinter(
      forObject: forObject,
      logLevelLabel: ContextualLogPrinter.emojiLevelLabel,
    ),
  );

完整示例

下面是一个完整的示例，展示了如何使用 contextual_logging 插件：

import 'package:contextual_logging/src/contextual_logger.dart';

Future<void> main() async {
  final weatherController = WeatherController();
  final cityController = CityController();

  await weatherController.initialize();
  await cityController.initialize();
}

class WeatherController with ContextualLogger {
  Future<void> initialize() async {
    try {
      log.i('Initializing ...');
      await fetchSomeData();
      log.i('Initialized successfully!');
    } on Exception catch (e, s) {
      log.e('Failed to initialize', e, s);
    }
  }
}

class CityController with ContextualLogger {
  Future<void> initialize() async {
    try {
      log.i('Initializing ...');
      await fetchSomeData();
      log.i('Initialized successfully!');
    } on Exception catch (e, s) {
      log.e('Failed to initialize', e, s);
    }
  }
}

Future<void> fetchSomeData() {
  return Future.value();
}