Go io/fs遍历虚拟文件系统的接口用法

我第一次把本地模板目录换成 embed.FS 时，真正需要改的不是业务逻辑，而是“遍历目录”这一层。Go 的 io/fs 已经把文件系统抽象成统一的 fs.FS 接口：宿主目录可以用 os.DirFS，嵌入资源可以直接使用 embed.FS，测试还可以用 fstest.MapFS。遍历代码只接收 fs.FS，就不必为每种来源重复递归。

官方资料：https://pkg.go.dev/io/fs

先把虚拟文件系统看成一个 FS 接口

fs.FS 的最小约束只有 Open(name string) (fs.File, error)。上层函数不需要知道数据来自磁盘、二进制嵌入区还是内存映射，只要遵守 io/fs 的路径规则即可。这里的路径不是操作系统路径：它只能是类似 templates/base.html 的相对层级名，根目录用 . 表示。

这个抽象的价值在于替换来源时，遍历函数的签名不变。把“打开文件”和“处理文件内容”留给调用方，代码会比接收具体的 *os.File 更容易测试。

WalkDir 遍历时要守住路径和符号链接边界

WalkDir 会回调根节点本身，并按字典序读取每个目录后继续访问。它把访问文件或目录时的错误交给回调处理，因此不要只在外层判断返回值。目录中遇到符号链接时默认不跟随；如果传入的 root 本身就是链接，则会遍历其目标。

package main

import (
    "fmt"
    "io/fs"
)

// listGoFiles 只依赖 fs.FS，磁盘、嵌入资源和测试文件系统都能复用。
func listGoFiles(fsys fs.FS) error {
    return fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
        // 访问失败时先返回错误，避免把不完整结果当成成功。
        if err != nil {
            return err
        }
        // 目录只负责继续遍历；这里不读取目录内容。
        if d.IsDir() {
            return nil
        }
        if d.Name() == "main.go" || len(d.Name()) > 3 && d.Name()[len(d.Name())-3:] == ".go" {
            fmt.Println(path)
        }
        return nil
    })
}

回调里的 path 是 io/fs 路径，例如 cmd/main.go，不是 C:\\work\\cmd\\main.go 或带根的 POSIX 路径。若某个目录无需继续向下，可以返回 fs.SkipDir；想结束整个遍历则返回 fs.SkipAll。这两个返回值表达的是遍历控制，不是业务错误。

用 DirEntry 做筛选和读取

WalkDir 先给出 fs.DirEntry，它适合做轻量筛选：Name 只有最后一级名称，IsDir 判断目录，Type 返回类型位。只有确实需要大小、修改时间或完整 FileInfo 时才调用 Info；如果条目已经被删除或改名，Info 可能返回 fs.ErrNotExist。

遍历与读取可以保持两段职责。得到路径后，用 fs.ReadFile(fsys, path) 读取内容，它会优先使用文件系统提供的 ReadFileFS 优化接口。不要手工用 filepath.Join 把回调路径拼成宿主路径，否则换到 embed.FS 时很容易破坏抽象。

把真实目录和嵌入资源统一到同一套代码

真实目录可用 os.DirFS(root) 转成 fs.FS。如果业务只允许访问某个子目录，可以先调用 fs.Sub(fsys, "templates")，之后对返回的子文件系统使用相对于该子树的路径。这样业务层只看到 base.html，无需携带外层目录名。

package main

import (
    "fmt"
    "io/fs"
    "os"
)

// readTemplate 将目录适配和内容读取固定在 io/fs 路径语义内。
func readTemplate(root string) ([]byte, error) {
    source := os.DirFS(root)
    // Sub 返回 templates 子树；name 仍然使用正斜杠和相对路径。
    templates, err := fs.Sub(source, "templates")
    if err != nil {
        return nil, fmt.Errorf("切分模板目录: %w", err)
    }
    // ReadFile 负责打开、读取和关闭文件，调用方只处理结果或错误。
    return fs.ReadFile(templates, "base.html")
}

同一个 listGoFiles 也可以接收 embed.FS。测试时则把文件放进 fstest.MapFS，用固定数据覆盖空目录、嵌套目录和读取失败等分支。需要注意的是，fs.Sub 只做路径视图转换，不是 chroot 安全边界；如果场景需要限制符号链接逃逸，应使用更合适的目录约束机制。

常见问题

WalkDir 为什么从 . 开始，而不是传绝对路径？

因为 fs.FS 使用统一的相对 slash 路径。磁盘根目录先用 os.DirFS 适配，遍历时传 . 或该文件系统内部的相对目录。

为什么回调里不能直接跟随符号链接？

这是 WalkDir 的默认边界，用来避免目录树循环和意外扩大访问范围。需要链接目标信息时，应根据文件系统是否实现相关接口单独处理。

字典序遍历会不会影响大目录性能？

会。为了保证确定性，WalkDir 在继续访问目录前需要读入整个目录；超大目录要评估内存和排序成本，不能只看递归写法是否简短。

什么时候应该调用 DirEntry.Info？

只有筛选确实依赖大小、权限或修改时间时再调用。普通的目录判断和扩展名筛选，用 IsDir 与 Name 就够了。