Go io/fs 怎么用统一接口读取磁盘和嵌入文件

项目从“读取配置模板”开始时，直接写 os.ReadFile 很自然；等模板要随二进制一起发布，又换成 embed.FS，路径拼接、错误处理和测试往往各写一套。更稳妥的做法是让业务函数只接收 io/fs 的 fs.FS，把磁盘目录或嵌入文件当成不同的数据源。

结论是：用 fs.ReadFile(fsys, name) 统一读取，磁盘侧传入 os.DirFS(dir)，嵌入侧传入 embed.FS；如果嵌入内容多了一层目录，再用 fs.Sub 把根目录调整到业务真正使用的位置。

先把读取动作收敛到 fs.FS

fs.FS 只有一个最小要求：实现 Open(name string) (fs.File, error)。标准库的 fs.ReadFile 会优先使用实现提供的快速读取能力，否则打开文件、读取内容并关闭文件，所以调用方无需知道底层是磁盘、内存映射还是嵌入资源。

这里的 name 不是操作系统路径：它应使用斜杠分隔，不能以斜杠开头或结尾，也不能包含 ..。先把“资源相对路径”约定下来，后面切换数据源就不会把绝对路径误传进来。

package main

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

// readText 只关心文件系统接口，不关心资源来自磁盘还是二进制。
func readText(fsys fs.FS, name string) (string, error) {
    // fs.ReadFile 成功时返回完整内容，结尾的 io.EOF 不会作为错误暴露。
    data, err := fs.ReadFile(fsys, name)
    if err != nil {
        // 保留 ErrNotExist 语义，让上层可以区分缺文件和其他 I/O 错误。
        if errors.Is(err, fs.ErrNotExist) {
            return "", fmt.Errorf("资源 %q 不存在: %w", name, err)
        }
        return "", fmt.Errorf("读取资源 %q 失败: %w", name, err)
    }
    return string(data), nil
}

这个函数也很容易用 testing/fstest.MapFS 做单元测试。测试只验证资源路径和业务结果，不必创建临时目录，说明抽象确实落在了正确的位置。

用 os.DirFS 接入磁盘目录

需要读取开发机或服务器上的目录时，先把目录变成文件系统根：

package main

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

func main() {
    // DirFS 把这个目录作为 fs.FS 的根，业务代码只传相对资源名。
    diskFS := os.DirFS("./config")
    text, err := readText(diskFS, "app.yaml")
    if err != nil {
        panic(err)
    }
    fmt.Println(text)

    // 目录枚举同样使用统一的斜杠路径。
    entries, err := fs.ReadDir(diskFS, ".")
    if err != nil {
        panic(err)
    }
    for _, entry := range entries {
        fmt.Println(entry.Name())
    }
}

os.DirFS("./config") 的重点是“改变根”，不是把字符串简单拼接成绝对路径。生产代码仍要明确目录来源和权限；官方文档特别提醒，目录里的符号链接可能指向根目录之外，DirFS 不是 chroot 式的安全隔离。若需求是严格限制逃逸，应使用更适合该安全目标的目录约束能力。

用 embed.FS 接入嵌入文件

把模板或静态资源编译进程序时，声明一个 embed.FS。下面假设项目中存在 assets/app.yaml：

package main

import (
    "embed"
    "fmt"
)

//go:embed assets
var embeddedFS embed.FS

func main() {
    // embed.FS 保留了 assets 这一层目录，所以读取名也要带上它。
    text, err := readText(embeddedFS, "assets/app.yaml")
    if err != nil {
        panic(err)
    }
    fmt.Println(text)
}

这就是最容易踩到的差异：磁盘例子把 ./config 当根，嵌入例子却把匹配到的 assets 目录保留在 FS 路径中。可以用 fs.Sub 把两边都整理成“根下直接有 app.yaml”：

// subFS 将资源根固定在 assets，调用方不再感知目录前缀。
assetFS, err := fs.Sub(embeddedFS, "assets")
if err != nil {
    panic(err)
}
text, err := readText(assetFS, "app.yaml")
if err != nil {
    panic(err)
}
fmt.Println(text)

统一接口落地时的四个边界

如果文件可能很大，不要为了追求“统一”而强行调用 fs.ReadFile 把全部内容放进内存，可以改用 fsys.Open 后流式读取，并在同一函数内 defer file.Close()。统一的是接口，不是每种资源都必须使用同一种读取策略。

常见问题

os.DirFS 和 embed.FS 能直接替换吗？

能，前提是传入的资源名在两个 FS 中都有效。最常见的差异是嵌入目录前缀，先用 fs.Sub 调整根目录即可。

为什么传入 /app.yaml 会失败？

io/fs 使用无根、斜杠分隔的路径，/app.yaml 不是合法的 FS 名称，应传入 app.yaml。

把读取函数依赖收敛到 fs.FS 后，开发环境可以使用 os.DirFS，发布版本可以切到 embed.FS，测试还可以接入 fstest.MapFS。资源根和路径规则一旦固定，后续切换就只发生在组装层，而不是散落在业务代码里。