Go io/fs用 Sub 限定目录视图的路径边界

我在把模板目录交给不同组件时，最容易留下的隐患不是遍历代码，而是路径前缀到处泄漏：一会儿传 templates/base.html，一会儿又把宿主机绝对路径拼进去。Go 的 io/fs 提供了更稳妥的切法：先用 fs.Sub 从一个 fs.FS 中取出子树，业务层随后只面对这个子树的相对路径。

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

fs.Sub 解决的是路径前缀，不是复制目录

fs.Sub(fsys, dir) 返回 dir 对应的子树。假设原文件系统里有 templates/base.html，得到 views, _ := fs.Sub(fsys, "templates") 后，应对 views 打开 base.html。它改变的是调用方看到的根，不会把文件复制到另一处。

这里的路径遵守 io/fs 规则：使用 UTF-8、正斜杠和不带根的层级名，根目录写成 .。dir 为 . 时，Sub 直接返回原来的 fsys；它也不会为了确认目录存在而提前扫描，真正访问文件时才会暴露缺失问题。

让子视图里的遍历和读取保持一致

我更愿意把目录切分放在适配层，把遍历函数写成只接收 fs.FS。这样 WalkDir、ReadFile 和测试数据都使用同一套相对路径，后续换成嵌入资源时不必改业务逻辑。

package main

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

// listTemplates 只接收子树视图，调用方无需知道外层目录名。
func listTemplates(root string) error {
    source := os.DirFS(root)
    views, err := fs.Sub(source, "templates")
    if err != nil {
        // dir 不符合 io/fs 路径规则时，在这里保留原始错误。
        return fmt.Errorf("创建模板视图: %w", err)
    }

    return fs.WalkDir(views, ".", func(path string, entry fs.DirEntry, walkErr error) error {
        // 回调错误必须先处理，避免把不完整遍历误当成成功。
        if walkErr != nil {
            return walkErr
        }
        // 目录只继续向下，文件名使用子视图内的相对路径。
        if entry.IsDir() {
            return nil
        }
        if len(path) >= 5 && path[len(path)-5:] == ".html" {
            data, err := fs.ReadFile(views, path)
            if err != nil {
                // 读取失败时停止，让上层决定是否重试或降级。
                return fmt.Errorf("读取 %s: %w", path, err)
            }
            fmt.Printf("%s: %d bytes\n", path, len(data))
        }
        return nil
    })
}

这段代码的关键不是递归，而是所有操作都绑定到同一个 views。回调收到的 index.html，就用同一个视图读取；如果把它拿去给原始 source，路径前缀会丢失。WalkDir 默认按字典序访问目录，目录中的符号链接也不会被自动跟随。

把非法路径、缺失目录和安全边界分开判断

fs.Sub 不是任意字符串截取器。像 ../secret、templates/../secret 这样的名称违反 ValidPath 语义，应在边界处拒绝；而合法但尚不存在的 templates，不能简单理解为 Sub 当场报错，因为它不会检查目录当前是否存在。

另外，子视图只约束了 io/fs 名称的映射。官方文档特别提醒：基于 os.DirFS 的实现不会阻止子目录里的符号链接指向外部位置，所以 fs.Sub 不能当作操作系统级隔离或 chroot。需要防止链接逃逸时，应采用具备目录树约束能力的方案，并把这项安全需求和普通路径整理分开评估。

同一套代码可以接磁盘、embed.FS 和 MapFS

os.DirFS 适合把真实目录转换成 fs.FS；embed.FS 和 fstest.MapFS 也能提供相同接口。业务函数只约定“传入的 FS 已经是目标子树”，就能在单元测试中用固定文件覆盖嵌套路径、空目录和缺失文件分支。

// readIndex 约定 fsys 的根已经是页面目录。
func readIndex(fsys fs.FS) ([]byte, error) {
    // 使用 io/fs 路径，不拼接宿主机分隔符或绝对路径。
    data, err := fs.ReadFile(fsys, "index.html")
    if err != nil {
        // 让调用方区分文件不存在与其他底层错误。
        return nil, fmt.Errorf("读取 index.html: %w", err)
    }
    return data, nil
}

生产代码可以在入口处执行一次 fs.Sub，然后把返回值传给多个小函数。这样前缀只出现一次，单元测试也不必创建真实目录。需要记住：Sub 的价值是收敛命名空间和减少耦合，不是提升底层文件系统的权限控制能力。

常见问题

为什么 Sub 之后要从 . 或 base.html 开始访问？

因为返回值已经把指定目录视为新的根。继续传 templates/base.html 会多加一层前缀，通常会得到不存在错误。

Sub 会递归复制目录内容吗？

不会。它返回一个 FS 视图，访问仍由底层文件系统完成；目录不存在也不会在 Sub 调用时被预先扫描。

可以用 Sub 防止符号链接越界吗？

不能单靠它保证。对于 os.DirFS，子目录中的符号链接可能指向外部位置，安全隔离需要更专门的目录约束机制。

什么时候把 Sub 放在业务函数内部？

通常放在适配层更清楚：先确定 FS 根，再把子视图传给遍历、读取和渲染函数，避免每个函数重复处理前缀。