使用 fs.FS 抽象本地目录与嵌入资源的读取逻辑

要让同一套读取代码同时支持本地目录和编译进二进制的资源，关键不是在函数里判断“开发环境还是生产环境”，而是把参数改成 fs.FS。业务函数只接收一个文件系统和一个相对路径；开发时传 os.DirFS，发布时传 embed.FS 或它的子树视图。

官方文档：https://pkg.go.dev/io/fs

fs.FS 的最小接口只有 Open(name string)。读取整文件、遍历目录、匹配文件和解析模板都可以在这个边界之上工作，调用方不必知道数据来自磁盘、内存还是编译期嵌入。

把目录参数改成 fs.FS

旧代码常把“资源位置”和“读取规则”写在一起：函数接收目录字符串，使用 filepath.Join 拼出完整路径，再调用 os.ReadFile。一旦资源改为 go:embed，这种函数就只能复制一份，或者不断增加环境判断。

// 旧写法把业务读取逻辑固定在操作系统目录上
func LoadConfigFromDir(root, name string) ([]byte, error) {
    fullPath := filepath.Join(root, name)
    return os.ReadFile(fullPath)
}

更小的改动是让函数依赖 fs.FS。路径从操作系统路径变成文件系统内部的逻辑路径，具体根目录由调用方决定：

// 新写法只依赖统一文件系统接口
func LoadBytes(fsys fs.FS, name string) ([]byte, error) {
    data, err := fs.ReadFile(fsys, name)
    if err != nil {
        return nil, fmt.Errorf("读取资源 %q: %w", name, err)
    }
    return data, nil
}

fs.ReadFile 会优先使用文件系统提供的 ReadFile 能力；若实现只有最小的 Open，标准库会打开、读取并关闭文件。业务层因此可以使用便利函数，而不必要求每种资源来源都暴露相同的具体类型。

用一个读取函数接住不同文件系统

实际项目通常不会只返回字节。下面把 JSON 解析也放进读取边界，函数仍然只关心 fs.FS、逻辑路径和配置结构。

package config

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

type Config struct {
    AppName string `json:"app_name"`
    Port    int    `json:"port"`
}

func LoadConfig(fsys fs.FS, name string) (Config, error) {
    // 从调用方提供的虚拟文件系统读取配置
    data, err := fs.ReadFile(fsys, name)
    if err != nil {
        return Config{}, fmt.Errorf("读取配置 %q: %w", name, err)
    }

    var cfg Config
    // 解析失败时保留配置路径，方便定位具体资源
    if err := json.Unmarshal(data, &cfg); err != nil {
        return Config{}, fmt.Errorf("解析配置 %q: %w", name, err)
    }
    return cfg, nil
}

这个边界还能自然接入 testing/fstest.MapFS、压缩包文件系统或项目自己的只读实现。业务函数不需要增加新的分支，错误包装和解析规则也只维护一份。

开发环境接入 os.DirFS

os.DirFS(dir) 把一个操作系统目录映射为 fs.FS。传入 ./assets 后，业务层看到的根目录就是 assets 内部，不再写 assets/config/app.json，而是写 config/app.json。

func loadLocal() (Config, error) {
    // ./assets 成为虚拟根目录，内部统一使用斜杠路径
    local := os.DirFS("./assets")
    return LoadConfig(local, "config/app.json")
}

开发模式的优势是文件可直接修改，不必为了改一行模板或配置重新编译程序。需要热加载时，也应把“何时重新读取”放在业务或服务层，而不是塞进文件系统抽象本身。

如果给 DirFS 传相对目录，后续 os.Chdir 会影响它的根位置。服务程序更适合在启动时确定绝对目录，或确保运行期间不改变工作目录。

发布版本接入 embed.FS

embed.FS 是只读文件集合，实现了 fs.FS。嵌入表达式相对于当前 Go 源文件所在包目录解析，并使用正斜杠。若把整个 assets 树嵌入，资源名称默认仍带有 assets/ 前缀。

package resources

import (
    "embed"
    "io/fs"
)

// 把配置目录在编译阶段收进二进制文件
//go:embed assets/config/*.json
var builtIn embed.FS

