Logging 包使用说明

概述

Logging 包提供了灵活的日志系统，支持多级别日志记录。默认日志级别为 Info，确保框架的关键操作都能被记录下来。

核心接口

ILogger

日志记录器接口，定义了日志记录的基本功能。

核心方法：

// 日志级别检查
bool IsTraceEnabled();
bool IsDebugEnabled();
bool IsInfoEnabled();
bool IsWarnEnabled();
bool IsErrorEnabled();
bool IsFatalEnabled();

// 记录日志
void Trace(string msg);
void Trace(string format, object arg);
void Trace(string format, object arg1, object arg2);
void Trace(string format, params object[] arguments);
void Trace(string msg, Exception t);

void Debug(string msg);
void Debug(string format, object arg);
void Debug(string format, object arg1, object arg2);
void Debug(string format, params object[] arguments);
void Debug(string msg, Exception t);

void Info(string msg);
void Info(string format, object arg);
void Info(string format, object arg1, object arg2);
void Info(string format, params object[] arguments);
void Info(string msg, Exception t);

void Warn(string msg);
void Warn(string format, object arg);
void Warn(string format, object arg1, object arg2);
void Warn(string format, params object[] arguments);
void Warn(string msg, Exception t);

void Error(string msg);
void Error(string format, object arg);
void Error(string format, object arg1, object arg2);
void Error(string format, params object[] arguments);
void Error(string msg, Exception t);

void Fatal(string msg);
void Fatal(string format, object arg);
void Fatal(string format, object arg1, object arg2);
void Fatal(string format, params object[] arguments);
void Fatal(string msg, Exception t);

// 获取日志器名称
string Name();

ILoggerFactory

日志工厂接口，用于创建日志记录器实例。

核心方法：

ILogger GetLogger(string name, LogLevel minLevel = LogLevel.Info);

ILoggerFactoryProvider

日志工厂提供程序接口，用于获取日志工厂。

核心方法：

ILoggerFactory GetLoggerFactory();
ILogger CreateLogger(string name);

LogLevel

日志级别枚举。

public enum LogLevel
{
    Trace = 0,   // 最详细的跟踪信息
    Debug = 1,   // 调试信息
    Info = 2,    // 一般信息（默认级别）
    Warning = 3, // 警告信息
    Error = 4,   // 错误信息
    Fatal = 5    // 致命错误
}

核心类

AbstractLogger

抽象日志基类，封装了日志级别判断、格式化与异常处理逻辑。平台日志器只需实现 Write 方法即可。

使用示例：

public class CustomLogger : AbstractLogger
{
    public CustomLogger(string? name = null, LogLevel minLevel = LogLevel.Info) 
        : base(name, minLevel)
    {
    }

    protected override void Write(LogLevel level, string message, Exception? exception)
    {
        // 自定义日志输出逻辑
        var logMessage = $"[{DateTime.UtcNow:yyyy-MM-dd HH:mm:ss}] [{level}] {message}";
        if (exception != null)
            logMessage += $"\n{exception}";
        
        Console.WriteLine(logMessage);
    }
}

ConsoleLogger

控制台日志记录器实现，支持彩色输出。

使用示例：

// 创建控制台日志记录器
var logger = new ConsoleLogger("MyLogger", LogLevel.Debug);

// 记录不同级别的日志
logger.Info("应用程序启动");
logger.Debug("调试信息");
logger.Warn("警告信息");
logger.Error("错误信息");
logger.Fatal("致命错误");

输出格式：

[2025-01-09 01:40:00.000] INFO     [MyLogger] 应用程序启动
[2025-01-09 01:40:01.000] DEBUG    [MyLogger] 调试信息
[2025-01-09 01:40:02.000] WARN     [MyLogger] 警告信息

日志级别颜色：

• Trace: 深灰色
• Debug: 青色
• Info: 白色
• Warning: 黄色
• Error: 红色
• Fatal: 洋红色

构造函数参数：

• name：日志器名称，默认为 "ROOT"
• minLevel：最低日志级别，默认为 LogLevel.Info
• writer：TextWriter 输出流，默认为 Console.Out
• useColors：是否使用颜色，默认为 true（仅在输出到控制台时生效）

ConsoleLoggerFactory

控制台日志工厂，用于创建控制台日志记录器实例。

使用示例：

var factory = new ConsoleLoggerFactory();
var logger = factory.GetLogger("MyModule", LogLevel.Debug);
logger.Info("日志记录器创建成功");

ConsoleLoggerFactoryProvider

