XCEngine/docs/api/XCEngine/Debug/Logger/Logger.md

# Logger

**命名空间**: `XCEngine::Debug`

**类型**: `class (singleton)`

**头文件**: `XCEngine/Debug/Logger.h`

**描述**: 构造日志记录、应用全局过滤并把日志分发到多个 sink。

## 概述

`Logger` 是 XCEngine 当前日志系统的中心节点。业务代码、测试程序和工具层并不直接操作控制台或文件，而是先把消息交给 `Logger`，再由它把统一格式的 `LogEntry` 分发给已注册的 `ILogSink`。

这类设计的好处是：

- 输出目标可以随运行环境变化，而业务日志调用点保持不变。
- 全局级别过滤和 category 开关只需要维护一份。
- 可以在编辑器、命令行测试和文件日志之间复用同一条日志链路。

## 生命周期

- [Get](Get.md) 返回进程级单例。
- [Initialize](Initialize.md) 只设置初始化标志，不会自动添加默认 sink。
- [Shutdown](Shutdown.md) 会 `Flush` 所有 sink 并清空 sink 列表。
- [Log](Log.md) 在第一次被调用时会自动调用 `Initialize`。

推荐做法：

- 在程序启动阶段显式 `Initialize` 并注册 sink。
- 在受控退出阶段调用 `Shutdown`，避免与其它线程仍在写日志时并发销毁。

## 线程语义

- `AddSink`、`RemoveSink` 和 `Log` 通过内部 `Mutex` 保护 sink 列表访问。
- `SetMinimumLevel` 和 `SetCategoryEnabled` 当前没有加锁，更适合作为初始化阶段配置，而不是高频热更新开关。
- `Shutdown` 当前也没有在锁内遍历 sink；应在其它线程不再写日志时调用。

## 所有权

- `AddSink` 接收 `std::unique_ptr<ILogSink>`，所有权转移给 `Logger`。
- `RemoveSink` 只按裸指针匹配已注册对象；如果调用方未来需要移除某个 sink，必须在移交所有权前保留一份原始指针。

## 宏与便捷接口

- `XE_LOG(category, level, message)` 会把 `__FILE__`、`__LINE__` 和 `__FUNCTION__` 一并传给 `Logger::Log`。
- `XE_ASSERT(condition, message)` 在条件失败时只记录一条 `Fatal` 级别日志；当前实现不会中断程序、抛异常或触发调试断点。
- `Verbose`、`Debug`、`Info`、`Warning`、`Error`、`Fatal` 都是 `Log` 的便捷封装，但默认不带源码位置信息。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Get](Get.md) | 获取全局 `Logger` 实例。 |
| [Initialize](Initialize.md) | 初始化日志系统状态。 |
| [Shutdown](Shutdown.md) | 刷新并移除所有 sink。 |
| [AddSink](AddSink.md) | 注册一个新的日志输出目标。 |
| [RemoveSink](RemoveSink.md) | 根据原始指针移除 sink。 |
| [Log](Log.md) | 构造 `LogEntry` 并分发到所有 sink。 |
| [Verbose](Verbose.md) | 发送 `Verbose` 级日志。 |
| [Debug](Debug.md) | 发送 `Debug` 级日志。 |
| [Info](Info.md) | 发送 `Info` 级日志。 |
| [Warning](Warning.md) | 发送 `Warning` 级日志。 |
| [Error](Error.md) | 发送 `Error` 级日志。 |
| [Fatal](Fatal.md) | 发送 `Fatal` 级日志。 |
| [SetMinimumLevel](SetMinimumLevel.md) | 设置全局最小日志级别。 |
| [SetCategoryEnabled](SetCategoryEnabled.md) | 打开或关闭某个日志分类。 |

## 真实使用位置

当前代码库中，`Logger` 已经被用于：

- 编辑器启动流程，为控制台、编辑器面板和文件同时输出日志。
- RHI 集成测试，为控制台和文件记录帧调试信息。
- `RenderDocCapture`、截图工具和资源管理等低层模块的错误与警告输出。

## 相关文档

- [当前模块](../Debug.md)
- [ILogSink](../ILogSink/ILogSink.md)
- [ConsoleLogSink](../ConsoleLogSink/ConsoleLogSink.md)
- [FileLogSink](../FileLogSink/FileLogSink.md)
- [LogEntry](../LogEntry/LogEntry.md)
- [Logging Architecture](../../../_guides/Debug/Logging-Architecture.md)