Go io/fs.ValidPath 如何约束嵌套资源名：从 embed.FS 到 fs.Sub

把模板、配置或静态资源编进 Go 二进制后，最容易忽略的不是文件能不能读，而是“资源名”到底由谁约束。embed.FS 遵循 io/fs 的命名约定，fs.Sub 可以把访问范围收窄到一个目录，而 fs.ValidPath 负责判断传入名称是否是合法的相对路径。

先用 fs.ValidPath 拦住空串、绝对路径和带 .. 的名称，再用 fs.Sub 固定资源根目录；读取失败时保留原始错误，不要把非法路径当成普通缺文件处理。

资源名不是操作系统路径：先确认 io/fs 的边界

io/fs 使用路径名访问文件，但它要求路径是相对的、使用斜杠分隔，并且不能包含空元素或父目录跳转。fs.ValidPath 返回布尔值，适合放在接收用户输入、配置字段或模板名称的入口处。

下面这些名字可以作为资源名：index.html、config/app.yaml。空字符串、/etc/hosts、../secret 和带双斜杠的名称则不应直接交给文件系统读取。这里的判断是 io/fs 规范判断，不等同于当前操作系统上的路径清理。

最小用法：把 embed.FS 的目录缩成一个子文件系统

假设项目中有 assets/config/app.yaml。使用 embed.FS 时，业务代码可以先通过 fs.Sub 取得 assets 子树，后续只接收相对于该子树的资源名。

package main

import (
    "embed"
    "fmt"
    "io/fs"
    "log"
)

//go:embed assets
var embedded embed.FS

func main() {
    assets, err := fs.Sub(embedded, "assets")
    if err != nil {
        log.Fatal(err)
    }

    name := "config/app.yaml"
    if !fs.ValidPath(name) {
        log.Fatal("invalid resource name")
    }

    data, err := fs.ReadFile(assets, name)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(len(data))
}

这里的调用链是 embed.FS 提供文件树，fs.Sub 固定 assets 边界，fs.ValidPath 检查相对资源名，最后再读取 config/app.yaml。子文件系统不会把名称改写成操作系统绝对路径，业务层仍应把它当作 io/fs 名称处理。

图中的四个节点都对应上面的真实代码：embed.FS、fs.Sub、fs.ValidPath 和 config/app.yaml。它们表达的是资源根收窄和名称校验的先后关系，不是操作系统路径转换。

参数边界：合法路径不代表文件一定存在

fs.ValidPath 只回答“名字是否符合约定”，不会检查文件是否存在，也不会判断它是不是目录。即使 fs.ValidPath(name) 为真，fs.ReadFile 仍可能返回不存在、权限或读取过程中的错误。

一个更稳妥的入口可以把两类失败分开：名称非法时直接返回参数错误；名称合法但打开失败时保留 fs.ReadFile 的错误上下文。这样日志和调用方才能区分输入问题与资源部署问题。

func readAsset(root fs.FS, name string) ([]byte, error) {
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid resource name %q", name)
    }
    data, err := fs.ReadFile(root, name)
    if err != nil {
        return nil, fmt.Errorf("read %q: %w", name, err)
    }
    return data, nil
}

如果调用方需要持续读取而不是一次性读完，也可以改用 root.Open(name)，但校验位置不应后移到打开之后。先校验，再打开，能让错误分类稳定下来。

把四类边界写进测试：空串、绝对路径和父目录

资源名测试不必依赖真实操作系统目录。用 fstest.MapFS 放入一个合法文件，就能分别验证校验函数和读取函数的责任边界。

func TestReadAsset(t *testing.T) {
    root := fstest.MapFS{
        "config/app.yaml": &fstest.MapFile{Data: []byte("port: 8080\n")},
    }

    got, err := readAsset(root, "config/app.yaml")
    if err != nil || string(got) != "port: 8080\n" {
        t.Fatalf("readAsset() = %q, %v", got, err)
    }

    for _, name := range []string{"", "/config/app.yaml", "../config/app.yaml", "config//app.yaml"} {
        if _, err := readAsset(root, name); err == nil {
            t.Fatalf("readAsset(%q) expected an error", name)
        }
    }
}

测试中的合法样例验证读取链，四个非法样例验证入口拦截。另加一个合法但不存在的名称，例如 config/missing.yaml，应当进入读取错误分支，而不是被误报为路径格式错误。

上线前检查：资源根、名称和错误日志分别确认

• 资源根：fs.Sub 的目录名是嵌入树中真实存在的目录。
• 名称：外部输入先经过 fs.ValidPath，不要直接拼接操作系统绝对路径。
• 读取：对合法但不存在的名称保留 fs.ReadFile 或 Open 的错误。
• 回归：至少覆盖一个嵌套文件、一个缺失文件和四种非法名称。

相关问题：使用 io/fs 时容易混淆的三个点

fs.ValidPath 会检查 embed.FS 里是否有这个文件吗

不会。它只检查名称格式；文件是否存在要交给 Open、ReadFile 或目录读取操作判断。

fs.Sub 会把路径变成绝对路径吗

不会。它返回一个从指定目录观察到的子文件系统，调用方仍使用相对的斜杠路径名。

已经使用 fs.Sub，还需要校验外部名称吗

需要。fs.Sub 固定资源根，但不会替业务层判断传入名称是否为空、绝对或包含父目录跳转。

小结

处理嵌入资源时，把职责拆成三段就够清楚：embed.FS 提供资源树，fs.Sub 收窄访问根，fs.ValidPath 约束名称格式，之后再由 fs.ReadFile 或 Open 负责读取。这样非法输入、资源缺失和读取错误不会混成一类问题。