Go io/fs.Sub 怎样把子目录暴露为新的文件系统

如果一个业务函数只需要读取 assets 目录，没必要让它知道父文件系统里的完整前缀。io/fs.Sub 可以从已有的 fs.FS 派生一个新的文件系统视图：父级中的 assets/config.yaml，在子 FS 中直接按 config.yaml 读取。它不会复制文件，也不会把目录内容搬到新位置，只是把访问根切换到指定子目录。

fs.Sub 先解决的是路径视图，不是复制文件

fs.Sub 的签名是 func Sub(fsys FS, dir string) (FS, error)。第一个参数是已有的文件系统，第二个参数是父 FS 内部的目录名；成功后得到的 FS 把这个目录当作新的根。父级里的 assets/config.yaml 会映射成子 FS 的 config.yaml，而不是继续要求下游传入 assets/config.yaml。

我在把“资源目录前缀”从业务函数里移走时，最容易忽略的点就是：Sub 改变的是名字解析视角，不改变底层实现。它可以用于内存 FS、嵌入式资源 FS 或自定义 FS，调用者仍然通过 Open、ReadFile、ReadDir 等接口访问内容。

用 fstest.MapFS 写一个可重复的子目录示例

testing/fstest.MapFS 是测试文件系统，适合把路径关系写成少量内存数据。下面的例子故意同时放入 assets 和 docs，让结果更容易看出子视图只暴露哪一部分：

package main

import (
	"fmt"
	"io/fs"
	"testing/fstest"
)

func main() {
	parent := fstest.MapFS{
		"assets/config.yaml": &fstest.MapFile{Data: []byte("mode: prod\n")},
		"assets/logo.txt":    &fstest.MapFile{Data: []byte("demo logo\n")},
		"docs/readme.md":     &fstest.MapFile{Data: []byte("read me\n")},
	}

	// 把 assets 变成新的 FS 根，子 FS 内不再携带 assets 前缀。
	assets, err := fs.Sub(parent, "assets")
	if err != nil {
		// 派生失败通常意味着目录不存在或 dir 不符合 fs 路径规则。
		panic(err)
	}

	data, err := fs.ReadFile(assets, "config.yaml")
	if err != nil {
		// 这里的读取路径相对于 assets 子 FS，而不是 parent 根。
		panic(err)
	}
	fmt.Printf("%s", data)
}

这个调用链里有两个不同的路径：fs.Sub 的 dir 是父 FS 中的 assets，fs.ReadFile 的 name 则是子 FS 中的 config.yaml。如果把后者错误地写成 assets/config.yaml，就会再次寻找一个不存在的嵌套路径。

路径规则决定了 Sub 的边界

io/fs 的路径不是操作系统路径。它要求使用 UTF-8、未加根的、用斜杠分隔的路径元素；. 只能作为根目录的特殊名字，..、空元素、开头或结尾的斜杠都不符合常规 FS 名称。也就是说，assets、templates/email 是面向 FS 的写法，而 /var/app/assets、assets/ 不是把本机目录直接照搬进来的写法。

func subFS(parent fs.FS, dir string) (fs.FS, error) {
	// 先用 ValidPath 判断 dir 是否符合 FS 的相对路径约定。
	if !fs.ValidPath(dir) {
		return nil, fmt.Errorf("invalid fs directory %q", dir)
	}

	// Sub 负责确认目录存在并创建子视图，错误交给上层分类处理。
	return fs.Sub(parent, dir)
}

这里的预检查不是为了替代 fs.Sub 的错误处理，而是为了在输入来自配置文件或用户参数时更早给出清晰原因。即使省略 ValidPath，也必须检查 Sub 的返回错误；不要把 nil 子 FS 继续传给业务读取函数。

根目录和不存在目录要单独处理

当调用方已经拿到一个代表目标目录的 FS 时，可以用 "." 表示当前根目录，避免为了“再派生一次”而拼出空字符串。相反，传入不存在的目录、带 .. 的路径或错误的斜杠形式时，应该把它当成配置或资源布局问题，而不是把读取失败归因给具体文件。

func openConfig(parent fs.FS, root string) ([]byte, error) {
	// root 为空时统一指向当前 FS 根，避免把空字符串传给 FS API。
	if root == "" {
		root = "."
	}

	view, err := fs.Sub(parent, root)
	if err != nil {
		// 目录层错误先返回，调用者可以记录 root 便于定位资源布局。
		return nil, fmt.Errorf("create sub fs %q: %w", root, err)
	}

	data, err := fs.ReadFile(view, "config.yaml")
	if err != nil {
		// 文件层错误与子目录派生错误分开包装，便于 errors.Is/As 判断。
		return nil, fmt.Errorf("read config.yaml: %w", err)
	}
	return data, nil
}

从 MapFS 迁移到 embed.FS 或自定义 FS

测试阶段可以用 MapFS，生产代码则可能使用 embed.FS 或项目自己的 fs.FS 实现。迁移时最省心的做法，是让业务函数只依赖 fs.FS，在装配层一次性完成 fs.Sub，这样测试与生产只替换父 FS，不改业务读取路径。

//go:embed web
var embedded embed.FS

func loadTemplateFS() (fs.FS, error) {
	// embed.FS 的根包含 web 目录，装配层把它收敛为模板子 FS。
	return fs.Sub(embedded, "web")
}

func readTemplate(templates fs.FS, name string) ([]byte, error) {
	// 业务层只接受相对于 templates 根的文件名。
	return fs.ReadFile(templates, name)
}

真实项目中还要确认 embed 声明位于带有有效 //go:embed 指令的 Go 文件中，并导入 embed（即使只通过空白标识符使用）。这里的重点不是让每个调用者知道资源来自哪里，而是稳定地约定：传给 readTemplate 的名字永远相对于模板根。

迁移时用这张表检查是否改完整

常见问题

fs.Sub 会复制目录内容吗？

不会。它返回一个新的 fs.FS 访问视图，底层数据仍由原来的 FS 提供。

fs.Sub 的 dir 可以写成操作系统路径吗？

不建议。io/fs 使用统一的相对、斜杠路径规则，不应把 Windows 反斜杠或 Unix 绝对路径当作 FS 名称。

为什么子 FS 里读取不到 assets/config.yaml？

因为 assets 已经成为子 FS 的根，读取名应改成 config.yaml；继续带前缀会寻找嵌套的 assets/assets/config.yaml 视图。

fs.Sub 和 MapFS.Sub 是什么关系？

fstest.MapFS 也提供了子目录派生能力，但业务接口仍可统一使用 fs.Sub 和 fs.FS，这样更容易替换底层实现。