Go testing/fstest发现 FS 实现的路径错误的检查方法

自定义 fs.FS 出现“文件不存在”“目录读取失败”或期望文件缺失时，先把实现交给 testing/fstest.TestFS，不要只对某一个文件调用 fs.ReadFile。它会从根目录开始检查目录枚举、文件打开、读取结果和路径集合；再结合报错中的路径，就能判断问题是在路径规范、Open，还是 ReadDirFile。

官方资料：https://pkg.go.dev/testing/fstest/

一、先识别 TestFS 报告的路径信号

fstest.TestFS(fsys, expected...) 的第一个参数是被测文件系统，后面的字符串是“至少应该存在”的路径。没有传 expected 时，TestFS 会把非空 FS 判为错误；传入嵌套路径时，它还会通过 fs.Sub 检查子树。因此，报告中的路径不是装饰信息，而是定位实现边界的线索。

常见信号可以这样分层：Open: file does not exist 多半是路径映射或根目录处理错误；ReadDir 相关错误说明目录没有正确返回条目；Open returned File type ... not a fs.ReadDirFile 则表示目录打开后缺少目录读取能力；expected but not found 表示实现返回的树与测试契约不一致。

二、建立最小 TestFS 检查

先固定一棵小目录树，覆盖根目录、一级目录和文件。下面的测试故意把 expected 写成 fs.FS 语法，而不是操作系统的绝对路径：

func TestAssetsFS(t *testing.T) {
	// MapFS 用少量稳定条目构造测试树，便于隔离路径契约。
	fsys := fstest.MapFS{
		"assets/config.json": {Data: []byte(`{"mode":"test"}`)},
		"assets/readme.txt":  {Data: []byte("hello")},
	}

	// expected 同时覆盖目录和文件，缺少任一条目都会让测试失败。
	if err := fstest.TestFS(fsys,
		"assets",
		"assets/config.json",
		"assets/readme.txt",
	); err != nil {
		t.Fatal(err) // 保留 TestFS 的聚合错误，方便定位具体路径。
	}
}

这个检查首先验证根目录可打开、目录可枚举、文件能读取，再对 expected 做存在性比较。自定义实现接入时，把 fstest.MapFS 换成自己的类型即可。不要在 TestFS 执行期间修改底层 map 或缓存，否则会把并发变化误判成路径问题。

三、修正路径实现并覆盖嵌套目录

io/fs 的路径是 UTF-8、无根、用斜杠分隔的相对路径；只有根目录允许写成 .。如果适配层直接把 filepath.Join 的结果当作 FS 名称，Windows 反斜杠、开头的斜杠或多余的 .. 都可能让 TestFS 发现不一致。适配层应先把外部路径转换为 FS 语法，再映射到真实存储。

嵌套路径尤其要检查两个边界：Open("assets") 必须表现为目录，且返回值应支持目录读取；fs.Sub(fsys, "assets") 后，子 FS 中的 "readme.txt" 应能找到，不能仍要求调用方传入 "assets/readme.txt"。这类前缀重复通常会表现为子树里的 expected 路径缺失。

修复时建议保留一层规范化函数，并让 Open、ReadDir、Stat 共用它；不要只修某一个入口。目录返回值还要正确关闭，错误应尽量保留底层路径信息，便于用 errors.Is 或 errors.As 分类。

四、回滚路径与回归确认

如果新适配层上线后 TestFS 失败，先回退到上一个路径转换版本，保留失败用例中的具体名称，再逐项恢复。回归集至少包含根目录 .、一级目录、嵌套文件、空目录、非法的前导斜杠和反斜杠输入。每次修改只改变一类边界，避免把“路径修好了”和“目录枚举修好了”混在一个提交里。

运行前确认 FS 内容在检查期间不变；运行后确认 go test ./... 中的 TestFS 失败能直接指出路径。若实现还支持符号链接，再单独覆盖其 Lstat 语义，不要把符号链接跟普通文件路径混为一谈。

相关问题

expected 路径应该写绝对路径吗？

不应该。fs.FS 使用相对、无根、斜杠分隔的路径；根目录是 .。绝对路径属于宿主文件系统语义，直接传入会掩盖适配层错误。

TestFS 能替代所有业务测试吗？

不能。它适合验证 FS 接口契约和基础行为；业务层仍要测试权限、缓存失效、资源生命周期以及应用对文件内容的解释。