yk_log 1.0.0

YKLog

YKLog

YKLog 是一个轻量级、可扩展的 Flutter/Dart 日志代理库。它采用代理模式设计，允许开发者灵活地注入具体的日志实现（如 Console, File, Sentry, Crashlytics 等），实现日志逻辑与业务代码的解耦。

特性

• 解耦设计：核心库只定义接口，不绑定具体实现。
• 灵活扩展：通过实现 YkLogDelegate 接口，可以轻松接入任何日志后端。
• 功能丰富：支持 Tag 分类、Error 对象记录、StackTrace 堆栈信息。
• 调试控制：支持仅在调试模式下输出日志（isOnlyDebug）。

安装

在 pubspec.yaml 中添加依赖：

dependencies:
  yk_log:
    path: ./ # 如果是本地引用
    # 或者 git 引用

使用指南

1. 实现 YkLogDelegate

首先，你需要创建一个类来实现 YkLogDelegate 接口。这里以一个简单的控制台输出为例：

import 'package:flutter/foundation.dart';
import 'package:yk_log/yk_log.dart';

class ConsoleLogDelegate implements YkLogDelegate {
  @override
  Future<void> init() async {
    // 在这里进行初始化操作，例如打开文件、初始化 SDK 等
    print('ConsoleLogDelegate initialized');
  }

  @override
  void log(
    String msg, {
    bool isOnlyDebug = true,
    String? tag,
    Object? error,
    StackTrace? stackTrace,
  }) {
    // 如果设置了仅在 Debug 模式下打印，且当前是 Release 模式，则直接返回
    if (isOnlyDebug && kReleaseMode) {
      return;
    }

    final buffer = StringBuffer();
    buffer.write(DateTime.now().toString());
    buffer.write(' ');
    if (tag != null) {
      buffer.write('[$tag] ');
    }
    buffer.write(msg);

    if (error != null) {
      buffer.write('\nError: $error');
    }
    if (stackTrace != null) {
      buffer.write('\nStack: $stackTrace');
    }

    // 打印到控制台，或者可以使用 debugPrint
    print(buffer.toString());
  }
}

2. 初始化 YkLog

在 App 启动时（例如 main.dart 中），初始化 YkLog 并注入你的 Delegate：

void main() async {
  // 注入具体的日志实现
  await YkLog.init(delegate: ConsoleLogDelegate());
  
  runApp(MyApp());
}

3. 记录日志

在项目的任何地方调用 YkLog.log：

// 简单日志
YkLog.log('App started');

// 带 Tag 的日志
YkLog.log('User login success', tag: 'Auth');

// 记录错误和堆栈
try {
  throw Exception('Something went wrong');
} catch (e, s) {
  YkLog.log(
    'Operation failed',
    tag: 'Network',
    error: e,
    stackTrace: s,
    isOnlyDebug: false, // 即使在 Release 模式下也记录关键错误
  );
}

API 说明

YkLog

• static Future<void> init({required YkLogDelegate delegate}): 初始化日志库。
• static void log(String msg, {bool isOnlyDebug = true, String? tag, Object? error, StackTrace? stackTrace}): 记录日志。
• static bool get isInitialized: 检查是否已初始化。

YkLogDelegate

• Future<void> init(): 初始化回调。
• void log(...): 处理日志的具体逻辑。