XCEngine/docs/api/XCEngine/Core/FileWriter/FileWriter.md

# FileWriter

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

**类型**: `class`

**头文件**: `XCEngine/Core/FileWriter.h`

**描述**: 一个基于 `FILE*` 的轻量文件写入封装，提供打开、关闭、写入和刷新能力。

## 角色概述

`FileWriter` 是当前 `Core` 顶层里非常朴素的 I/O 工具类。它没有做复杂的路径解析、目录创建或异步写入，只是把一组常见的 C 文件写入操作包装成 RAII 风格接口。

这类工具在引擎里常用于：

- 简单二进制导出
- 文本或日志写出
- 不需要完整文件系统抽象时的底层落盘

## 当前实现行为

### 1. 构造和析构遵循 RAII

- 默认构造不会自动打开文件
- 带路径构造会立刻尝试 `Open()`
- 析构函数会自动 `Close()`

### 2. `Open()` 会先关闭旧文件

当前 `Open(const char* filePath, bool append)` 的第一步就是调用 `Close()`。这意味着：

- 可以重复复用同一个 `FileWriter`
- 打开新文件前，旧句柄会先被安全关闭

### 3. 始终以二进制模式打开

当前模式字符串是：

- `append == false` -> `"wb"`
- `append == true` -> `"ab"`

也就是说，它没有文本模式分支，始终按二进制写入处理。

### 4. `Write()` 的失败条件很直接

`Write(const char* data, size_t length)` 在以下情况返回 `false`：

- 文件没打开
- `data == nullptr`
- `length == 0`
- `fwrite` 未完整写入指定长度

这意味着“空写入”也会被视为失败，而不是 no-op success。

### 5. `Write(const Containers::String&)` 只是便利重载

它会转发到字节写入版本，使用：

- `str.CStr()`
- `str.Length()`

当前没有额外编码转换或换行处理。

## 当前代码库中的使用情况

在当前取证范围内，没有看到 `FileWriter` 在 `engine/src` 里形成广泛调用链。因此它当前更像底层通用工具，而不是高频核心主线类型。

## 线程语义

- 当前实现没有加锁。
- `FILE*` 句柄由对象内部独占持有。
- 默认应按单线程顺序使用。

## 当前实现限制

- 不会自动创建父目录。
- 只提供写入，不提供读取。
- 打开模式固定为二进制写/追加。
- `Write(length == 0)` 会返回 `false`。
- 没有看到直接单元测试覆盖。

## 相关方法

- [Constructor](Constructor.md)
- [Destructor](Destructor.md)
- [Open](Open.md)
- [Close](Close.md)
- [Write](Write.md)
- [Flush](Flush.md)
- [IsOpen](IsOpen.md)

## 相关文档

- [当前模块](../Core.md)
- [IO](../IO/IO.md)
- [API 总索引](../../../main.md)