From 0980fd48b5cda9cf50500b76a614240aba3db854 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Tue, 23 Dec 2025 13:23:42 +0800
Subject: [PATCH] =?UTF-8?q?refactor(logging):=20=E5=AE=8C=E5=96=84?=
 =?UTF-8?q?=E6=97=A5=E5=BF=97=E7=B3=BB=E7=BB=9F=E5=AE=9E=E7=8E=B0=E5=92=8C?=
 =?UTF-8?q?API=E8=AE=BE=E8=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 为ConsoleLogger添加完整的XML文档注释
- 实现GodotLogger中缺失的日志级别方法
- 统一Fatal方法签名，支持异常参数传递
- 为NullLogger添加完整的方法注释
- 修复LoggerFactory中的文件路径处理逻辑
- 移除日志示例中对架构阶段的直接访问
- 添加全局日志记录器创建功能
---
 GFramework.Core/logging/ConsoleLogger.cs  | 67 ++++++++++++++++++++---
 GFramework.Core/logging/ILog.cs           |  3 +-
 GFramework.Core/logging/ILoggerFactory.cs |  6 ++
 GFramework.Core/logging/LoggerFactory.cs  | 15 ++---
 GFramework.Core/logging/LoggingExample.cs |  3 +-
 GFramework.Core/logging/NullLogger.cs     | 40 +++++++++++++-
 GFramework.Godot/logging/GodotLogger.cs   | 14 ++---
 7 files changed, 119 insertions(+), 29 deletions(-)

diff --git a/GFramework.Core/logging/ConsoleLogger.cs b/GFramework.Core/logging/ConsoleLogger.cs
index 1b8f5e9..fdd74b8 100644
--- a/GFramework.Core/logging/ConsoleLogger.cs
+++ b/GFramework.Core/logging/ConsoleLogger.cs
@@ -1,6 +1,3 @@
-using System;
-using System.IO;
-
 namespace GFramework.Core.logging;
 
 /// <summary>
@@ -35,6 +32,10 @@ public sealed class ConsoleLogger : ILog
     /// <summary>
     /// 记录日志消息
     /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <param name="message">日志消息</param>
+    /// <param name="exception">异常信息（可选）</param>
+    /// <param name="context">上下文信息（可选）</param>
     public void Log(LogLevel level, string message, Exception? exception = null, object? context = null)
     {
         if (!IsEnabled(level))
@@ -61,6 +62,8 @@ public sealed class ConsoleLogger : ILog
     /// <summary>
     /// 检查指定日志级别是否启用
     /// </summary>
+    /// <param name="level">要检查的日志级别</param>
+    /// <returns>如果启用则返回true，否则返回false</returns>
     public bool IsEnabled(LogLevel level) => level >= _minLevel;
 
     /// <summary>
@@ -68,6 +71,11 @@ public sealed class ConsoleLogger : ILog
     /// </summary>
     public LogLevel MinLevel => _minLevel;
 
+    /// <summary>
+    /// 使用颜色写入日志消息
+    /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <param name="message">要写入的消息</param>
     private void WriteColored(LogLevel level, string message)
     {
         var originalColor = Console.ForegroundColor;
@@ -82,7 +90,12 @@ public sealed class ConsoleLogger : ILog
         }
     }
 
-    private ConsoleColor GetColor(LogLevel level)
+    /// <summary>
+    /// 根据日志级别获取对应的颜色
+    /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <returns>对应的控制台颜色</returns>
+    private static ConsoleColor GetColor(LogLevel level)
     {
         return level switch
         {
@@ -96,7 +109,12 @@ public sealed class ConsoleLogger : ILog
         };
     }
 
-    private string FormatContext(object context)
+    /// <summary>
+    /// 格式化上下文对象为字符串
+    /// </summary>
+    /// <param name="context">上下文对象</param>
+    /// <returns>格式化后的字符串</returns>
+    private static string FormatContext(object context)
     {
         return context switch
         {
@@ -108,21 +126,54 @@ public sealed class ConsoleLogger : ILog
     }
 
     // 快捷方法实现
+
+    /// <summary>
+    /// 记录信息级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Info(string msg, object? ctx = null)
         => Log(LogLevel.Info, msg, null, ctx);
 
+    /// <summary>
+    /// 记录错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">异常信息（可选）</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Error(string msg, Exception? ex = null, object? ctx = null)
         => Log(LogLevel.Error, msg, ex, ctx);
 
+    /// <summary>
+    /// 记录调试级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Debug(string msg, object? ctx = null)
         => Log(LogLevel.Debug, msg, null, ctx);
 
+    /// <summary>
+    /// 记录跟踪级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Trace(string msg, object? ctx = null)
         => Log(LogLevel.Trace, msg, null, ctx);
 
+    /// <summary>
+    /// 记录警告级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Warn(string msg, object? ctx = null)
         => Log(LogLevel.Warning, msg, null, ctx);
 
-    public void Fatal(string msg, object? ctx = null)
-        => Log(LogLevel.Fatal, msg, null, ctx);
-}
\ No newline at end of file
+    /// <summary>
+    /// 记录致命错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">异常信息（可选）</param>
+    /// <param name="ctx">上下文信息（可选）</param>
+    public void Fatal(string msg,Exception? ex = null, object? ctx = null)
+        => Log(LogLevel.Fatal, msg, ex, ctx);
+}
diff --git a/GFramework.Core/logging/ILog.cs b/GFramework.Core/logging/ILog.cs
index aa37db3..a4037a2 100644
--- a/GFramework.Core/logging/ILog.cs
+++ b/GFramework.Core/logging/ILog.cs
@@ -66,6 +66,7 @@ public interface ILog
     /// 记录致命错误级别日志
     /// </summary>
     /// <param name="msg">日志消息</param>
