Go os.DirFS 怎样组合到一个小型工具中

我在做一个很小的文档查看工具时，不想让业务代码到处拼接本地绝对路径：命令行只负责接收目录，读取逻辑则统一接收 fs.FS。这正是 os.DirFS 的合适用法。它把目录包装成文件系统接口，后续可以直接组合 fs.ReadDir、fs.ReadFile 和 fs.WalkDir。

官方文档：https://pkg.go.dev/os　接口文档：https://pkg.go.dev/io/fs

最小组合方式是：用 os.DirFS(rootDir) 创建一个 fs.FS，所有文件名都使用相对于这个目录、以斜杠分隔的路径，再把这个接口传给读取函数。要注意，os.DirFS 不是 chroot；目录中的符号链接仍可能指向根目录之外。

这个小工具到底要组合什么

我们把工具命名为 docpeek，只做两件事：列出根目录下的条目，或者读取一个文本文件。命令行参数是操作系统路径，进入读取层后就不再继续拼接绝对路径，而是只传递 fs.FS 能理解的相对名称。

这个拆分有一个实际好处：以后把本地目录换成 embed.FS、测试用的 fstest.MapFS，读取函数仍然可以复用。变化只发生在“创建文件系统”的入口处。

把目录入口组合成 fs.FS

先看一个完整但刻意保持小的实现。listEntries 和 readText 都只接收 fs.FS，它们不关心根目录来自哪里；main 负责把命令行目录转换为 os.DirFS。

package main

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

func listEntries(fileSystem fs.FS) error {
	entries, err := fs.ReadDir(fileSystem, ".")
	if err != nil {
		return fmt.Errorf("列出目录失败: %w", err)
	}
	for _, entry := range entries {
		kind := "文件"
		if entry.IsDir() {
			kind = "目录"
		}
		fmt.Printf("%s\t%s\n", kind, entry.Name())
	}
	return nil
}

func readText(fileSystem fs.FS, name string) error {
	// fs.FS 使用相对、斜杠分隔的名称；先拒绝不符合约定的输入。
	if !fs.ValidPath(name) {
		return fmt.Errorf("无效文件名 %q", name)
	}
	data, err := fs.ReadFile(fileSystem, name)
	if err != nil {
		return fmt.Errorf("读取 %q 失败: %w", name, err)
	}
	fmt.Print(string(data))
	return nil
}

func main() {
	rootDir := flag.String("root", ".", "文档根目录")
	fileName := flag.String("file", "", "要读取的相对文件名；留空时列出根目录")
	flag.Parse()

	// DirFS 只在这里接触操作系统路径，后续统一使用 fs.FS。
	fileSystem := os.DirFS(*rootDir)
	var err error
	if *fileName == "" {
		err = listEntries(fileSystem)
	} else {
		err = readText(fileSystem, *fileName)
	}
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

这里没有为了读取文件再调用 filepath.Join。这不是说路径处理永远不需要 filepath，而是进入 fs.FS 后应遵循它自己的名称约定。目录列表使用 "." 表示根，文件读取使用类似 notes/today.txt 的相对名称。

处理路径输入与安全边界

fs.ValidPath 解决的是“这个字符串是否符合 fs.FS 名称约定”，不是“这个文件是否存在”。例如 "notes/today.txt" 可以通过检查，"/tmp/a.txt"、"a/../b" 和 "a//b" 不应作为统一文件名继续传入。检查通过后，fs.ReadFile 仍然可能因为文件不存在、权限不足或路径指向目录而返回错误。

还要把两个根目录概念分开：os.DirFS(rootDir) 接收的是操作系统路径；传给 fs.ReadFile 的名称则是相对于该根的 fs 路径。相对路径根目录如果来自 DirFS("relative")，后续工作目录变化也会影响它的解释，因此命令行工具通常更适合先明确根目录来源和生命周期。

常见误区与适用边界

第一个误区是把 os.DirFS 当作安全沙箱。官方文档明确说明，目录内指向外部位置的符号链接不会因为包装成 fs.FS 就自动失效；如果工具要处理不可信目录，应该根据当前 Go 版本评估 os.OpenRoot 与 Root.FS 等更强的根目录能力，而不是只依赖 DirFS。

第二个误区是把 fs.ValidPath 当成权限校验。它只检查名称格式，不会替你判断访问权限，也不会证明目标是普通文件。真正的读取错误仍要保留并返回，示例中的 %w 让上层可以继续使用错误链判断。

第三个误区是让业务函数继续保存根目录字符串并自行拼路径。这样会让同一份代码同时处理操作系统路径和 fs 路径，跨平台时更容易把反斜杠、绝对路径和相对名称混在一起。把根目录适配集中在入口，读取函数只接收 fs.FS，小工具反而更容易测试。

什么时候值得这样组合

如果程序只读取一个文件，直接使用 os.ReadFile 可能更短；当程序需要列目录、遍历、读取，或希望在本地目录、嵌入资源和内存文件系统之间切换时，os.DirFS 的价值就会明显起来。它不是额外的框架，而是把“文件从哪里来”和“业务如何读取”拆开的一层很薄的适配。

可以把这篇的组合记成三句话：命令行只接收根目录；读取函数只接收 fs.FS；传入文件名先按 fs.ValidPath 规则处理。若场景涉及不可信符号链接，再单独升级根目录隔离方案。

相关问题

os.DirFS 能不能限制符号链接跳出根目录？

不能把它当作这个保证。目录中的符号链接仍可能指向根目录之外；需要更强隔离时，应评估 Go 官方提供的根目录能力。

fs.ValidPath 会检查文件是否存在吗？

不会。它只检查 fs.FS 名称格式，文件是否存在要由 fs.ReadFile、fs.Stat 或其他具体操作返回结果。

为什么不在工具里到处拼接绝对路径？

因为统一使用 fs.FS 后，可以替换文件系统实现，并把平台路径差异收敛在入口，列表、读取和测试代码都更容易复用。