先讲一个真出现过的事故。一个服务启动时要把新配置写到 /etc/app/conf.toml。代码写得很直白:fs::write(path, new_content)。fs::write 的内部行为是「打开文件、截断成 0 字节、再写」。那天机器恰好在那几毫秒里断电,重启后配置文件是空的,服务起不来,而旧配置已经没了。
这不是 Rust 的问题,是「原地覆盖」这个动作本身不安全:它先把旧内容毁掉,再写新内容,中间有一段两者都不完整的窗口。文件系统这一层看起来只是几个函数,真正难的是这些函数背后的语义:什么时候算写完、路径为什么不等于字符串、目录里文件的顺序为什么不能依赖、读出来的字节为什么可能不是 UTF-8。
这一篇把 std::fs 和 std::path 拆开讲,每一段都配一个在本机真跑过的例子。学完的标准不是背 API,而是遇到「文件读出来乱码」「目录顺序每次不一样」「写完断电丢数据」时,知道该查哪一层。
Path 与 PathBuf:路径不是字符串
新手最容易把路径当 String 拼。用 format!("{}/{}", dir, file) 拼出来的东西在 Windows 上可能用正斜杠,在 Linux 上可能混进反斜杠,遇到文件名里带空格、带中文、带 .. 时行为更不可预测。Rust 用两个类型把路径单独建模:Path 是借用的路径切片,类似 &str;PathBuf 是拥有所有权的路径,类似 String。
用 Path::new 或 PathBuf::from 构造,用 join 拼接,用 file_name、extension、parent、with_extension 拆解。下面是在 Windows 上实际跑出来的输出:
join => demo_root\logs\app.log
file_name => Some("app.log")
extension => Some("log")
parent => demo_root\logs
with_ext => demo_root\logs\app.log.bak
exists => false
注意 with_extension("log.bak") 的结果是把原来的 .log 换掉,不是追加。想保留原扩展名要自己拼 file_name 再加后缀。另一个容易误会的点是 exists():它只回答「现在能不能看到」,不保证接下来还能打开。文件可能在检查完的一瞬间被别的进程删掉,这就是典型的检查与使用之间的竞态。正确做法是直接打开,让错误在打开时暴露,而不是先 exists() 再操作。
Path 还处理了平台差异。components() 能按平台的规则把路径拆成根、普通段、..,is_absolute() 判断绝对路径。需要绝对路径时用 canonicalize,它会解析 ..、跟随符号链接,并且要求路径真实存在。在 Windows 上它返回的路径会带 \\?\ 前缀,这是 Win32 的长路径形式,用来绕开 260 字符限制。打印给人看时通常要去掉,传给文件 API 时保留反而更稳。
还有一类路径根本不能变成 UTF-8:Unix 上文件名是任意字节序列,Path::to_str() 返回 Option,遇到非法字节就是 None。如果程序把路径当字符串处理,这类文件就会静默丢失。需要完整支持时用 OsStr/OsString,只在展示时做有损转换。
读文件:整读和流式是两种量级
fs::read_to_string 和 fs::read 都是整读:一次性把文件全部放进内存。前者的额外要求是内容必须是合法 UTF-8,否则直接报错。实测一个 GBK 编码的字节序列:
utf8 err => stream did not contain valid UTF-8 (InvalidData)
raw bytes => [196, 227, 186, 10]
[196, 227] 在 GBK 里是「你」,在 UTF-8 里不是合法序列。这里没有乱码,只有明确的失败,这是好事:错误在读取时暴露,而不是在界面上显示成一串问号。要处理非 UTF-8,先用 fs::read 拿字节,再按已知编码解码;不知道编码就得引入 encoding_rs 之类的库,或者接受有损转换。标准库只认 UTF-8,这条限制必须写进文档。
整读的另一个问题是内存。100 MB 的日志占 100 MB 堆内存,1 GB 的文件在 32 位进程里直接失败。日志、CSV、导出的数据这类「行结构」的文件应该流式读:
let reader = BufReader::new(File::open(&big)?);
let mut count = 0u64;
for line in reader.lines() {
let line = line?;
count += 1;
}
实测读 20 万行、约 2.7 MB 的文件,debug 构建耗时 123.9 毫秒,内存占用只跟 BufReader 的缓冲区有关。这个数字只说明量级,换机器、换 release 构建都会变,不要拿它当性能结论。流式的代价是借用关系和错误处理更麻烦:不能随手把行借出去,逐行都可能出错,lines() 还会把行尾的 \r\n 或 \n 去掉。要保留原始字节就不能用 lines,得自己 read_until(b'\n')。
BufWriter。write_all 只是写进缓冲区,不调用 flush 或让 writer 析构,数据可能还留在用户态。程序正常返回时析构会 flush,但 process::exit 不会执行析构,这条区别在写日志时很致命。目录遍历:顺序不是承诺
fs::read_dir 返回一个迭代器,每次给一个 DirEntry。文档明确说顺序由平台决定,不保证任何次序;同一个目录在不同文件系统、不同创建历史下顺序都可能不同。所以只要输出要稳定,就必须自己收集、排序:
let mut entries: Vec<PathBuf> = fs::read_dir(dir)?
.filter_map(|e| e.ok())
.filter(|e| e.path().extension().map_or(false, |x| x == "log"))
.map(|e| e.path())
.collect();
entries.sort();
实测目录里放了 b.log、a.log、c.txt,过滤扩展名再排序后输出 a.log、b.log。这里有两个细节:filter_map(|e| e.ok()) 把读目录时的错误吞掉了,生产代码应该把错误收集起来而不是静默跳过;extension() 只比较扩展名,不判断是不是普通文件,目录也可能叫 foo.log,要再用 metadata().is_file() 排除。
递归遍历标准库没有现成函数,要自己写。简单做法是显式维护一个栈,遇到目录就压进去,避免递归过深把栈打爆;同时要决定是否跟随符号链接。跟随符号链接可能走进循环,也可能越出你以为的目录范围。成熟项目一般用 walkdir 这类库,但它不在标准库里,本篇不引入依赖,只写单层遍历。
DirEntry 上的 file_type() 在某些平台是免费拿到的,metadata() 则可能要额外一次系统调用。遍历几万个文件时这个差别会累积,但先别为它优化,除非你真的测到瓶颈。
权限:只读不是你想的那个意思
Permissions::readonly() 在 Windows 上对应的是文件的只读属性,在 Unix 上对应「所有者写位是否关闭」,两者语义并不完全一样。实测把一个文件设成只读再取消:
readonly => false
readonly => true
readonly => false
能设置不等于能保护。set_readonly(true) 只是改属性,拥有足够权限的进程仍然可以改回来。它挡的是「误写」,不是「恶意写」。真正的权限控制要靠操作系统的用户与访问控制,Rust 层只是转发。
Unix 上还有 std::os::unix::fs::PermissionsExt,可以设置 0o644 这类模式位,这段在本机 Windows 上无法运行,标注为未实测。跨平台代码要把权限逻辑放进 #[cfg(unix)] 分支,而不是假设 set_readonly 能表达所有需求。另一个常见错误是先检查权限再写:检查与写入之间权限可能变,正确姿势是直接写,失败了再根据 ErrorKind::PermissionDenied 给用户提示。
Windows 的访问控制比「只读」复杂得多,真正的权限是 ACL,标准库没有暴露设置 ACL 的接口,只能读到只读属性。要精细控制得走 Windows API 或者外部库,这段本机没有实测,不展开。实际项目里更常见的是「服务账号对目录有没有写权限」这类部署问题,它和代码里的权限 API 是两回事:代码写得再对,账号没权限照样失败,排查时先看进程身份,再看代码。
原子替换:别在原地毁掉旧文件
回到开头的事故。安全的做法是「写临时文件、落盘、再改名覆盖」:
let tmp = path.with_extension("tmp");
{
let mut f = File::create(&tmp)?;
f.write_all(new_content.as_bytes())?;
f.sync_all()?;
}
fs::rename(&tmp, &path)?;
实测这段执行后,目标文件内容从 old 变成 new:
atomic => new
为什么这样安全:rename 在同一文件系统内是原子的,调用返回时,目标要么是完整的旧文件,要么是完整的新文件,不会出现半截。前提有三个,缺一不可。第一,临时文件和目标必须在同一个文件系统,跨盘 rename 会失败或退化成复制。第二,sync_all 必须在 rename 之前,否则断电后可能文件内容还没落盘,名字却已经换过去了。第三,崩溃后要能清理残留的临时文件,启动时扫一遍 *.tmp 删掉。
Windows 上 fs::rename 覆盖已存在的文件是可以成功的,底层用的是带替换标志的移动;Unix 的 rename 同样覆盖。但目录不在这个规则里:把临时目录 rename 成已有目录,行为依平台而定,不要依赖。还有一点,Unix 上父目录的元数据也要落盘才算真正持久,需要打开目录再 fsync,标准库没有直接接口,得用 File::open(dir) 再 sync_all,这条在 Windows 上不适用。
临时文件的命名也有讲究。如果固定叫 conf.toml.tmp,两个进程同时更新配置就会写同一个临时文件,最后谁 rename 谁的内容说不清。可用的做法是把进程号和时间戳拼进文件名,并且用 OpenOptions::new().create_new(true).write(true) 打开,create_new 保证「不存在才创建」,已存在就报错,这样名字冲突会立刻暴露而不是静默覆盖。创建成功后如果后续步骤失败,要负责把临时文件删掉,否则崩溃恢复时目录里会积一堆垃圾。
追加、截断与打开模式
File::create 等价于「创建或截断」,每次都会清空原内容。想追加用 OpenOptions::new().create(true).append(true),追加模式下每次写都由内核定位到文件末尾,多进程同时追加通常不会互相覆盖(但写入顺序仍然不保证)。实测连续两次打开追加:
append => "record\nrecord\n"
日志轮转是追加模式的反面:文件到一定大小要换新文件。常见错误是「先读文件大小,超限就改名,再新建一个」,两个进程同时做就会互相踩。正确做法是用一个锁文件或让单一进程负责轮转,其他进程只追加。文件系统的 API 不会替你做互斥,这一层要自己设计。
说到互斥就绕不开文件锁。标准库没有跨平台的锁文件 API:Unix 上是 flock,Windows 上是 LockFileEx,语义还不完全一样。常用方案是引入 fs2 这类库,或者自己写一个「创建独占文件成功才拿到锁」的约定。这段本机没有实测,只给结论:文件锁能防住多个进程同时改同一份数据,但防不住「拿到锁之后忘了释放」,也防不住网络文件系统上的实现差异。用锁文件时要把持有时间压到最短,并且在异常路径上也要释放。
还有一类容易忽略的打开模式:create_new、truncate、append 可以组合,不同组合对应完全不同的语义。写临时文件、写日志、写缓存应该用不同的组合,不要到处都用 File::create。File::create 最省事,但它隐含「允许截断」,在很多场景里正是你不想要的那个动作。
现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 程序崩溃后配置文件变成 0 字节 | 用 fs::write 原地覆盖,截断与写入之间有窗口 | 改成临时文件 + sync_all + rename |
read_to_string 报 InvalidData | 文件不是 UTF-8,常见于 GBK 日志或混入二进制 | 先用 fs::read 看原始字节,确认编码后再解码 |
| 同样的目录两次遍历,输出顺序不同 | read_dir 不保证顺序,由文件系统决定 | 收集后按文件名排序,别依赖迭代顺序 |
| 路径拼接后多出反斜杠或找不到文件 | 用字符串拼路径,混用了平台分隔符 | 全程用 Path/PathBuf 和 join |
exists() 为真,打开却失败 | 检查与使用之间有竞态,文件被删除或改名 | 去掉预检查,直接打开并处理错误 |
| 写日志后进程退出,最后几行丢了 | 缓冲区没 flush,process::exit 不执行析构 | 退出前显式 flush,或用 sync_all |
| 只读属性设了还是被改 | 只读只是文件属性,不是访问控制 | 用系统权限模型,别把 set_readonly 当安全边界 |
| 1 GB 文件读到一半内存爆了 | read_to_string 整读,堆占用等于文件大小 | 换 BufReader 逐行或分块处理 |
临时文件残留一堆 .tmp | 崩溃发生在 rename 之前,没有清理逻辑 | 启动时按命名规则扫描并删除过期临时文件 |
边界与代价
第一层代价是平台差异。路径分隔符、大小写敏感、长路径限制、符号链接语义、目录 fsync,各平台都不一样。Rust 抹平了类型层面的差异,但抹不平语义层面的差异。跨平台程序要么明确只支持一种平台,要么把差异集中到一个小模块里,别散落在业务代码里。
大小写是最容易被忽略的一条。Windows 与 macOS 默认大小写不敏感,Linux 敏感,代码里写 Config.TOML,在开发机上能找到 config.toml,部署到 Linux 就找不到。Unicode 规范化也有差异:macOS 会把某些文件名转成分解形式,看起来一样的名字,字节不一样。跨平台比较路径时别直接比字符串,要么比 canonicalize 后的结果,要么在文档里明确只支持一个平台。这类问题不会在开发机上暴露,只会在部署当天出现。
第二层是错误信息的质量。std::io::Error 只带系统错误码和一句系统语言的消息,用户看到「系统找不到指定的文件」时并不知道是哪个文件。正确做法是在调用点包一层上下文,比如「读取配置 /etc/app/conf.toml 失败:……」。用 Box<dyn Error> 还是具体错误类型,取决于调用方要不要区分错误种类;命令行工具用前者省事,库用后者更好。
第三层是性能与安全性的取舍。整读快、代码简单,但内存和编码假设都更强;流式省内存,但要处理逐行错误和借用。原子替换多一次写和一次 rename,换来崩溃安全。每个选择都有明确的代价,关键是知道自己在为哪条买账,而不是照着「最佳实践」抄。
第四层是文件系统不是数据库。它不提供事务,不提供跨文件的一致性,不保证目录项和内容的顺序。需要这些能力时,应该用 SQLite 这类嵌入式数据库,而不是用一堆 rename 和锁文件硬凑。Rust 的标准库故意只做「操作系统能力的转发」,剩下的语义要上层自己定义。
小结
这一篇的线索可以收成四句话:路径用 Path/PathBuf,不要拼字符串;读文件先问「整读还是流式」,再看编码;目录顺序不保证,要排序就自己排;覆盖文件先写临时文件,落盘再 rename。权限和原子性都有明确的能力边界,别把属性当安全,也别把 rename 当事务。
这些能力全部来自操作系统,std::fs 只是把它们包成了 Rust 的类型。下一篇离开单机文件,进入网络:同样是一层「看起来只是读写」的接口,但 TCP 连「一条消息到哪里结束」都不保证,这比文件系统的坑更隐蔽。
当天可以自己验证的练习:
- 写一个程序,把同一段内容分别用
fs::write和「临时文件 +sync_all+rename」写入,在写入过程中用另一个进程反复读,观察前者是否能读到空文件。 - 造一个 GBK 编码的文件,分别用
read_to_string和fs::read处理,记录两次的错误与字节内容。 - 在一个目录里创建 10 个文件,连续调用
read_dir十次,打印每次的顺序,确认它是否稳定。 - 把一篇的日志统计程序改成
BufReader流式版本,用 50 万行文件对比内存占用和耗时。 - 给原子替换加上「启动时清理
.tmp」的逻辑,故意在 rename 前杀进程,验证下次启动能清理干净。
如果这几条都亲手跑过,文件系统这一层基本就不会再出「莫名其妙」的问题了。