Go fstest.TestFS 为什么会报告实现不符合约定

Go 的 fstest.TestFS 报告“实现不符合约定”时，先不要急着改测试参数。它会从根目录开始遍历文件系统，检查路径合法性、目录读取、文件打开和内容重复读取，还会核对 expected 中列出的路径。最稳妥的排查顺序是：先缩小到一个文件，再看目录元数据，最后检查 fs.Sub 和并发修改。

TestFS 实际检查的是一组 fs.FS 约定

这类报错都不是fstest.TestFS故意找茬，本质是你写的自定义FS没有对齐Go标准库fs包定义的全部隐性约定，常见坑点基本都集中在路径处理、文件夹语义、错误返回值这几个核心维度。

TestFS(fsys, expected...) 接收的是 fs.FS，并不要求实现必须是磁盘文件系统。它会打开“.”，读取目录，再逐个打开发现的文件；如果传入了期望路径，还会确认这些路径存在。没有传入期望路径时，发现任何文件都会报错，这正适合验证一个应该为空的测试文件系统。

用 MapFS 做最小复现时，文件键使用斜杠分隔的相对路径，不要写成操作系统绝对路径：

package fstestdemo

import (
    "testing"
    "testing/fstest"
)

func TestLayout(t *testing.T) {
    fsys := fstest.MapFS{
        // 子文件足以让 MapFS 合成 config 目录。
        "config/app.yaml": {Data: []byte("port: 8080\n")},
    }
    // expected 写逻辑路径，列出目录可让失败信息更容易定位。
    if err := fstest.TestFS(fsys, "config", "config/app.yaml"); err != nil {
        t.Fatal(err)
    }
}

先排路径与目录，再排文件内容

第一类错误集中在 Open：实现接受了以斜杠开头、包含 ..、重复斜杠或反斜杠的名称。自定义文件系统应使用 fs.ValidPath 判断名称，并返回带有底层原因的 fs.PathError。第二类错误是目录被当成普通文件返回，或 ReadDir 没有返回稳定、可读的目录项。

如果实现显式登记目录，记得设置 Mode: fs.ModeDir | 0555；如果只登记 a/b.txt，像 MapFS 一样合成 a 也可以。排查时把期望集合缩成一个叶子文件和它的父目录，能立刻区分“路径不存在”和“目录行为不正确”。

文件能打开，不代表满足完整契约

TestFS 还会重新打开文件并比较读取结果。常见自定义实现只在第一次 Read 时正确，第二次打开却复用了已经到末尾的 reader；或者 Close 后仍允许读取。修复时让每次 Open 都创建独立的文件句柄和读取游标，并让 Stat 的名称、大小、目录位与实际内容一致。

按错误层次修复自定义文件系统

fstest.TestFS 通过后，再看实现是否真的适合生产场景。它关注的是 fs.FS 的可观察约定，并不会替你验证后端权限、网络一致性或业务级缓存策略。符号链接实现了 fs.ReadLinkFS 时，还要保证 Lstat 描述的是链接本身；测试不会把链接当成普通文件无限跟随。

另一个容易忽略的边界是并发：测试遍历期间不能修改底层 map。对于 MapFS，文档明确说明读操作直接访问 map；并发写入会形成数据竞争。若测试需要变更文件，先结束本轮 TestFS，再复制或重建文件系统。

相关问题

expected 只写文件，不写父目录可以吗？

可以。只要实现能正确打开文件并枚举父目录，TestFS 会检查到文件；写上父目录则更容易在错误信息中定位层级。

为什么空的 expected 反而报发现文件？

这是设计行为：没有 expected 时，TestFS 将目标视为空文件系统。要测试非空内容，应明确列出至少一个期望路径。

MapFS 适合模拟大型目录吗？

不适合。它打开或读取目录时需要遍历 map，适合小型测试数据；大型目录应使用更贴近真实后端的实现或专门的测试夹具。