Go fstest.MapFS 怎么测试依赖 fs.FS 的组件

测试依赖 fs.FS 的组件时，最直接的做法是把真实磁盘或嵌入资源换成 fstest.MapFS。组件仍然只接收 fs.FS，测试则用一张内存 map 精确声明文件名、内容和权限，不需要临时目录，也不会受工作目录影响。

官方文档：https://pkg.go.dev/testing/fstest#MapFS

最小可用结构是：组件构造参数保存一个 fs.FS，业务方法用 fs.ReadFile、fs.ReadDir 等辅助函数读取；测试把 fstest.MapFS 传进去，再分别断言成功结果与错误类型。

目标和边界：先让组件只依赖 fs.FS

fstest.MapFS 适合测试“文件系统的使用者”。如果组件内部直接调用 os.ReadFile，测试就无法替换数据来源；先把依赖收口为 fs.FS，生产环境可以传 os.DirFS 或 embed.FS，测试环境再传 MapFS。

下面以读取 JSON 配置的组件为例。它只负责读取、解析和检查必填字段，不知道文件来自磁盘、嵌入资源还是内存。

package config

import (
    "encoding/json"
    "fmt"
    "io/fs"
)

type Config struct {
    Name string `json:"name"`
    Port int    `json:"port"`
}

type Loader struct {
    Files fs.FS
}

func (l Loader) Load(name string) (Config, error) {
    // 通过 fs.FS 读取，测试时可以注入内存文件系统
    data, err := fs.ReadFile(l.Files, name)
    if err != nil {
        return Config{}, fmt.Errorf("read config %q: %w", name, err)
    }

    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        // 保留文件名，便于定位是哪份测试数据损坏
        return Config{}, fmt.Errorf("decode config %q: %w", name, err)
    }
    if cfg.Name == "" {
        return Config{}, fmt.Errorf("config %q: name is required", name)
    }
    return cfg, nil
}

全流程总览：把文件系统变成可替换依赖

这个工作流只有一个稳定边界：fs.FS。生产代码负责选择真实来源，测试代码负责组装输入。只要业务组件不向下依赖具体实现，同一套读取逻辑就能在不同来源上复用。

阶段拆解：一张 MapFS 表覆盖三类结果

MapFS 的类型是 map[string]*fstest.MapFile。键就是传给 Open 或 fs.ReadFile 的路径，值里的 Data 是文件内容。普通文件的 Mode 可以保持零值；只有需要显式目录、特殊权限或元数据时才填写。

package config

import (
    "errors"
    "io/fs"
    "testing"
    "testing/fstest"
)

func TestLoader_Load(t *testing.T) {
    tests := []struct {
        name    string
        files   fstest.MapFS
        path    string
        want    Config
        wantErr error
    }{
        {
            name: "读取有效配置",
            files: fstest.MapFS{
                // 键必须是 fs.ValidPath 接受的相对路径
                "configs/app.json": {Data: []byte(`{"name":"api","port":8080}`)},
            },
            path: "configs/app.json",
            want: Config{Name: "api", Port: 8080},
        },
        {
            name:    "文件不存在",
            files:   fstest.MapFS{},
            path:    "configs/missing.json",
            wantErr: fs.ErrNotExist,
        },
        {
            name: "JSON 无效",
            files: fstest.MapFS{
                // 用确定的坏数据触发解析分支
                "configs/app.json": {Data: []byte(`{"name":`)},
            },
            path: "configs/app.json",
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            loader := Loader{Files: tt.files}
            got, err := loader.Load(tt.path)

            if tt.wantErr != nil {
                // 包装错误仍可通过 errors.Is 判断底层原因
                if !errors.Is(err, tt.wantErr) {
                    t.Fatalf("Load() error = %v, want %v", err, tt.wantErr)
                }
                return
            }
            if tt.name == "JSON 无效" {
                if err == nil {
                    t.Fatal("Load() error = nil, want decode error")
                }
                return
            }
            if err != nil {
                t.Fatalf("Load() error = %v", err)
            }
            if got != tt.want {
                t.Fatalf("Load() = %#v, want %#v", got, tt.want)
            }
        })
    }
}

