先讲一个真出现过的事故。一个服务启动时要把新配置写到 /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 保证「不存在才创建」,已存在就报错,这样名字冲突会立刻暴露而不是静默覆盖。创建成功后如果后续步骤失败,要负责把临时文件删掉,否则崩溃恢复时目录里会积一堆垃圾。

原子替换保证的是「不会读到半个文件」,不保证「不会丢已经成功的写」。如果 rename 之前断电,旧文件仍然完好,这是可接受的失败;如果 rename 之后断电但目录项没落盘,可能回到旧版本。要更强的一致性,需要文件系统或数据库层的事务,不是多写几行代码能解决的。

追加、截断与打开模式

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 连「一条消息到哪里结束」都不保证,这比文件系统的坑更隐蔽。

当天可以自己验证的练习:

  1. 写一个程序,把同一段内容分别用 fs::write 和「临时文件 + sync_all + rename」写入,在写入过程中用另一个进程反复读,观察前者是否能读到空文件。
  2. 造一个 GBK 编码的文件,分别用 read_to_string 和 fs::read 处理,记录两次的错误与字节内容。
  3. 在一个目录里创建 10 个文件,连续调用 read_dir 十次,打印每次的顺序,确认它是否稳定。
  4. 把一篇的日志统计程序改成 BufReader 流式版本,用 50 万行文件对比内存占用和耗时。
  5. 给原子替换加上「启动时清理 .tmp」的逻辑,故意在 rename 前杀进程,验证下次启动能清理干净。

如果这几条都亲手跑过,文件系统这一层基本就不会再出「莫名其妙」的问题了。