Go io/fs 怎样实现带前缀的虚拟文件系统

如果底层文件系统里有 assets/css/app.css，但业务模块只希望看到一个从根目录开始的资源树，可以给 fs.FS 加一层很薄的前缀包装器。关键是先用 fs.ValidPath 校验调用方传入的名称，再用标准库的 path.Join 拼接前缀；不要用操作系统相关的 filepath.Join 改写虚拟路径。

一、先把虚拟路径和底层路径分开

前缀 FS 的职责很单一：对外暴露一个新的根目录。调用方请求 css/app.css 时，包装器把它转成底层的 assets/css/app.css；请求 . 时则打开前缀目录本身。这里的路径是 io/fs 定义的逻辑路径，在 Windows 上也使用斜杠。

如果只是把现有 FS 的某个子目录暴露出来，标准库已经提供 fs.Sub，它通常是更省事的选择。需要自定义错误路径、埋点或组合额外规则时，再实现自己的包装器。

二、用 fs.ValidPath 拦住越界输入

fs.ValidPath 接受 . 和普通的斜杠分隔路径，拒绝空字符串、绝对路径、尾部斜杠、重复斜杠、. 元素和 .. 元素。反斜杠在 FS 规则中不是分隔符，所以不能把它当成 Windows 路径再交给 filepath.Clean。

package main

import (
	"errors" // 用于判断底层错误是否属于非法路径。
	"fmt"
	"io/fs"
	"path"
)

type prefixFS struct {
	base   fs.FS // 真正保存文件的底层文件系统。
	prefix string // 必须是 ValidPath 可接受的目录名。
}

func (p prefixFS) Open(name string) (fs.File, error) {
	if !fs.ValidPath(name) {
		// 返回调用方看到的原始 name，便于定位是哪一次请求越界。
		return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrInvalid}
	}
	mapped := path.Join(p.prefix, name) // fs.FS 始终使用斜杠路径。
	f, err := p.base.Open(mapped)
	if err != nil {
		// 保留底层原因，但把 Path 还原成调用方请求的虚拟路径。
		var pathErr *fs.PathError
		if errors.As(err, &pathErr) {
			return nil, &fs.PathError{Op: "open", Path: name, Err: pathErr.Err}
		}
		return nil, err
	}
	return f, nil // 调用方仍负责关闭返回的文件。
}

func main() {
	_ = fmt.Sprintf("%T", prefixFS{}) // 这里只展示类型，实际 base 可来自 embed.FS 或 os.DirFS。
}

示例把底层 *fs.PathError 的 Err 保留下来，同时把 Path 改回虚拟路径。这样日志不会泄露内部前缀，调用者也能继续用 errors.Is 判断 fs.ErrNotExist。若项目不需要这层错误整形，直接透传 p.base.Open(mapped) 也可以。

三、测试目录语义与适用边界

测试时用 testing/fstest.MapFS 放入一棵小树即可：assets/css/app.css 应能通过 css/app.css 打开，../secret 应在触达底层前失败。还要测 .，因为它代表包装器暴露出来的根目录。

func TestPrefixFS(t *testing.T) {
	base := fstest.MapFS{
		"assets/css/app.css": &fstest.MapFile{Data: []byte("body{}")}, // 模拟前缀目录中的文件。
	}
	view := prefixFS{base: base, prefix: "assets"}

	f, err := view.Open("css/app.css")
	if err != nil {
		t.Fatal(err) // 正常路径必须能落到底层文件。
	}
	_ = f.Close() // 测试也要关闭文件，保持 FS 使用习惯。

	if _, err := view.Open("../secret"); !errors.Is(err, fs.ErrInvalid) {
		t.Fatalf("want fs.ErrInvalid, got %v", err) // 非法路径不应被拼接后再访问。
	}
}

如果前缀固定且只需要子树视图，优先写 view, err := fs.Sub(base, "assets")。自定义 prefixFS 适合需要统一错误路径、记录访问指标或在 Open 前加入额外规则的场景。无论选哪种方式，都不要把它误当成操作系统级隔离：fs.FS 的路径校验解决的是接口边界，底层实现的符号链接和真实目录权限仍需单独设计。

相关问题

为什么这里使用 path.Join 而不是 filepath.Join？

fs.FS 的路径规范跨平台固定使用斜杠；path.Join 与这个规范一致，避免把本机分隔符带进虚拟路径。

前缀为空时应该怎么处理？

可以把空前缀规范化为 .，或者直接返回底层 FS。不要让空前缀绕过对 name 的 fs.ValidPath 校验。

fs.Sub 和自定义包装器怎么选？

只需要子目录视图就用 fs.Sub；需要自定义错误、观测或额外策略时再保留包装器。