func BuiltInFS() (fs.FS, error) {
    // 去掉 assets 前缀，让调用路径与 os.DirFS("./assets") 一致
    return fs.Sub(builtIn, "assets")
}

fs.Sub 返回一个以指定子目录为根的新 fs.FS。这样，本地和嵌入两种来源都能使用完全相同的 config/app.json，业务调用不必知道嵌入变量内部多了一层 assets。

func loadBuiltIn() (Config, error) {
    source, err := resources.BuiltInFS()
    if err != nil {
        return Config{}, fmt.Errorf("创建嵌入资源视图: %w", err)
    }
    // 读取路径与开发环境保持一致
    return LoadConfig(source, "config/app.json")
}

构建时每个 //go:embed 模式必须匹配至少一个文件或非空目录，否则构建会失败。这是编译阶段问题，不应在运行时静默降级到另一个目录。

统一虚拟根目录与路径规则

io/fs 的路径规则跨平台一致：名称是 UTF-8、非根路径、使用正斜杠分隔。除根目录可用 . 外，路径元素不能是空字符串、. 或 ..，路径也不能以斜杠开头或结尾。因此 C:\config\app.json、/config/app.json 和 config/../app.json 都不应作为 fs.FS 内部名称。

如果路径来自用户输入，可先用 fs.ValidPath 拒绝明显无效的名称，再决定业务是否允许该资源。不要对用户字符串调用 filepath.Clean 后就当作安全路径，因为操作系统路径清理与 fs.FS 的逻辑路径边界不是一回事。

迁移边界与最小测试

fs.FS 适合读取抽象，不提供统一写入接口。如果业务既要读取内置默认配置，又要写回用户配置，应把读和写分开：默认值从 fs.FS 读取，持久化仍由明确的文件、数据库或存储接口负责。

还要注意，os.DirFS 并不是 chroot。目录中的符号链接可能指向树外，fs.Sub 也不会改变这一安全边界。若目录内容不可信，并且必须约束访问不能逃离某个树，应采用 Go 当前提供的受约束根目录能力，而不是把 DirFS 当作安全沙箱。

抽象之后，测试不需要创建临时目录。fstest.MapFS 可以用内存映射构造同样的文件系统契约：

package config

import (
    "testing"
    "testing/fstest"
)

func TestLoadConfig(t *testing.T) {
    // 用内存文件系统提供最小测试资源
    source := fstest.MapFS{
        "config/app.json": {
            Data: []byte(`{"app_name":"demo","port":8080}`),
        },
    }

    cfg, err := LoadConfig(source, "config/app.json")
    if err != nil {
        t.Fatal(err)
    }
    // 同时核对文本字段和数字字段
    if cfg.AppName != "demo" || cfg.Port != 8080 {
        t.Fatalf("配置不符: %+v", cfg)
    }
}

迁移时可以按最小顺序处理：先把读取函数参数改为 fs.FS，再用 os.DirFS 保持现有本地行为，随后接入 embed.FS 与 fs.Sub，最后把磁盘测试替换为 MapFS。每一步都能独立检查，不需要一次重写全部资源代码。

常见问题

fs.FS 能直接写文件吗？

不能。标准 fs.FS 是最小读取接口，只定义 Open。需要写入时应额外设计自己的存储接口，不要把可写假设塞进通用读取函数。

为什么本地目录和嵌入资源的路径对不上？

通常是虚拟根不同。若本地使用 os.DirFS("./assets")，而嵌入树保留了 assets/ 前缀，就对嵌入文件系统调用 fs.Sub(fsys, "assets")，让两边都从 config/app.json 开始。

什么时候直接传 embed.FS，不需要 fs.Sub？

当业务路径本来就包含嵌入前缀，或者嵌入模式直接把所需文件放在文件系统根层时，可以直接传。选择标准不是少写一行代码，而是让各资源提供者暴露相同的逻辑目录结构。

错误还能判断文件不存在吗？

可以。保留 %w 包装后，调用方仍可用 errors.Is(err, fs.ErrNotExist) 判断底层错误，同时日志中还能看到具体操作和资源名称。