mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-25 21:34:28 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
18 KiB
18 KiB
日志系统
**本文引用的文件** - [ILogger.cs](file://GFramework.Core.Abstractions/logging/ILogger.cs) - [ILoggerFactory.cs](file://GFramework.Core.Abstractions/logging/ILoggerFactory.cs) - [ILoggerFactoryProvider.cs](file://GFramework.Core.Abstractions/logging/ILoggerFactoryProvider.cs) - [LogLevel.cs](file://GFramework.Core.Abstractions/logging/LogLevel.cs) - [AbstractLogger.cs](file://GFramework.Core/logging/AbstractLogger.cs) - [ConsoleLogger.cs](file://GFramework.Core/logging/ConsoleLogger.cs) - [ConsoleLoggerFactory.cs](file://GFramework.Core/logging/ConsoleLoggerFactory.cs) - [ConsoleLoggerFactoryProvider.cs](file://GFramework.Core/logging/ConsoleLoggerFactoryProvider.cs) - [LoggerFactoryResolver.cs](file://GFramework.Core/logging/LoggerFactoryResolver.cs) - [README.md](file://GFramework.Core/logging/README.md) - [LoggerTests.cs](file://GFramework.Core.Tests/logging/LoggerTests.cs) - [ConsoleLoggerTests.cs](file://GFramework.Core.Tests/logging/ConsoleLoggerTests.cs) - [LoggerFactoryTests.cs](file://GFramework.Core.Tests/logging/LoggerFactoryTests.cs)目录
简介
本文件为 GFramework 日志系统的技术文档，围绕日志抽象层、控制台输出、工厂模式与解析器、日志级别与最佳实践展开，帮助开发者快速理解并扩展日志能力，构建可观测的游戏架构。
项目结构
日志系统位于 GFramework.Core 与 GFramework.Core.Abstractions 两个项目中，分别提供抽象接口与具体实现；Godot 平台另提供 GodotLogger 等扩展（本篇聚焦核心日志体系）。
graph TB
subgraph "抽象层"
ILog["ILogger 接口"]
IFac["ILoggerFactory 接口"]
IFacP["ILoggerFactoryProvider 接口"]
Lvl["LogLevel 枚举"]
end
subgraph "核心实现"
Abs["AbstractLogger 抽象基类"]
Con["ConsoleLogger 控制台实现"]
Fac["ConsoleLoggerFactory 工厂"]
FacP["ConsoleLoggerFactoryProvider 工厂提供程序"]
Res["LoggerFactoryResolver 解析器"]
end
ILog --> Abs
IFac --> Fac
IFacP --> FacP
Lvl --> Abs
Lvl --> Con
Lvl --> Fac
Lvl --> FacP
Abs --> Con
FacP --> Fac
Res --> FacP
图表来源
- ILogger.cs
- ILoggerFactory.cs
- ILoggerFactoryProvider.cs
- LogLevel.cs
- AbstractLogger.cs
- ConsoleLogger.cs
- ConsoleLoggerFactory.cs
- ConsoleLoggerFactoryProvider.cs
- LoggerFactoryResolver.cs
章节来源
核心组件
- 抽象接口层：定义日志记录器、工厂、工厂提供程序与日志级别的统一契约。
- 抽象基类：封装级别判断、格式化与异常处理，子类仅需实现 Write。
- 具体实现：ConsoleLogger 提供控制台输出与彩色打印；ConsoleLoggerFactory/Provider 提供实例创建；LoggerFactoryResolver 统一解析与配置。
章节来源
- ILogger.cs
- ILoggerFactory.cs
- ILoggerFactoryProvider.cs
- LogLevel.cs
- AbstractLogger.cs
- ConsoleLogger.cs
- ConsoleLoggerFactory.cs
- ConsoleLoggerFactoryProvider.cs
- LoggerFactoryResolver.cs
架构总览
日志系统采用“接口抽象 + 工厂 + 解析器”的分层设计，便于替换输出目标（控制台、文件、网络等），并通过解析器集中管理默认提供程序与全局最小级别。
classDiagram
class ILogger {
+Name() string
+IsTraceEnabled() bool
+IsDebugEnabled() bool
+IsInfoEnabled() bool
+IsWarnEnabled() bool
+IsErrorEnabled() bool
+IsFatalEnabled() bool
+IsEnabledForLevel(level) bool
+Trace(...)
+Debug(...)
+Info(...)
+Warn(...)
+Error(...)
+Fatal(...)
}
class ILoggerFactory {
+GetLogger(name, minLevel) ILogger
}
class ILoggerFactoryProvider {
+MinLevel : LogLevel
+CreateLogger(name) ILogger
}
class LogLevel {
<<enum>>
+Trace
+Debug
+Info
+Warning
+Error
+Fatal
}
class AbstractLogger {
-string _name
+Name() string
#IsEnabled(level) bool
#IsTraceEnabled() bool
#IsDebugEnabled() bool
#IsInfoEnabled() bool
#IsWarnEnabled() bool
#IsErrorEnabled() bool
#IsFatalEnabled() bool
#IsEnabledForLevel(level) bool
#Trace(...)
#Debug(...)
#Info(...)
#Warn(...)
#Error(...)
#Fatal(...)
#Write(level, message, exception) void
}
class ConsoleLogger {
-bool _useColors
-TextWriter _writer
#Write(level, message, exception) void
}
class ConsoleLoggerFactory {
+GetLogger(name, minLevel) ILogger
}
class ConsoleLoggerFactoryProvider {
+MinLevel : LogLevel
+CreateLogger(name) ILogger
}
class LoggerFactoryResolver {
+Provider : ILoggerFactoryProvider
+MinLevel : LogLevel
}
ILogger <|.. AbstractLogger
AbstractLogger <|-- ConsoleLogger
ILoggerFactory <|.. ConsoleLoggerFactory
ILoggerFactoryProvider <|.. ConsoleLoggerFactoryProvider
LogLevel --> AbstractLogger : "minLevel"
LogLevel --> ConsoleLogger : "minLevel"
LogLevel --> ConsoleLoggerFactory : "minLevel"
LogLevel --> ConsoleLoggerFactoryProvider : "MinLevel"
LoggerFactoryResolver --> ConsoleLoggerFactoryProvider : "默认提供程序"
ConsoleLoggerFactory --> ConsoleLogger : "创建"
ConsoleLoggerFactoryProvider --> ConsoleLoggerFactory : "委托"
图表来源
- ILogger.cs
- ILoggerFactory.cs
- ILoggerFactoryProvider.cs
- LogLevel.cs
- AbstractLogger.cs
- ConsoleLogger.cs
- ConsoleLoggerFactory.cs
- ConsoleLoggerFactoryProvider.cs
- LoggerFactoryResolver.cs
组件详解
ILogger 接口与日志抽象层
- 设计要点
- 统一日志级别检查与记录方法族，覆盖 Trace/Debug/Info/Warn/Error/Fatal。
- 支持格式化参数与异常附带，避免不必要的字符串拼接开销。
- 通过 Name() 提供命名空间级隔离，便于多模块日志分类。
- 复杂度与性能
- 级别检查为 O(1)，格式化在启用时进行，未启用级别直接短路。
- 错误处理
- 对未知级别抛出参数异常，保证上层调用健壮性。
章节来源
AbstractLogger 抽象基类
- 设计模式
- 模板方法：子类仅需实现 Write，其余级别判断、格式化、异常处理由基类完成。
- 关键机制
- 最小级别 minLevel：IsEnabled(level) 做前置过滤。
- 核心管道：Log(...) 负责格式化与异常包装，最终调用 Write。
- 名称常量 ROOTLoggerName 用于默认日志器标识。
- 性能优化
- 启用检查优先，避免格式化与 IO。
- 参数化日志使用字符串格式化，减少中间字符串对象。
章节来源
ConsoleLogger 控制台实现
- 输出格式
- 时间戳：精确到毫秒。
- 级别：大写并右对齐占位，统一宽度。
- 名称：[Name()] 标识来源。
- 异常：换行追加异常文本。
- 彩色输出
- 仅在 writer 指向 Console.Out 且 useColors=true 时启用。
- 不同级别映射不同控制台前景色。
- 可定制性
- 支持自定义 TextWriter 与 useColors。
- 默认最小级别为 Info，可通过构造函数调整。
章节来源
ILoggerFactory 与 ConsoleLoggerFactory
- ILoggerFactory
- 根据名称与最小级别创建 ILogger 实例。
- ConsoleLoggerFactory
- 返回 ConsoleLogger 实例，内部默认最小级别为 Info。
- 使用建议
- 通过工厂按模块/服务创建独立日志器，便于分级与过滤。
章节来源
ILoggerFactoryProvider 与 ConsoleLoggerFactoryProvider
- ILoggerFactoryProvider
- 暴露 MinLevel 属性，用于统一设定最小级别。
- CreateLogger(name) 返回带名称与 MinLevel 的 ILogger。
- ConsoleLoggerFactoryProvider
- 默认 MinLevel=Info；委托 ConsoleLoggerFactory.GetLogger(name, minLevel)。
- 多实例支持
- 可创建多个提供程序实例，各自持有独立 MinLevel，互不影响已创建实例。
章节来源
LoggerFactoryResolver 工厂解析机制
- 职责
- Provider：全局默认工厂提供程序（默认 ConsoleLoggerFactoryProvider）。
- MinLevel：全局最小级别（默认 Info）。
- 用法
- 通过 Provider.CreateLogger(name) 获取日志器，自动应用 Provider 的 MinLevel。
- 可动态切换 Provider 与 MinLevel，影响后续创建的日志器。
- 多实例支持
- 已创建的日志器维持其构造时的 minLevel，不受 Provider.MinLevel 后续变更影响。
章节来源
日志级别设计与使用场景
- 级别定义
- Trace → Debug → Info → Warning → Error → Fatal（数值递增）
- 使用建议
- Trace：复杂流程追踪、函数调用链。
- Debug：开发期变量、分支状态。
- Info：关键业务流程、系统状态。
- Warning：潜在问题，不影响运行。
- Error：功能异常，可恢复。
- Fatal：不可恢复错误。
- 性能与可读性
- 通过最小级别裁剪日志量，避免生产环境噪声。
- 结合命名空间区分模块，提升检索效率。
章节来源
依赖关系分析
- 抽象依赖
- ILogger 依赖 LogLevel；ILoggerFactory/Provider 依赖 ILogger。
- 实现依赖
- AbstractLogger 实现 ILogger，并依赖 LogLevel。
- ConsoleLogger 继承 AbstractLogger，依赖控制台输出与颜色 API。
- ConsoleLoggerFactory/Provider 依赖 ConsoleLogger 与 LogLevel。
- LoggerFactoryResolver 依赖 ConsoleLoggerFactoryProvider 作为默认提供程序。
- 耦合与内聚
- 抽象清晰，实现可替换；工厂与解析器解耦，便于扩展与测试。
graph LR
LogLevel --> ILogger
LogLevel --> ILoggerFactory
LogLevel --> ILoggerFactoryProvider
LogLevel --> AbstractLogger
LogLevel --> ConsoleLogger
ILogger --> AbstractLogger
ILoggerFactory --> ConsoleLoggerFactory
ILoggerFactoryProvider --> ConsoleLoggerFactoryProvider
ConsoleLoggerFactory --> ConsoleLogger
ConsoleLoggerFactoryProvider --> ConsoleLoggerFactory
LoggerFactoryResolver --> ConsoleLoggerFactoryProvider
图表来源
- ILogger.cs
- ILoggerFactory.cs
- ILoggerFactoryProvider.cs
- LogLevel.cs
- AbstractLogger.cs
- ConsoleLogger.cs
- ConsoleLoggerFactory.cs
- ConsoleLoggerFactoryProvider.cs
- LoggerFactoryResolver.cs
性能考量
- 级别检查优先：在记录前进行 IsEnabled 判断，避免格式化与 IO。
- 参数化日志：使用格式化方法减少中间字符串对象创建。
- 控制台输出：彩色输出仅在 Console.Out 且启用时生效，避免跨流色彩污染。
- 批量输出：多行日志分行输出，注意外部缓冲区大小与刷新策略。
- 生产建议：将 MinLevel 提升至 Info 或 Warning，降低日志写入压力。
章节来源
故障排查指南
- 日志未输出
- 检查最小级别是否高于当前级别；通过 IsEnabledForLevel 验证。
- 确认构造函数传入的 minLevel 是否正确。
- 输出不符合预期
- ConsoleLogger 仅在 writer 为 Console.Out 且 useColors=true 时启用彩色。
- 若传入自定义 TextWriter，请确认其是否被正确刷新。
- 多实例行为差异
- Provider.MinLevel 变更不影响已创建实例；如需一致行为，重新创建实例。
- 异常信息未显示
- 确保调用带 Exception 的重载方法；异常会在单独行追加。
章节来源
结论
GFramework 日志系统以清晰的抽象层与工厂解析机制为核心，既满足控制台开发的即时可观测性，又为多平台输出与多实例管理奠定基础。通过合理的日志级别与命名策略，结合参数化日志与最小级别裁剪，可在性能与可观测性之间取得平衡。
附录
API 一览（核心）
- ILogger
- 级别检查：IsTraceEnabled/IsDebugEnabled/IsInfoEnabled/IsWarnEnabled/IsErrorEnabled/IsFatalEnabled/IsEnabledForLevel
- 记录方法：Trace/Debug/Info/Warn/Error/Fatal（支持格式化与异常）
- 元数据：Name()
- ILoggerFactory：GetLogger(name, minLevel)
- ILoggerFactoryProvider：MinLevel + CreateLogger(name)
- LogLevel：Trace/Debug/Info/Warning/Error/Fatal
- AbstractLogger：模板方法 Write(level, message, exception)
- ConsoleLogger：控制台输出 + 彩色打印 + 可定制 TextWriter/useColors
- LoggerFactoryResolver：Provider（默认 ConsoleLoggerFactoryProvider）+ MinLevel（默认 Info）
章节来源
- ILogger.cs
- ILoggerFactory.cs
- ILoggerFactoryProvider.cs
- LogLevel.cs
- AbstractLogger.cs
- ConsoleLogger.cs
- ConsoleLoggerFactory.cs
- ConsoleLoggerFactoryProvider.cs
- LoggerFactoryResolver.cs
最佳实践
- 合理选择日志级别：Info 记录主业务，Debug 记录开发期细节，Warning/Error/Fatal 分级告警。
- 提供上下文：在消息中包含关键上下文（如用户 ID、任务 ID），便于检索。
- 异常记录：统一使用带 Exception 的重载，保留堆栈信息。
- 分类日志：按模块/服务创建独立日志器，使用名称区分来源。
- 性能监控：在关键路径埋点，结合日志与指标，形成闭环观测。
章节来源