控制台日志工厂提供程序实现。

使用示例：

var provider = new ConsoleLoggerFactoryProvider();
provider.MinLevel = LogLevel.Debug;  // 设置最低日志级别
var logger = provider.CreateLogger("MyApp");
logger.Info("应用程序启动");

LoggerFactoryResolver

日志工厂提供程序解析器，用于管理和提供日志工厂提供程序实例。

使用示例：

// 设置日志工厂提供程序
LoggerFactoryResolver.Provider = new ConsoleLoggerFactoryProvider();

// 设置最小日志级别
LoggerFactoryResolver.MinLevel = LogLevel.Debug;

// 获取日志记录器
var logger = LoggerFactoryResolver.Provider.CreateLogger("MyApp");
logger.Info("应用程序启动");

在架构中使用日志

1. 在 Architecture 中使用

public class GameArchitecture : Architecture
{
    protected override void Init()
    {
        var logger = LoggerFactoryResolver.Provider.CreateLogger("GameArchitecture");
        logger.Info("游戏架构初始化开始");

        RegisterModel(new PlayerModel());
        RegisterSystem(new GameSystem());

        logger.Info("游戏架构初始化完成");
    }
}

2. 在 System 中使用

public class CombatSystem : AbstractSystem
{
    protected override void OnInit()
    {
        var logger = LoggerFactoryResolver.Provider.CreateLogger("CombatSystem");
        logger.Info("战斗系统初始化完成");
    }
    
    protected override void OnDestroy()
    {
        var logger = LoggerFactoryResolver.Provider.CreateLogger("CombatSystem");
        logger.Info("战斗系统已销毁");
    }
}

3. 在 Model 中使用

public class PlayerModel : AbstractModel
{
    protected override void OnInit()
    {
        var logger = LoggerFactoryResolver.Provider.CreateLogger("PlayerModel");
        logger.Info("玩家模型初始化完成");
    }
}

4. 自定义日志级别

public class DebugLogger : AbstractLogger
{
    public DebugLogger() : base("Debug", LogLevel.Debug)
    {
    }

    protected override void Write(LogLevel level, string message, Exception? exception)
    {
        // 只输出调试及更高级别的日志
        if (level >= LogLevel.Debug)
        {
            Console.WriteLine($"[{level}] {message}");
            if (exception != null)
                Console.WriteLine(exception);
        }
    }
}

日志级别说明

级别	说明	使用场景
Trace	最详细的跟踪信息	调试复杂的执行流程，记录函数调用等
Debug	调试信息	开发阶段，记录变量值、流程分支等
Info	一般信息	记录重要的业务流程和系统状态
Warning	警告信息	可能的问题但不中断程序执行
Error	错误信息	影响功能但不致命的问题
Fatal	致命错误	导致程序无法继续运行的严重错误

最佳实践

1. 使用合适的日志级别：

   • 使用 Info 记录重要业务流程
   • 使用 Debug 记录调试信息
   • 使用 Warning 记录异常情况
   • 使用 Error 记录错误但不影响程序运行
   • 使用 Fatal 记录严重错误

2. 提供上下文信息：

   logger.Info($"用户登录成功: UserId={userId}, UserName={userName}");

3. 异常日志记录：

   try 
   {
       // 业务逻辑
   }
   catch (Exception ex)
   {
       logger.Error("数据库操作失败", ex);
   }

4. 分类使用日志：

   var dbLogger = LoggerFactoryResolver.Provider.CreateLogger("Database");
   var netLogger = LoggerFactoryResolver.Provider.CreateLogger("Network");
   
   dbLogger.Info("查询用户数据");
   netLogger.Debug("发送HTTP请求");

5. 在框架组件中合理使用日志：

   // 在系统初始化时记录
   var logger = LoggerFactoryResolver.Provider.CreateLogger("System");
   logger.Info("系统初始化完成");

注意事项

1. 日志级别检查：

   • 每个日志方法都会自动检查日志级别
   • 如果当前级别低于最小级别，不会输出日志

2. 格式化参数：

   • 支持字符串格式化参数
   • 支持异常信息传递

3. ConsoleLogger 的额外参数：

   • ConsoleLogger 现在支持自定义TextWriter输出流
   • 支持禁用颜色输出的功能（useColors参数）

相关包

• architecture - 架构核心，使用日志系统记录生命周期事件
• property - 可绑定属性基于事件系统实现
• extensions - 提供便捷的扩展方法

---

许可证: Apache 2.0