From fdaac135f985f085f0cad91562e282657906b128 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Tue, 23 Dec 2025 12:52:07 +0800
Subject: [PATCH] =?UTF-8?q?feat(logging):=20=E6=B7=BB=E5=8A=A0=E6=97=A5?=
 =?UTF-8?q?=E5=BF=97=E8=AE=B0=E5=BD=95=E7=B3=BB=E7=BB=9F=E7=9A=84=E5=9F=BA?=
 =?UTF-8?q?=E7=A1=80=E5=AE=9E=E7=8E=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 定义了ILog接口，提供日志记录和级别检查功能
- 实现了GodotLogger类，将日志输出到Godot控制台
- 创建了ILoggerFactory接口用于创建日志记录器实例
- 添加了Log静态类提供全局日志记录功能
- 定义了LogLevel枚举标识不同严重程度的日志级别
- 实现了NullLogger用于禁用日志记录功能
---
 GFramework.Core/logging/ILog.cs           | 28 ++++++++
 GFramework.Core/logging/ILoggerFactory.cs | 15 +++++
 GFramework.Core/logging/Log.cs            | 78 +++++++++++++++++++++++
 GFramework.Core/logging/LogLevel.cs       | 32 ++++++++++
 GFramework.Core/logging/NullLogger.cs     | 24 +++++++
 GFramework.Godot/logging/GodotLogger.cs   | 49 ++++++++++++++
 6 files changed, 226 insertions(+)
 create mode 100644 GFramework.Core/logging/ILog.cs
 create mode 100644 GFramework.Core/logging/ILoggerFactory.cs
 create mode 100644 GFramework.Core/logging/Log.cs
 create mode 100644 GFramework.Core/logging/LogLevel.cs
 create mode 100644 GFramework.Core/logging/NullLogger.cs
 create mode 100644 GFramework.Godot/logging/GodotLogger.cs