+    /// <param name="ex">相关异常对象（可选）</param>
     /// <param name="ctx">日志上下文信息（可选）</param>
-    void Fatal(string msg, object? ctx = null);
+    void Fatal(string msg, Exception? ex = null,object? ctx = null);
 }
diff --git a/GFramework.Core/logging/ILoggerFactory.cs b/GFramework.Core/logging/ILoggerFactory.cs
index 2de452e..d118eba 100644
--- a/GFramework.Core/logging/ILoggerFactory.cs
+++ b/GFramework.Core/logging/ILoggerFactory.cs
@@ -11,5 +11,11 @@ public interface ILoggerFactory
     /// <param name="category">日志类别，用于区分不同的日志源</param>
     /// <returns>返回指定类别的日志记录器实例</returns>
     ILog Create(string category);
+    
+    /// <summary>
+    /// 创建全局日志记录器实例
+    /// </summary>
+    /// <returns>返回全局日志记录器实例</returns>
+    ILog CreateGlobalLogger();
 }
 
diff --git a/GFramework.Core/logging/LoggerFactory.cs b/GFramework.Core/logging/LoggerFactory.cs
index 6837327..685e759 100644
--- a/GFramework.Core/logging/LoggerFactory.cs
+++ b/GFramework.Core/logging/LoggerFactory.cs
@@ -1,6 +1,3 @@
-using System;
-using System.Collections.Generic;
-
 namespace GFramework.Core.logging;
 
 /// <summary>
@@ -65,13 +62,13 @@ public class LoggerFactory : ILoggerFactory
         try
         {
             var level = _config.GetCategoryLevel(category);
-            var directory = System.IO.Path.GetDirectoryName(_config.LogFilePath);
-            if (!string.IsNullOrEmpty(directory) && !System.IO.Directory.Exists(directory))
+            var directory = Path.GetDirectoryName(_config.LogFilePath);
+            if (!string.IsNullOrEmpty(directory) && !Directory.Exists(directory))
             {
-                System.IO.Directory.CreateDirectory(directory);
+                Directory.CreateDirectory(directory);
             }
 
-            var writer = new System.IO.StreamWriter(_config.LogFilePath!, append: true);
+            var writer = new StreamWriter(_config.LogFilePath!, append: true);
             return new ConsoleLogger(category, level, writer, useColors: false);
         }
         catch
@@ -125,7 +122,7 @@ public class LoggerFactory : ILoggerFactory
         public void Warn(string msg, object? ctx = null)
             => Log(LogLevel.Warning, msg, null, ctx);
 
-        public void Fatal(string msg, object? ctx = null)
-            => Log(LogLevel.Fatal, msg, null, ctx);
+        public void Fatal(string msg,Exception? ex = null, object? ctx = null)
+            => Log(LogLevel.Fatal, msg, ex, ctx);
     }
 }
\ No newline at end of file
diff --git a/GFramework.Core/logging/LoggingExample.cs b/GFramework.Core/logging/LoggingExample.cs
index 8ce9448..7485fe1 100644
--- a/GFramework.Core/logging/LoggingExample.cs
+++ b/GFramework.Core/logging/LoggingExample.cs
@@ -3,6 +3,7 @@ using GFramework.Core.logging;
 using GFramework.Core.system;
 using GFramework.Core.model;
 using GFramework.Core.events;
+using GFramework.Core.utility;
 
 namespace GFramework.Core.Examples;
 
@@ -100,8 +101,6 @@ public class LoggingExample
         // 创建示例架构
         var architecture = ExampleArchitecture.Instance;
         
-        Console.WriteLine($"架构当前阶段: {architecture.CurrentPhase}");
-        
         // 注册组件（会自动记录日志）
         architecture.RegisterSystem(new ExampleSystem());
         architecture.RegisterModel(new ExampleModel());
diff --git a/GFramework.Core/logging/NullLogger.cs b/GFramework.Core/logging/NullLogger.cs
index d06cb50..d57ad69 100644
--- a/GFramework.Core/logging/NullLogger.cs
+++ b/GFramework.Core/logging/NullLogger.cs
@@ -21,11 +21,47 @@ internal sealed class NullLogger : ILog
     /// <returns>始终返回 false，表示所有日志级别都被禁用</returns>
     public bool IsEnabled(LogLevel level) => false;
 
-    // 快捷方法实现（空实现）
+    /// <summary>
+    /// 记录信息级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Info(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">相关异常对象（可选）</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Error(string msg, Exception? ex = null, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录调试级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Debug(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录跟踪级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Trace(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录警告级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Warn(string msg, object? ctx = null) { }
-    public void Fatal(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录致命错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">相关异常对象（可选）</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public void Fatal(string msg,Exception? ex = null, object? ctx = null) { }
 }
diff --git a/GFramework.Godot/logging/GodotLogger.cs b/GFramework.Godot/logging/GodotLogger.cs
index 138925e..ed1901c 100644
--- a/GFramework.Godot/logging/GodotLogger.cs
+++ b/GFramework.Godot/logging/GodotLogger.cs
@@ -49,31 +49,31 @@ public sealed class GodotLogger : ILog
 
     public void Info(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Info, msg, null, ctx);
     }
 
     public void Error(string msg, Exception? ex = null, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Error, msg, ex, ctx);
     }
 
     public void Debug(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Debug, msg, null, ctx);
     }
 
     public void Trace(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Trace, msg, null, ctx);
     }
 
     public void Warn(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Warning, msg, null, ctx);
     }
 
-    public void Fatal(string msg, object? ctx = null)
+    public void Fatal(string msg,Exception? ex = null, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Fatal, msg, ex, ctx);
     }
 }