From 64543be0b5440de31006d58eefb0878dc480a691 Mon Sep 17 00:00:00 2001 From: GeWuYou <95328647+GeWuYou@users.noreply.github.com> Date: Tue, 23 Dec 2025 13:35:51 +0800 Subject: [PATCH] =?UTF-8?q?docs(logging):=20=E6=9B=B4=E6=96=B0=E6=97=A5?= =?UTF-8?q?=E5=BF=97=E7=B3=BB=E7=BB=9F=E6=96=87=E6=A1=A3=E5=B9=B6=E7=A7=BB?= =?UTF-8?q?=E9=99=A4=E7=A4=BA=E4=BE=8B=E4=BB=A3=E7=A0=81=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在README.md中添加基本使用示例和详细使用示例 - 添加框架组件日志使用示例代码 - 添加高级配置和异常日志记录示例 - 添加生产环境配置示例 - 添加框架组件中日志使用最佳实践 - 移除LoggingExample.cs示例文件 - 更新日志级别说明和配置建议 --- GFramework.Core/logging/LoggingExample.cs | 262 ---------------------- GFramework.Core/logging/README.md | 160 ++++++++++++- 2 files changed, 157 insertions(+), 265 deletions(-) delete mode 100644 GFramework.Core/logging/LoggingExample.cs diff --git a/GFramework.Core/logging/LoggingExample.cs b/GFramework.Core/logging/LoggingExample.cs deleted file mode 100644 index 7485fe1..0000000 --- a/GFramework.Core/logging/LoggingExample.cs +++ /dev/null @@ -1,262 +0,0 @@ -using GFramework.Core.architecture; -using GFramework.Core.logging; -using GFramework.Core.system; -using GFramework.Core.model; -using GFramework.Core.events; -using GFramework.Core.utility; - -namespace GFramework.Core.Examples; - -/// -/// 日志系统使用示例 -/// 演示如何在实际项目中使用GFramework.Core的日志功能 -/// -public class LoggingExample -{ - /// - /// 演示基本的日志配置和使用 - /// - public static void DemonstrateBasicUsage() - { - Console.WriteLine("=== 基本日志使用示例 ==="); - - // 1. 快速配置日志系统（默认Info级别） - Log.Configure( - minLevel: LogLevel.Info, - enableConsole: true, - useColors: true - ); - - // 2. 使用全局日志 - Log.Info("应用程序启动"); - Log.Warn("这是一个警告"); - Log.Error("这是一个错误信息"); - - // 3. 创建特定类别的日志记录器 - var userLogger = Log.CreateLogger("UserService"); - userLogger.Info("用户服务初始化完成", new { ServiceVersion = "1.0" }); - - var dbLogger = Log.CreateLogger("Database"); - dbLogger.Debug("连接数据库", new { Server = "localhost", Database = "MyApp" }); - dbLogger.Info("数据库连接成功"); - - Console.WriteLine(); - } - - /// - /// 演示高级日志配置 - /// - public static void DemonstrateAdvancedConfiguration() - { - Console.WriteLine("=== 高级日志配置示例 ==="); - - // 创建详细的日志配置 - var config = new LogConfig - { - DefaultMinLevel = LogLevel.Info, - EnableConsole = true, - UseColors = true, - EnableFile = true, - LogFilePath = "logs/example-{yyyy-MM-dd}.log" - }; - - // 为不同模块设置不同的日志级别 - config.SetCategoryLevel("Architecture", LogLevel.Info); - config.SetCategoryLevel("IOC", LogLevel.Debug); - config.SetCategoryLevel("Event", LogLevel.Info); - config.SetCategoryLevel("UserService", LogLevel.Debug); - config.SetCategoryLevel("Database", LogLevel.Debug); - config.SetCategoryLevel("Network", LogLevel.Trace); // 最详细的网络日志 - - // 初始化日志系统 - Log.Initialize(config); - - // 演示不同级别的日志记录 - var networkLogger = Log.CreateLogger("Network"); - networkLogger.Trace("网络请求开始", new { Url = "https://api.example.com/users", Method = "GET" }); - networkLogger.Debug("添加请求头", new { Headers = new[] { "Authorization: Bearer xxx", "Content-Type: application/json" } }); - networkLogger.Info("网络请求完成", new { StatusCode = 200, ResponseTime = "120ms" }); - - var userServiceLogger = Log.CreateLogger("UserService"); - userServiceLogger.Debug("查询用户信息", new { UserId = 123 }); - userServiceLogger.Info("用户登录成功", new { UserId = 123, UserName = "张三", LoginTime = DateTime.Now }); - - Console.WriteLine(); - } - - /// - /// 演示在框架组件中使用日志 - /// - public static void DemonstrateFrameworkLogging() - { - Console.WriteLine("=== 框架组件日志示例 ==="); - - // 配置日志系统 - Log.Configure( - minLevel: LogLevel.Info, - enableConsole: true, - useColors: true - ); - - // 创建示例架构 - var architecture = ExampleArchitecture.Instance; - - // 注册组件（会自动记录日志） - architecture.RegisterSystem(new ExampleSystem()); - architecture.RegisterModel(new ExampleModel()); - architecture.RegisterUtility(new ExampleUtility()); - - // 发送事件（会自动记录日志） - architecture.SendEvent(new ExampleEvent { Message = "框架日志示例事件" }); - - // 注册事件监听器（会自动记录日志） - architecture.RegisterEvent(evt => - { - Log.CreateLogger("EventListener").Info($"收到事件: {evt.Message}"); - }); - - // 再次发送事件 - architecture.SendEvent(new ExampleEvent { Message = "框架日志示例事件2" }); - - Console.WriteLine(); - } - - /// - /// 演示异常日志记录 - /// - public static void DemonstrateExceptionLogging() - { - Console.WriteLine("=== 异常日志记录示例 ==="); - - Log.Configure(LogLevel.Debug, enableConsole: true, useColors: true); - - var serviceLogger = Log.CreateLogger("UserService"); - - try - { - // 模拟业务逻辑中的异常 - throw new InvalidOperationException("用户数据验证失败"); - } - catch (Exception ex) - { - serviceLogger.Error("用户注册失败", ex, new - { - Operation = "UserRegistration", - UserEmail = "user@example.com", - ValidationErrors = new[] { "邮箱格式无效", "密码强度不足" } - }); - } - - // 演示Fatal级别的使用 - try - { - throw new SystemException("数据库连接完全中断"); - } - catch (Exception ex) - { - serviceLogger.Fatal("系统发生致命错误", ex, new - { - ErrorCode = "DB_CONNECTION_FAILED", - RetryAttempts = 3, - LastRetryTime = DateTime.Now.AddMinutes(-5) - }); - } - - Console.WriteLine(); - } - - /// - /// 演示生产环境日志配置 - /// - public static void DemonstrateProductionConfiguration() - { - Console.WriteLine("=== 生产环境日志配置示例 ==="); - - // 生产环境推荐配置 - var productionConfig = new LogConfig - { - DefaultMinLevel = LogLevel.Info, // 只记录Info及以上级别 - EnableConsole = false, // 生产环境通常不输出到控制台 - UseColors = false, - EnableFile = true, // 启用文件日志 - LogFilePath = "logs/production-{yyyy-MM-dd}.log" - }; - - // 为关键模块设置更详细的日志级别 - productionConfig.SetCategoryLevel("Architecture", LogLevel.Info); - productionConfig.SetCategoryLevel("Security", LogLevel.Debug); // 安全相关日志更详细 - productionConfig.SetCategoryLevel("Payment", LogLevel.Debug); // 支付相关日志更详细 - productionConfig.SetCategoryLevel("IOC", LogLevel.Warning); // 减少IOC调试日志 - - Log.Initialize(productionConfig); - - var securityLogger = Log.CreateLogger("Security"); - securityLogger.Info("用户登录尝试", new { UserId = 456, IpAddress = "192.168.1.100" }); - securityLogger.Warn("密码错误", new { UserId = 456, FailedAttempts = 2 }); - securityLogger.Info("登录成功", new { UserId = 456, SessionId = "sess_abc123" }); - - var paymentLogger = Log.CreateLogger("Payment"); - paymentLogger.Debug("开始处理支付", new { OrderId = "ORD_789", Amount = 99.99m, Currency = "CNY" }); - paymentLogger.Info("支付成功", new { OrderId = "ORD_789", TransactionId = "txn_456" }); - - Console.WriteLine("生产环境日志已配置完成，日志文件将保存到 logs/ 目录"); - Console.WriteLine(); - } -} - -/// -/// 示例架构类 -/// -public class ExampleArchitecture : Architecture -{ - protected override void Init() - { - Log.CreateLogger("Architecture").Info("ExampleArchitecture 初始化"); - } -} - -/// -/// 示例系统 -/// -public class ExampleSystem : AbstractSystem -{ - protected override void OnInit() - { - Log.CreateLogger("System").Info("ExampleSystem 初始化完成"); - } - - protected override void OnDestroy() - { - Log.CreateLogger("System").Info("ExampleSystem 销毁"); - } -} - -/// -/// 示例模型 -/// -public class ExampleModel : AbstractModel -{ - protected override void OnInit() - { - Log.CreateLogger("Model").Info("ExampleModel 初始化完成"); - } -} - -/// -/// 示例工具 -/// -public class ExampleUtility : IUtility -{ - public void DoSomething() - { - Log.CreateLogger("Utility").Debug("ExampleUtility 执行操作"); - } -} - -/// -/// 示例事件 -/// -public class ExampleEvent -{ - public string Message { get; set; } = string.Empty; -} \ No newline at end of file diff --git a/GFramework.Core/logging/README.md b/GFramework.Core/logging/README.md index bc0c0cf..981cc55 100644 --- a/GFramework.Core/logging/README.md +++ b/GFramework.Core/logging/README.md @@ -48,12 +48,26 @@ Log.Initialize(config); ### 2. 使用日志记录 +#### 基本使用示例 + ```csharp // 使用全局日志实例 -Log.Info("应用程序启动完成"); -Log.Warn("这是一个警告信息"); -Log.Error("这是一个错误信息", exception); +Log.Info("应用程序启动"); +Log.Warn("这是一个警告"); +Log.Error("这是一个错误信息"); +// 创建特定类别的日志记录器 +var userLogger = Log.CreateLogger("UserService"); +userLogger.Info("用户服务初始化完成", new { ServiceVersion = "1.0" }); + +var dbLogger = Log.CreateLogger("Database"); +dbLogger.Debug("连接数据库", new { Server = "localhost", Database = "MyApp" }); +dbLogger.Info("数据库连接成功"); +``` + +#### 详细使用示例 + +```csharp // 创建特定类别的日志记录器 var logger = Log.CreateLogger("MyModule"); @@ -64,6 +78,54 @@ logger.Error("数据库连接失败", ex, new { DatabaseUrl = "localhost:1433" } logger.Fatal("系统发生严重错误", new { SystemState = "Critical" }); ``` +#### 框架组件日志示例 + +```csharp +// 在架构中使用 +var architecture = ExampleArchitecture.Instance; +architecture.RegisterSystem(new ExampleSystem()); +architecture.RegisterModel(new ExampleModel()); +architecture.RegisterUtility(new ExampleUtility()); + +// 在系统中使用 +public class ExampleSystem : AbstractSystem +{ + protected override void OnInit() + { + Log.CreateLogger("System").Info("ExampleSystem 初始化完成"); + } + + protected override void OnDestroy() + { + Log.CreateLogger("System").Info("ExampleSystem 销毁"); + } +} + +// 在模型中使用 +public class ExampleModel : AbstractModel +{ + protected override void OnInit() + { + Log.CreateLogger("Model").Info("ExampleModel 初始化完成"); + } +} + +// 在工具中使用 +public class ExampleUtility : IUtility +{ + public void DoSomething() + { + Log.CreateLogger("Utility").Debug("ExampleUtility 执行操作"); + } +} + +// 在事件中使用 +architecture.RegisterEvent(evt => +{ + Log.CreateLogger("EventListener").Info($"收到事件: {evt.Message}"); +}); +``` + ### 3. 高级配置 ```csharp @@ -86,6 +148,83 @@ config.SetCategoryLevel("Database", LogLevel.Debug); // 数据库日志 config.SetCategoryLevel("Network", LogLevel.Trace); // 网络日志（最详细） Log.Initialize(config); + +// 演示不同级别的日志记录 +var networkLogger = Log.CreateLogger("Network"); +networkLogger.Trace("网络请求开始", new { Url = "https://api.example.com/users", Method = "GET" }); +networkLogger.Debug("添加请求头", new { Headers = new[] { "Authorization: Bearer xxx", "Content-Type: application/json" } }); +networkLogger.Info("网络请求完成", new { StatusCode = 200, ResponseTime = "120ms" }); + +var userServiceLogger = Log.CreateLogger("UserService"); +userServiceLogger.Debug("查询用户信息", new { UserId = 123 }); +userServiceLogger.Info("用户登录成功", new { UserId = 123, UserName = "张三", LoginTime = DateTime.Now }); +``` + +### 4. 异常日志记录 + +```csharp +var serviceLogger = Log.CreateLogger("UserService"); + +try +{ + // 模拟业务逻辑中的异常 + throw new InvalidOperationException("用户数据验证失败"); +} +catch (Exception ex) +{ + serviceLogger.Error("用户注册失败", ex, new + { + Operation = "UserRegistration", + UserEmail = "user@example.com", + ValidationErrors = new[] { "邮箱格式无效", "密码强度不足" } + }); +} + +// 演示Fatal级别的使用 +try +{ + throw new SystemException("数据库连接完全中断"); +} +catch (Exception ex) +{ + serviceLogger.Fatal("系统发生致命错误", ex, new + { + ErrorCode = "DB_CONNECTION_FAILED", + RetryAttempts = 3, + LastRetryTime = DateTime.Now.AddMinutes(-5) + }); +} +``` + +### 5. 生产环境配置 + +```csharp +// 生产环境推荐配置 +var productionConfig = new LogConfig +{ + DefaultMinLevel = LogLevel.Info, // 只记录Info及以上级别 + EnableConsole = false, // 生产环境通常不输出到控制台 + UseColors = false, + EnableFile = true, // 启用文件日志 + LogFilePath = "logs/production-{yyyy-MM-dd}.log" +}; + +// 为关键模块设置更详细的日志级别 +productionConfig.SetCategoryLevel("Architecture", LogLevel.Info); +productionConfig.SetCategoryLevel("Security", LogLevel.Debug); // 安全相关日志更详细 +productionConfig.SetCategoryLevel("Payment", LogLevel.Debug); // 支付相关日志更详细 +productionConfig.SetCategoryLevel("IOC", LogLevel.Warning); // 减少IOC调试日志 + +Log.Initialize(productionConfig); + +var securityLogger = Log.CreateLogger("Security"); +securityLogger.Info("用户登录尝试", new { UserId = 456, IpAddress = "192.168.1.100" }); +securityLogger.Warn("密码错误", new { UserId = 456, FailedAttempts = 2 }); +securityLogger.Info("登录成功", new { UserId = 456, SessionId = "sess_abc123" }); + +var paymentLogger = Log.CreateLogger("Payment"); +paymentLogger.Debug("开始处理支付", new { OrderId = "ORD_789", Amount = 99.99m, Currency = "CNY" }); +paymentLogger.Info("支付成功", new { OrderId = "ORD_789", TransactionId = "txn_456" }); ``` ## 日志级别说明 @@ -174,6 +313,21 @@ GFramework.Core 在以下关键位置自动添加了日志记录： netLogger.Debug("发送HTTP请求"); ``` +5. **在框架组件中合理使用日志**: + ```csharp + // 在系统初始化时记录 + protected override void OnInit() + { + Log.CreateLogger("System").Info("系统初始化完成"); + } + + // 在事件处理中记录 + architecture.RegisterEvent(evt => + { + Log.CreateLogger("Event").Info("用户登录事件", new { UserId = evt.UserId }); + }); + ``` + ## 配置建议 ### 开发环境