Flutter日志管理插件harmony_log的使用

Harmony Logging Mechanism

安装

在 pubspec.yaml 文件中添加以下依赖项：

dependencies:
  harmony_log: ^latest.version

然后导入 harmony_log 库：

import 'package:harmony_log/harmony_log.dart';

使用

日志系统包含两个主要部分：一个表示为 Log 类的日志记录器，以及一个表示为 LogOutput 类的输出。每个 Log 类的请求都会被转换为 LogEvent 并添加标识符和时间信息，然后重定向到指定的 LogOutput。

LogEvent 包含 message、error、stackTrace 和 level（由 LogLevel 枚举表示）以及其他一些信息，如 id（由给定的 LogId 生成）、time 和 extra。extra 是一个通用字段，类型为 Object，用于在日志事件中添加额外信息。

LogId 用于 Log 类生成每个日志事件的 ID。您可以使用 LogId 工厂，如 counter（从起始值开始计数）、constant（始终生成相同的给定 ID）和 custom（自定义逻辑生成 ID）。这些工厂可以在 Dart 文档中查看。

除了 Log 类上的通用 log 方法外，您还可以访问帮助方法 v、d、i、w、e 和 wtf，这些方法根据它们的首字母缩写添加 level。您还可以访问 Log 类上的 write 方法，这是一个低级方法，可以直接指定日志事件。LogLevel 枚举有 6 种不同的日志级别，例如 LogLevel.verbose 的重要性为 0，LogLevel.wtf 的重要性为 5。LogLevel 可以通过 compareTo 方法或比较运算符（如 >=）进行比较。

Log 类应使用 init 初始化，并使用 close 关闭。调用 init 后应立即使用。但在调用 close 后的行为是不确定的，即关闭后继续使用日志可能会实际记录事件，但不会抛出错误。关闭操作可能是异步完成的。必须在调用 init 后且在调用 close 前调用日志方法。init 和 close 命令会被重定向到 LogOutput。

Log 类通过提供 LogOutput、LogId 和 tag 来创建。tag 默认为 null。建议您为应用程序日志创建一个带有 null tag 的 Log 类，然后从您的日志记录器创建带标记的日志记录器。这样做可以使用相同的输出和 ID 生成系统，因此只需初始化一个即可，所有日志记录器都已初始化，并且对于关闭也是一样。

LogOutput 通过其工厂创建。有些输出负责将事件重定向到其他输出，如 filtered 用于过滤事件并重定向到其他输出，multi 用于输出到多个其他输出，redirect 用于根据条件将输出重定向到其他输出，redirectOnDebug 仅在调试时将输出重定向到其他输出。还有一些终端输出，如 noop 不执行任何操作。还有一个特殊的 custom 输出，可以通过提供 init、write 和 close 操作的函数来创建自定义输出。还有一个特殊的 plain 工厂，用于输出纯文本数据。还有一个 developerLog 日志输出，可以将日志输出到 dart:developer。

过滤事件是通过使用特殊的 filtered LogOutput 工厂来实现的。您应该提供一个过滤事件的目标输出和一个 LogFilter 来过滤事件。LogFilter 可以通过其工厂创建，例如 level 将允许等于或大于指定级别的事件，all 将允许所有事件，none 将不允许任何事件，debug 将仅允许调试时的事件，以及其他一些工厂可以在 Dart 文档中查看。还有一个 custom 工厂用于创建自定义过滤逻辑。所有 LogFilter 都支持标准的集合操作，如 |、&、- 和 !。

纯文本输出是您将日志输出到控制台和文件的地方。输出纯文本数据是通过使用特殊的 plain LogOutput 工厂来实现的。您应该提供一个 LogPlainFilter 和一个 LogPlainOutput。

LogPlainFilter 负责将日志事件转换为字符串行列表。它可以通过其工厂创建，如 simple 将格式化简单的单行输出，pretty 将格式化事件为类似框视图的格式，json 将格式化事件为 JSON。json 格式特别适用于输出到文件。LogPlainFilter 还会在日志输出的开头和结尾添加序列，例如在 JSON 中，我们需要 [ 和 ] 在文件的开头和结尾使其有意义。还有一个 custom 工厂可以用来实现自定义的格式化机制。

LogPlainOutput 负责输出字符串行列表。一些纯文本输出负责将事件重定向到其他纯文本输出，如 multi 用于输出到多个其他输出，redirect 用于根据条件将输出重定向到其他输出。还有一些终端输出，如 noop 不执行任何操作，console 用于使用 print 语句输出数据，file 用于将数据输出到文件中的给定目录路径。文件名基于创建时间，并带有前缀、后缀和扩展名，可以根据需要更改。文件输出不能在 Flutter Web 上使用。

注意，过滤总是会通过 init 和 close 操作。最好使用 redirect 及其方言在不同情况下完全启用/禁用日志记录。

基本示例

该示例仅在调试时记录，并使用简单格式输出到控制台：

import 'package:harmony_log/harmony_log.dart';

void main() {
  final log = Log(
    id: LogId.counter(),
    child: LogOutput.redirectOnDebug(
      child: LogOutput.plain(
        format: LogPlainFormat.simple(),
        child: LogPlainOutput.console(),
      ),
    ),
  );
  log.init();
  log.i('hello, there!');
  log.e('bad code!', error: AssertionError());
  log.close();
}

带有漂亮格式的复杂示例

该示例仅在调试时记录，并使用漂亮格式输出到控制台，同时过滤至少为 info 级别的日志，并使用计数器 ID 生成：

final log = Log(
  id: LogId.counter(),
  child: LogOutput.redirectOnDebug(
    child: LogOutput.filtered(
      filter: LogFilter.level(LogLevel.info),
      child: LogOutput.plain(
        format: LogPlainFormat.pretty(),
        child: LogPlainOutput.console(),
      ),
    ),
  ),
);

综合示例

该示例展示了在调试时仅在控制台上以漂亮格式显示至少为 debug 级别的日志，在发布时将至少为 error 级别的日志发送到服务器，并将所有日志保存到文件中：

final log = Log(
  id: LogId.counter(),
  child: LogOutput.multi(
    children: [
      LogOutput.redirectOnDebug(
        child: LogOutput.filtered(
          filter: LogFilter.level(LogLevel.debug),
          child: LogOutput.plain(
            format: LogPlainFormat.simple(),
            child: LogPlainOutput.console(),
          ),
        ),
      ),
      LogOutput.plain(
        format: LogPlainFormat.json(),
        child: LogPlainOutput.file(
          path: 'path/to/directory',
        ),
      ),
      LogOutput.redirectOnRelease(
        child: LogOutput.filtered(
          filter: LogFilter.level(LogLevel.error),
          child: LogOutput.custom(
            write: (e) {
              // 发送事件到服务器
            },
          ),
        ),
      ),
    ],
  ),
);

创建带标签的日志记录器

final log = Log(/* ... */);

final otherLog = log.tagged('OTHER');