XCEngine/docs/api/XCEngine/Debug/FileLogSink/FileLogSink.md

# FileLogSink

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

**类型**: `class`

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

**描述**: 将日志追加写入文件，并在失败时回退到 `stderr`。

## 概述

`FileLogSink` 负责把 `LogEntry` 序列化成文本并落盘。它适合编辑器、集成测试和长时间运行的工具程序，因为这类场景通常需要保留会话级日志以便复盘。

当前实现中的关键行为：

- 构造时尝试以追加模式打开目标文件。
- 每次写入后立即 `Flush`，优先保证可追溯性，而不是吞吐量。
- 如果文件句柄不可用，会在 `Log` 时尝试重新打开。
- 如果重新打开或写入失败，会把错误和原始日志内容写到 `stderr`。

## 生命周期

- [Constructor](Constructor.md) 保存目标路径并尝试打开文件。
- [Destructor](Destructor.md) 关闭底层 `FileWriter`。
- [Flush](Flush.md) 将缓冲区刷到磁盘。

## 线程语义

- `FileLogSink` 自身没有显式加锁。
- 通过 `Logger` 使用时，调用会被 `Logger` 串行化。
- 当前实现使用 `std::localtime` 生成时间文本；如果绕过 `Logger` 并发调用，线程安全性由调用方承担。

## 输出格式

当前实现输出格式为：

```text
[YYYY-MM-DD HH:MM:SS] [LEVEL] [Category] message
```

注意：

- 使用的是 `LogEntry::timestamp` 的本地时间表示。
- 当前不会把 `file`、`line`、`function` 或 `threadId` 写入文件。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Constructor](Constructor.md) | 构造文件日志 sink。 |
| [Destructor](Destructor.md) | 析构 sink 并关闭文件。 |
| [Log](Log.md) | 将日志条目写入文件。 |
| [Flush](Flush.md) | 刷新底层文件。 |

## 相关文档

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