diff --git a/GFramework.Core/logging/ILog.cs b/GFramework.Core/logging/ILog.cs
new file mode 100644
index 0000000..0afc49d
--- /dev/null
+++ b/GFramework.Core/logging/ILog.cs
@@ -0,0 +1,28 @@
+namespace GFramework.Core.logging;
+
+/// <summary>
+/// 定义日志记录接口，提供日志记录和级别检查功能
+/// </summary>
+public interface ILog
+{
+    /// <summary>
+    /// 记录指定级别的日志消息
+    /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <param name="message">日志消息内容</param>
+    /// <param name="exception">可选的异常对象，默认为null</param>
+    /// <param name="context">可选的上下文对象，默认为null</param>
+    void Log(
+        LogLevel level,
+        string message,
+        Exception? exception = null,
+        object? context = null
+    );
+
+    /// <summary>
+    /// 检查指定日志级别是否已启用
+    /// </summary>
+    /// <param name="level">要检查的日志级别</param>
+    /// <returns>如果指定级别已启用则返回true，否则返回false</returns>
+    bool IsEnabled(LogLevel level);
+}
diff --git a/GFramework.Core/logging/ILoggerFactory.cs b/GFramework.Core/logging/ILoggerFactory.cs
new file mode 100644
index 0000000..2de452e
--- /dev/null
+++ b/GFramework.Core/logging/ILoggerFactory.cs
@@ -0,0 +1,15 @@
+namespace GFramework.Core.logging;
+
+/// <summary>
+/// 定义日志工厂接口，用于创建日志记录器实例
+/// </summary>
+public interface ILoggerFactory
+{
+    /// <summary>
+    /// 创建指定类别的日志记录器实例
+    /// </summary>
+    /// <param name="category">日志类别，用于区分不同的日志源</param>
+    /// <returns>返回指定类别的日志记录器实例</returns>
+    ILog Create(string category);
+}
+
diff --git a/GFramework.Core/logging/Log.cs b/GFramework.Core/logging/Log.cs
new file mode 100644
index 0000000..0488bab
--- /dev/null
+++ b/GFramework.Core/logging/Log.cs
@@ -0,0 +1,78 @@
+namespace GFramework.Core.logging;
+
+/// <summary>
+/// 日志记录的静态类，提供全局日志记录功能
+/// </summary>
+public static class Log
+{
+    /// <summary>
+    /// 获取或设置当前的日志记录器实例
+    /// 默认使用 NullLogger，不输出任何日志
+    /// </summary>
+    public static ILog Instance { get; private set; } = new NullLogger();
+
+    /// <summary>
+    /// 设置日志记录器实例
+    /// </summary>
+    /// <param name="logger">要设置的日志记录器，如果为 null 则使用 NullLogger</param>
+    public static void SetLogger(ILog? logger)
+    {
+        Instance = logger ?? new NullLogger();
+    }
+
+    /// <summary>
+    /// 检查指定日志级别是否启用
+    /// </summary>
+    /// <param name="level">要检查的日志级别</param>
+    /// <returns>如果指定级别已启用则返回 true，否则返回 false</returns>
+    public static bool IsEnabled(LogLevel level) => Instance.IsEnabled(level);
+
+    /// <summary>
+    /// 记录信息级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public static void Info(string msg, object? ctx = null)
+        => Instance.Log(LogLevel.Info, msg, null, ctx);
+
+    /// <summary>
+    /// 记录错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">相关异常对象（可选）</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public static void Error(string msg, Exception? ex = null, object? ctx = null)
+        => Instance.Log(LogLevel.Error, msg, ex, ctx);
+
+    /// <summary>
+    /// 记录调试级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public static void Debug(string msg, object? ctx = null)
+        => Instance.Log(LogLevel.Debug, msg, null, ctx);
+
+    /// <summary>
+    /// 记录跟踪级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public static void Trace(string msg, object? ctx = null)
+        => Instance.Log(LogLevel.Trace, msg, null, ctx);
+
+    /// <summary>
+    /// 记录警告级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public static void Warn(string msg, object? ctx = null)
+        => Instance.Log(LogLevel.Warning, msg, null, ctx);
+
+    /// <summary>
+    /// 记录致命错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public static void Fatal(string msg, object? ctx = null)
+        => Instance.Log(LogLevel.Fatal, msg, null, ctx);
+}
diff --git a/GFramework.Core/logging/LogLevel.cs b/GFramework.Core/logging/LogLevel.cs
new file mode 100644
index 0000000..a9469a6
--- /dev/null
+++ b/GFramework.Core/logging/LogLevel.cs
@@ -0,0 +1,32 @@
+namespace GFramework.Core.logging;
+
+/// <summary>
+/// 定义日志级别的枚举，用于标识不同严重程度的日志消息
+/// </summary>
+public enum LogLevel
+{
+    /// <summary>
+    /// 跟踪级别，用于详细的程序执行流程信息
+    /// </summary>
+    Trace,
+    /// <summary>
+    /// 调试级别，用于调试过程中的详细信息
+    /// </summary>
+    Debug,
+    /// <summary>
+    /// 信息级别，用于一般性的程序运行信息
+    /// </summary>
+    Info,
+    /// <summary>
+    /// 警告级别，用于表示可能的问题或异常情况
+    /// </summary>
+    Warning,
+    /// <summary>
+    /// 错误级别，用于表示错误但程序仍可继续运行的情况
+    /// </summary>
+    Error,
+    /// <summary>
+    /// 致命级别，用于表示严重的错误导致程序无法继续运行
+    /// </summary>
+    Fatal
+}
diff --git a/GFramework.Core/logging/NullLogger.cs b/GFramework.Core/logging/NullLogger.cs
new file mode 100644
index 0000000..08e33d7
--- /dev/null
+++ b/GFramework.Core/logging/NullLogger.cs
@@ -0,0 +1,24 @@
+namespace GFramework.Core.logging;
+
+/// <summary>
+/// 空日志记录器实现，用于禁用日志记录功能
+/// </summary>
+internal sealed class NullLogger : 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, object? context) { }
+
+    /// <summary>
+    /// 检查指定日志级别是否启用
+    /// </summary>
+    /// <param name="level">要检查的日志级别</param>
+    /// <returns>始终返回 false，表示所有日志级别都被禁用</returns>
+    public bool IsEnabled(LogLevel level) => false;
+}
+
diff --git a/GFramework.Godot/logging/GodotLogger.cs b/GFramework.Godot/logging/GodotLogger.cs
new file mode 100644
index 0000000..6c0503b
--- /dev/null
+++ b/GFramework.Godot/logging/GodotLogger.cs
@@ -0,0 +1,49 @@
+using GFramework.Core.logging;
+using Godot;
+
+namespace GFramework.Godot.logging;
+
+/// <summary>
+/// Godot平台的日志记录器实现
+/// </summary>
+public sealed class GodotLogger : ILog
+{
+    /// <summary>
+    /// 记录日志消息到Godot控制台
+    /// </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, object? context)
+    {
+        var prefix = $"[{level}]";
+
+        if (exception != null)
+            message += $"\n{exception}";
+
+        switch (level)
+        {
+            case LogLevel.Error:
+            case LogLevel.Fatal:
+                GD.PrintErr(prefix, message);
+                break;
+            case LogLevel.Warning:
+                GD.PushWarning($"{prefix} {message}");
+                break;
+            case LogLevel.Trace:
+            case LogLevel.Debug:
+            case LogLevel.Info:
+            default:
+                GD.Print(prefix, message);
+                break;
+        }
+    }
+
+    /// <summary>
+    /// 检查指定日志级别是否启用
+    /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <returns>始终返回 true</returns>
+    public bool IsEnabled(LogLevel level) => true;
+}