Go fs.Sub 怎样把文件系统限制在子目录

在资源目录越来越大时，我更愿意让每个模块拿到自己的 fs.FS 视图，而不是把项目根目录到处传递。Go 的 fs.Sub 正好解决这个问题：它以一个已有文件系统和子目录名为输入，返回从该子目录开始解释相对路径的新视图。

最小用法是 sub, err := fs.Sub(fsys, "assets")。之后在 sub 上读取 config/app.yaml，实际对应根文件系统里的 assets/config/app.yaml。需要记住，这是一层逻辑路径边界，不是操作系统级的 chroot 或安全沙箱。

先把根文件系统转换成子树视图

典型场景是把磁盘目录交给 os.DirFS，再把应用真正需要的资源目录交给模块。模块只接收子视图，调用者不必把 assets 前缀重复传下去。

package main

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

func readAppConfig() error {
    // 先把磁盘根目录转换成 fs.FS，避免模块依赖具体文件对象。
    root := os.DirFS("/srv/myapp")

    // 子视图的根是 assets；错误必须保留给调用者处理。
    assets, err := fs.Sub(root, "assets")
    if err != nil {
        return fmt.Errorf("创建 assets 子视图: %w", err)
    }

    // 这里使用子视图内的相对路径，不再重复写 assets/ 前缀。
    data, err := fs.ReadFile(assets, "config/app.yaml")
    if err != nil {
        return fmt.Errorf("读取应用配置: %w", err)
    }
    fmt.Printf("配置字节数: %d\\n", len(data))
    return nil
}

func main() {
    if err := readAppConfig(); err != nil {
        fmt.Println(err)
    }
}

这段代码的关键不是少写几个字符，而是把路径解释权收敛到模块边界。模块只需要知道自己拥有 config/app.yaml，以后把资源从磁盘换成 embed.FS 或测试用的 fstest.MapFS 时，读取代码也不必改变。

按子视图的相对路径读取文件

fs.Sub 返回的对象仍然满足 fs.FS。因此 fs.ReadFile、fs.ReadDir、fs.WalkDir 和 fs.Glob 都可以继续使用。路径必须是 fs 包规定的相对、斜杠分隔路径；./config、../secret、开头带斜杠的路径都不应该作为正常输入。

子视图还会重新表达错误路径。比如根文件系统中真正访问的是 assets/config/missing.yaml，调用者看到的 fs.PathError.Path 会尽量回到子视图里的 config/missing.yaml。这样日志更贴近当前模块的责任边界。

处理目录参数和不存在目录

fs.Sub 首先要求 dir 是有效的 fs 路径。传入 "." 时，它直接返回原来的文件系统；传入带有 ..、空元素或绝对路径形式的字符串，会返回路径错误。另一个容易忽略的点是：创建子视图时不会检查目录当前是否存在，真正打开或读取时才可能得到不存在错误。

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

func subFS(root fs.FS, dir string) (fs.FS, error) {
    // 先创建视图；目录不存在不是这里的必然错误。
    child, err := fs.Sub(root, dir)
    if err != nil {
        var pathErr *fs.PathError
        if errors.As(err, &pathErr) {
            return nil, fmt.Errorf("子目录参数无效: %w", err)
        }
        return nil, err
    }

    // 读取时再暴露目录不存在或权限等实际访问错误。
    if _, err := fs.Stat(child, "."); err != nil {
        return nil, fmt.Errorf("子目录不可用: %w", err)
    }
    return child, nil
}

示例中的 fs.Stat(child, ".") 是业务方主动选择的“现在就确认”动作，不是 fs.Sub 自动完成的检查。若应用允许延迟加载，也可以只保存子视图，等第一次读取时再处理错误。

用嵌套 Sub 组织模块边界

当资源目录有多级模块时，可以连续调用 fs.Sub。第二次调用的路径是相对于第一次子视图的路径，因此更容易把公共资源和私有资源分成两个明确入口。

func loadPublicIcon(root fs.FS) ([]byte, error) {
    // 第一层把应用资源限制在 assets 子树。
    assets, err := fs.Sub(root, "assets")
    if err != nil {
        return nil, err
    }

    // 第二层继续收窄到 public；路径相对于 assets 解释。
    public, err := fs.Sub(assets, "public")
    if err != nil {
        return nil, err
    }

    // 业务函数只处理自己的 icon.svg，不感知上层目录前缀。
    return fs.ReadFile(public, "icon.svg")
}

这种写法适合稳定的模块边界：每层都只向下暴露自己负责的资源。代价是错误链会多一层包装，目录命名也要有文档约定；如果只是偶尔读取一次文件，不必为了形式上的分层反复创建视图。

区分逻辑隔离与安全隔离

fs.Sub 解决的是“这个模块看到哪些相对路径”的工程问题，不应被描述成防越权的安全机制。Go 官方说明指出，os.DirFS 下子目录内的符号链接可能指向外部目录；fs.Sub 不会改变这个事实。因此配置文件浏览器、插件运行时或不可信输入场景，不能仅凭 os.DirFS 加 fs.Sub 宣称已经完成强隔离。

可以把取舍记成三句话：

• 需要模块化路径和可替换的 fs.FS：使用 fs.Sub。
• 需要立刻确认目录是否可读：在创建视图后主动 fs.Stat(child, ".")。
• 需要操作系统级目录树约束：选择具备相应安全语义的机制，不把子视图当作 chroot。

常见问题

fs.Sub 的 dir 能写成绝对路径吗？

不能。fs 路径要求是 UTF-8、斜杠分隔的相对路径，根目录用 . 表示；绝对路径和包含 .. 的路径会触发无效路径错误。

fs.Sub 会在创建时判断子目录存在吗？

不会。它先创建路径视图，目录是否存在通常要到 Open、ReadDir 或主动 Stat 时才能确定。

fs.Sub 能防止符号链接访问外部目录吗？

不能把它当作这种保证。它是逻辑路径映射；涉及不可信文件系统内容时，需要另外选择满足安全约束的目录访问机制。

小结

fs.Sub 的核心价值是把根文件系统变成以某个子目录为根的 fs.FS 视图：调用者用子视图内的相对路径工作，模块边界更清楚，底层实现也更容易替换。工程上要同时记住有效路径、延迟存在性检查、嵌套视图和“不是 chroot”这四个边界。