三个用例分别验证业务的三条主要分支：数据正确时返回配置；路径缺失时保留 fs.ErrNotExist；内容损坏时返回解析错误。测试不必创建、清理临时目录，输入也能直接写在用例旁边。

推荐流程：用 fs.Sub 对齐生产目录

生产代码经常把资源放在 configs/、templates/ 等子目录，再把该目录当作组件根目录。测试也可以先构造完整 MapFS，再通过 fs.Sub 截取相同边界，这样组件内只需要读取 app.json，路径规则与生产环境一致。

func TestLoaderWithSubFS(t *testing.T) {
    files := fstest.MapFS{
        "fixtures/app.json": {Data: []byte(`{"name":"worker","port":9000}`)},
    }

    // 把 fixtures 目录变成组件看到的根目录
    root, err := fs.Sub(files, "fixtures")
    if err != nil {
        t.Fatal(err)
    }

    got, err := (Loader{Files: root}).Load("app.json")
    if err != nil {
        t.Fatal(err)
    }
    if got.Name != "worker" || got.Port != 9000 {
        t.Fatalf("unexpected config: %#v", got)
    }
}

这种写法尤其适合生产环境使用 embed.FS 的组件：嵌入资源和测试数据都先裁出相同子树，再交给业务层，避免一边写 assets/app.json、另一边写 app.json。

路径和目录：最容易踩的四个边界

1. MapFS 的键不是操作系统绝对路径

应使用斜杠分隔的相对路径，如 configs/app.json。不要写 /configs/app.json、Windows 盘符或依赖当前工作目录的路径。MapFS 的 Open 会按 fs.ValidPath 规则处理名称。

2. 普通父目录通常无需显式声明

MapFS 可以根据 configs/app.json 自动合成 configs 父目录。如果要表示一个没有任何子文件的空目录，或要精确控制目录元数据，则需要显式加入目录项。

files := fstest.MapFS{
    // 空目录必须显式设置 ModeDir
    "empty": {Mode: fs.ModeDir | 0o555},
}

3. 不要一边读取一边修改底层 map

MapFS 的文件系统操作会直接读取这张 map。官方文档明确提醒：在文件系统操作进行时并发修改 map 会形成数据竞争。并行子测试如果需要不同状态，应给每个用例创建自己的 MapFS，不要共享后再临时增删键。

4. MapFS 适合小型测试夹具

打开或读取目录时可能需要遍历整张 map，因此它通常适合几百个条目以内的测试数据。需要模拟数万文件的性能测试时，应设计专用 fs.FS 实现或使用受控的临时目录，而不是把 MapFS 当作大型内存文件数据库。

常见误区：MapFS 和 TestFS 不是一回事

fstest.MapFS 是给组件提供测试数据的文件系统实现；fstest.TestFS 则用于检查“你自己实现的文件系统”是否符合 fs.FS 行为约定。测试 Loader 这类使用者时，重点是业务输入与输出，不需要对每个 MapFS 用例再调用 TestFS。

另一个边界是写入能力。fs.FS 本身是只读抽象，MapFS 也主要用于读取场景。若组件要创建、修改、删除文件，应另外定义最小写入接口，或在测试里使用 t.TempDir 配合真实文件操作，不要硬把写入职责塞进 fs.FS。

速查表

相关问题

MapFS 里必须写出所有父目录吗？

不必。存在子文件时，普通父目录会按需合成；只有空目录或需要自定义目录元数据时才显式声明。

为什么用 MapFS 后仍然报文件不存在？

先检查键是否是合法相对路径、组件是否经过 fs.Sub 改变了根目录，以及读取时是否多写或少写了目录前缀。

组件要同时支持磁盘和 embed.FS 怎么设计？

让构造函数接收 fs.FS，在程序入口选择 os.DirFS 或嵌入文件系统；组件内部不判断具体类型，测试再传 MapFS。

什么时候应该改用 t.TempDir？

当被测逻辑依赖写入、重命名、文件锁、操作系统权限或真实路径语义时，临时目录更合适；纯读取、遍历和解析通常优先使用 MapFS。