Flutter对话框插件dlogbasic的使用

Flutter 对话框插件 dlogbasic 的使用

在 Flutter 中，dlogbasic 是一个用于日志记录的库，其设计灵感来自于 NLog。它提供了多种日志级别和配置选项，以满足不同的日志需求。

使用

该库包含了一些现成的日志记录器实现，方便开发者快速上手。以下是两个默认的日志记录器：

基本日志记录器

final ILogger logger = BasicLogger(name: 'YourLogger');
logger.info('some message'); // [09-12-2013T19:35:21+9:00] some message ||

基本日志记录器通过 ConsoleTarget 目标将日志输出到标准输出（stdout）控制台。

空日志记录器

final ILogger logger = NullLogger(name: 'YourNullLogger');
logger.info('some message'); // nothing will happen, this is a NOP

空日志记录器不会执行任何操作，相当于一个“空操作”。

日志级别

以下是一些可用的日志级别，按严重程度递增顺序排列：

• trace
• debug
• info
• warn
• error
• fatal
• off

off 是一个特殊级别，表示不应该记录任何日志。

日志记录器、目标、格式化器和接收器

层次结构

日志记录器层次结构如下所示：

                  [ Logger ]
                       |
                       |
                [ Target {1,n} ]
                       |
                       |
                   [ Sink ]

日志记录器可以有多个目标，每个目标可以有一个接收器。

日志记录器

日志记录器是一个具有不同日志级别方法的对象。例如：

logger.warn('some warning message');
logger.fatal('an exceptionally bad message');

异常和事件参数

日志记录方法可以接受可选的异常和事件参数。这些参数在打印日志时会得到特殊处理：

try {
  throw Exception("Didn't work");
} on Exception catch (e) {
   logger.error('Failed to push the thing', exception: e);
}

如果为该日志记录器配置了 ConsoleTarget（默认情况下），则标准输出将如下所示：

[9-12-203T19:54:32+9:00] [ERROR] Failed to push the thing |Exception("Didn't work")|

日志记录方法还可以接受一个 eventParameters 字段，这是一个可选的 JSON 对象，可用于传递额外的数据：

void serveFile(String path) {
    logger.info('Received request for file', eventParameters: {'path': path});
}
serveFile("addresses.txt");

再次使用 ConsoleTarget，这将打印：

[9-12-203T19:54:32+9:00] [INFO] Received request for file ||{'path': 'addresses.txt'}

启用级别

日志记录器可以选择启用或忽略某些级别的事件。可以通过特定的 getter 检查每个日志级别的状态：

logger.isTraceEnabled; // true or false

或者通过发送特定的日志级别来检查：

logLevel = LogLevel.trace;
logger.isLogLevelEnabled(logLevel); // true or false

根据使用的日志记录器实现，你可能可以在运行时更改此设置。

目标

预定义的目标

以下目标已默认包含：

• BasicConsoleTarget
• BasicFileTarget

BasicConsoleTarget 将日志事件写入 stdout，而 BasicFileTarget 在给定文件路径（存在与否均可）时会将其内容写入文件。

对于文件目标，日志轮换功能已包含在此包中。

概览

目标是写入日志文件的地点和时机。目标包含三个方法：

class ITarget {

  /// 格式化日志事件并异步写入接收器。非必需。
  ///
  /// 对于异步操作，参见 [writeAsync]
  void writeSync(LogEvent logEvent);

  /// 格式化日志事件并异步写入接收器。必需。
  ///
  /// 对于同步操作，参见 [writeSync]
  Future<void> writeAsync(LogEvent logEvent);

  /// 此日志事件是否应写入此记录器
  bool shouldWrite(LogEvent logEvent);
}

目标如何实现这些方法取决于具体实现，但请注意，目标可以根据自己的判断使用 shouldWrite() 方法忽略日志消息。

这涵盖了“何时”部分，但“何地”由 writeSync() 和 writeAsync() 方法决定。目标在构建时还会包含两个附加字段：

final IFormatter formatter;
final ISink sink;

这些字段应在写入方法中用于格式化并发送实际的位日志消息。

以下是 BasicConsoleTarget 的 writeSync 实现：

@override
void writeSync(LogEvent logEvent) {
    final msg = formatter.format(logEvent);
    sink.writeAsync(msg);
}

注意它使用 formatter 来格式化传入的日志事件，这会返回将要写入内存中的完整字符串化日志消息，然后将其发送到 sink。

接收器负责“如何”写入，格式化器负责“写什么”，目标负责协调这些事情。

格式化器

格式化器是一个属于目标的对象，确定如何从日志事件生成字符串。默认包括两种格式化器：

• BasicFormatter
• JsonFormatter
• JsonLinesFormatter

BasicFormatter 生成如下格式的字符串：

[$DateTime] [$LogLevel] [LoggerName] $message |$exception||$eventProperties|

JsonFormatter 生成如下格式的字符串：

{
  'Timestamp': number,
  'Level': string,
  'Name': string,
  'Message': string,
  'Exception': string?,
  'EventProperties': JsonObject?
}

JsonLinesFormatter 生成如下格式的字符串：

{
  'Timestamp': number,
  'Level': string,
  'Name': string,
  'Message': string,
  'Exception': string?,
  'EventProperties': JsonObject?
}

JsonLines 与 Json 的区别在于 JsonLines 使用了 JSONLines 格式，适用于流式日志数据。

接收器

接收器是实际写入日志消息的终点。这可以包括文件、标准输入/输出管道、网络连接或数据库连接。

预定义的接收器

默认包含以下接收器：

• BasicConsoleSink
• BasicFileSink

BasicConsoleSink 负责实际写入 stdout，而 BasicFileSink 负责更复杂的任务——向文件追加内容。文件接收器还具有能力，可以接受一个 FileRotation 对象，在适当的时候帮助滚动文件。

概览

接收器只有两个有趣的方法：

/// 将最终消息写入接收器。并非所有编写者都需要此操作。
/// 对于异步写入，参见 [writeAsync]
void writeSync(String formattedMessage);

/// 刷新此接收器的所有挂起更改。并非所有编写者都需要此操作。
///
/// 对于异步刷新，参见 [flushAsync]
void flushSync();

调用 writeSync 可能不会立即产生写入事件到最终位置。相反，它取决于接收器何时最适合执行这些写入。也就是说，接收器可能会在内存中批量写入，然后再发送出去。然而，如果库的调用者希望这样做，他们可以使用 flush 系列方法强制写入。

日志轮换

当使用 FileTarget 时，该包包含了一个基本的日志文件轮换系统。当然，你可以自由地在自己的日志记录器中使用这一点，但它被完全打包好以便你的方便。

class FileRotationSettings {
  /// 从初始写入开始每隔一段时间旋转日志文件
  /// 如果为 null，则不按时间旋转
  final Duration? rotateOnEvery;

  /// 当日志文件达到一定字节数时旋转日志文件
  /// 如果为 null，则不按字节大小旋转
  final int? rotateOnByteSize;

  /// 保留多少个过去的日志文件
  /// 如果为 null 或负数，则保留无限个日志文件
  /// 如果为零，则不保留任何日志文件
  final int? keepHowMany;
}