Flutter日志记录插件ilogger的使用

Flutter日志记录插件ilogger的使用

简介

该插件提供了构建日志记录器的简单接口，大致模仿了NLog。

此包的目的不是成为你的日志记录解决方案。它的目的是只提供常见的接口以供代码使用。你应该能够在不同的项目之间传递ILogger对象，如果它们遵循这个接口。

ILogger接口

ILogger接口定义如下。它包含了许多默认实现：

abstract class ILogger implements ISuppress {
  /// 名称
  String get name;

  /// 是否在[LogLevel.trace]级别启用日志记录
  bool get isTraceEnabled;

  /// 是否在[LogLevel.debug]级别启用日志记录
  bool get isDebugEnabled;

  /// 是否在[LogLevel.info]级别启用日志记录
  bool get isInfoEnabled;

  /// 是否在[LogLevel.warn]级别启用日志记录
  bool get isWarnEnabled;

  /// 是否在[LogLevel.error]级别启用日志记录
  bool get isErrorEnabled;

  /// 是否在[LogLevel.fatal]级别启用日志记录
  bool get isFatalEnabled;

  /// 检查是否在此日志记录器上启用了给定的[LogLevel]
  bool isEnabled(LogLevel level);

  /// 在给定的[LogLevel]级别写入诊断消息
  void log(dynamic message, {required LogLevel level, Exception? exception, Map<String, dynamic>? eventProperties});

  /// 在[LogLevel.trace]级别写入诊断消息
  void trace(dynamic message, {Exception? exception, Map<String, dynamic>? eventProperties});

  /// 在[LogLevel.debug]级别写入诊断消息
  void debug(dynamic message, {Exception? exception, Map<String, dynamic>? eventProperties});

  /// 在[LogLevel.info]级别写入诊断消息
  void info(dynamic message, {Exception? exception, Map<String, dynamic>? eventProperties});

  /// 在[LogLevel.warn]级别写入诊断消息
  void warn(dynamic message, {Exception? exception, Map<String, dynamic>? eventProperties});

  /// 在[LogLevel.error]级别写入诊断消息
  void error(dynamic message, {Exception? exception, Map<String, dynamic>? eventProperties});

  /// 在[LogLevel.fatal]级别写入诊断消息
  void fatal(dynamic message, {Exception? exception, Map<String, dynamic>? eventProperties});

  /// 运行操作。
  ///
  /// 如果操作抛出异常，则该异常将记录为错误级别。异常不会传播到方法外部。
  [@override](/user/override)
  void swallow(Function action) {}

  /// 运行提供的函数并返回其结果。
  ///
  /// 如果抛出异常，则该异常将记录为错误级别。异常不会传播到方法外部。
  ///
  /// 返回回退值。
  [@override](/user/override)
  T? swallowResult<T>(T? Function() action, [T? fallbackValue]) {
    return null;
  }

  /// 运行异步操作。
  ///
  /// 如果操作抛出异常，则该异常将记录为错误级别。异常不会传播到方法外部。
  [@override](/user/override)
  Future<void> swallowAsync(Function action) async {
    return;
  }

  /// 运行提供的异步函数并返回其结果。
  ///
  /// 如果抛出异常，则该异常将记录为错误级别。异常不会传播到方法外部。
  ///
  /// 返回回退值。
  [@override](/user/override)
  Future<T?> swallowResultAsync<T>(Future<T?> Function() action, T? fallbackValue) async {
    return null;
  }
}

你应该始终考虑实现log方法。其他方法可以根据你的需要来实现。

使用

虽然这个包不打算作为一个实际的日志记录解决方案，但它包括两个非常简单的日志记录器实现，以便让你快速上手：

• BasicConsoleLogger
• BasicNullLogger

BasicConsoleLogger 包含大多数方法的简单实现，并将通过 print 方法将未经过滤的消息打印到控制台：

void printLog() {
    final simpleLogger = BasicConsoleLogger(name: 'mySimpleLogger');
    simpleLogger.info('A simple message'); // [2023-09-12T16:47:32+5:00] INFO A Simple message ||
}

BasicNullLogger 将丢弃所有消息且不会打印任何内容：

void printLog() {
    final simpleLogger = BasicConsoleLogger(name: 'myNullLogger');
    simpleLogger.info('A simple message'); // nothing will be printed at all, this is a NOP
}

建议你基于这些接口合同构建自己的更复杂日志记录器。对于一个稍微高级一点的例子，可以查看 DLog Basic 仓库，其中包含了一个工作版本的简化版NLog。

完整示例

以下是一个完整的示例，展示了如何使用ILogger接口创建自定义日志记录器：

import 'package:ilogger/ilogger.dart';

// 自定义日志记录器
final class SampleLogger extends ILogger {
  [@override](/user/override)
  String get name => "sample";

  [@override](/user/override)
  bool get isDebugEnabled => true;

  [@override](/user/override)
  bool get isErrorEnabled => true;

  [@override](/user/override)
  bool get isFatalEnabled => true;

  [@override](/user/override)
  bool get isInfoEnabled => true;

  [@override](/user/override)
  bool get isTraceEnabled => true;

  [@override](/user/override)
  bool get isWarnEnabled => true;

  [@override](/user/override)
  bool isEnabled(LogLevel level) => true;

  [@override](/user/override)
  void debug(message,
      {Exception? exception, Map<String, dynamic>? eventProperties}) {
    log(message,
        level: LogLevel.debug,
        exception: exception,
        eventProperties: eventProperties);
  }

  [@override](/user/override)
  void error(message,
      {Exception? exception, Map<String, dynamic>? eventProperties}) {
    log(message,
        level: LogLevel.error,
        exception: exception,
        eventProperties: eventProperties);
  }

  [@override](/user/override)
  void fatal(message,
      {Exception? exception, Map<String, dynamic>? eventProperties}) {
    log(message,
        level: LogLevel.fatal,
        exception: exception,
        eventProperties: eventProperties);
  }

  [@override](/user/override)
  void info(message,
      {Exception? exception, Map<String, dynamic>? eventProperties}) {
    log(message,
        level: LogLevel.info,
        exception: exception,
        eventProperties: eventProperties);
  }

  [@override](/user/override)
  void trace(message,
      {Exception? exception, Map<String, dynamic>? eventProperties}) {
    log(message,
        level: LogLevel.trace,
        exception: exception,
        eventProperties: eventProperties);
  }

  [@override](/user/override)
  void warn(message,
      {Exception? exception, Map<String, dynamic>? eventProperties}) {
    log(message,
        level: LogLevel.warn,
        exception: exception,
        eventProperties: eventProperties);
  }

  [@override](/user/override)
  void log(message,
      {required LogLevel level,
      Exception? exception,
      Map<String, dynamic>? eventProperties}) {
    print('${DateTime.now()} [$level] $message |$exception|$eventProperties');
  }
}

void main() {
  final ILogger logger = SampleLogger();

  logger.info('Running example from `main` at the info level');
  logger.error('Showing a sample error', exception: Exception('An error'));
  logger.trace(
    'Showing event properties at the trace level',
    eventProperties: {
      '1+1': 2,
      'dogsOrCats': 'both',
      'isItTrue': true,
      'extraArr': ['a', 'b', 'c'],
      'extraObj': {
        'fieldA': 0,
        'fieldB': 1,
      }
    },
  );
}