Go io/fs 如何用 Sub 实现受限文件树：路径规范化与 Open 失败处理

如果一个 Go 服务只应该暴露静态目录中的某个子目录，直接把物理路径拼在请求参数后面很容易把边界弄模糊。更稳妥的做法是先用 fs.Sub 得到受限文件树，再让 fs.ValidPath 检查相对路径，最后调用 fs.Open；这样“从哪个根目录找”和“请求的路径是否合法”是两件清楚的事。

fs.Sub 负责缩小可见文件树，fs.ValidPath 负责判断相对路径格式，fs.Open 负责报告目标是否真的存在。三步不能用一次字符串拼接替代。

先把文件访问边界收窄到 static/docs

示例假设磁盘目录是 /srv/app/public，服务只允许读取其中的 static/docs。os.DirFS 以物理目录作为文件系统根，fs.Sub 再把可见范围裁到 static/docs。后续的 Open 只接收这个受限文件树，不再接触原始磁盘路径。

package main

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

func docsFS() (fs.FS, error) {
    publicFS := os.DirFS("/srv/app/public")
    return fs.Sub(publicFS, "static/docs")
}

func main() {
    docs, err := docsFS()
    if err != nil {
        panic(err)
    }
    f, err := docs.Open("guide/start.html")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer f.Close()
    fmt.Println(f.Name())
}

这里有一个容易忽略的关系：fs.Sub 返回的新文件系统把 static/docs 隐藏在根后面，所以调用方只需要传 guide/start.html。如果把 static/docs/guide/start.html 再传一次，路径语义就错了。文件系统切换与文件打开之间的调用链如下图所示。

用 fs.ValidPath 先挡住不合格的请求路径

fs.FS 使用斜杠分隔的相对路径。空字符串、以斜杠开头的绝对样式、包含 . 或 .. 路径元素的输入，都不应该直接交给 Open。检查时不要先把用户输入拼到 /srv/app/public 上，而是先把它当作文件系统内部路径判断。

func openDoc(docs fs.FS, name string) (fs.File, error) {
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid document path %q", name)
    }
    return docs.Open(name)
}

func loadStart(docs fs.FS) error {
    file, err := openDoc(docs, "guide/start.html")
    if err != nil {
        return err
    }
    defer file.Close()
    return nil
}

这段代码把两个判断分开：fs.ValidPath 返回 false 时，问题在输入格式；它返回 true 之后，docs.Open 仍可能返回“文件不存在”或底层读取错误。不要把所有错误都改写成“路径非法”，否则调用方无法区分用户输入和部署文件缺失。

把三类失败映射成稳定的调用方结果

在 HTTP handler 中，建议至少保留三类结果：路径不合法返回 400，合法但文件不存在返回 404，其他打开或读取错误记录日志并返回 500。实际项目可以根据日志策略细分，但不要依靠错误字符串做唯一判断。

func serveDoc(w http.ResponseWriter, docs fs.FS, name string) {
    if !fs.ValidPath(name) {
        http.Error(w, "bad document path", http.StatusBadRequest)
        return
    }

    file, err := docs.Open(name)
    if err != nil {
        if errors.Is(err, fs.ErrNotExist) {
            http.NotFound(w, nil)
            return
        }
        http.Error(w, "document unavailable", http.StatusInternalServerError)
        return
    }
    defer file.Close()
    http.ServeContent(w, nil, name, time.Time{}, file.(io.ReadSeeker))
}

上面的 handler 省略了类型适配和读取权限细节，重点是状态顺序：先校验，再打开，再区分 fs.ErrNotExist。如果文件系统实现不满足 io.ReadSeeker，应改用读取接口或缓存策略，而不是强行断言。

什么时候不该使用 fs.Sub

如果业务需要让用户在多个根目录之间切换，应该在业务层先完成根目录选择，再为每次请求传入正确的 fs.FS；不要把用户可控字符串直接作为 fs.Sub 的目录参数。若需要创建、删除或写入文件，fs.FS 的只读接口也不是合适的抽象，应选择明确支持写操作的实现并额外设计权限边界。

另外，fs.ValidPath 只验证文件系统路径格式，不会替你确认文件类型、大小或内容。HTML、压缩包和配置文件仍需在打开后做类型与容量限制。

常见问题：fs.Sub 与 fs.ValidPath 怎么配合

fs.Sub 会自动检查请求路径吗？

不会。fs.Sub 只负责从父文件系统得到一个子树，调用方仍应对外部传入的相对路径执行 fs.ValidPath，然后再调用 Open。

合法路径为什么仍可能 Open 失败？

路径格式合法只说明它符合 fs.FS 约定，目标可能不存在，或者底层实现遇到权限、IO 等错误。判断是否缺失时优先使用 errors.Is(err, fs.ErrNotExist)。

只传 guide/start.html 的好处是什么？

因为 docs 已经由 fs.Sub 固定到 static/docs，调用方只描述子树内的相对位置，物理根目录不会进入请求参数。

小结

这套组合的核心不是多写一个校验函数，而是让接口边界各司其职：os.DirFS 建立物理根，fs.Sub 缩小可见树，fs.ValidPath 过滤路径格式，fs.Open 给出实际文件结果。顺序固定下来后，错误映射、日志和后续测试都会更容易维护。