Go io/fs.ValidPath 怎样判断输入是否满足边界

把外部输入交给 io/fs.FS.Open 或 fs.ReadFile 前，先判断它是不是符合 io/fs 约定的路径名。最小做法是调用 fs.ValidPath(name)：它检查的是 slash 分隔的未根路径，不是当前操作系统上的绝对路径清理器。

排查路径问题时先记住一句话：. 是 io/fs 根目录的特例；空字符串、空路径元素、..、以斜杠开头或结尾的输入都不应作为普通 FS 路径通过入口。

触发信号：FS 入口收到的路径不稳定

值班时如果发现同一个文件接口对 docs/readme.txt、/docs/readme.txt 和 docs//readme.txt 的处理不一致，先不要用 filepath.Clean 把字符串“修好”。io/fs 的路径语义跨平台统一，入口应该先按 FS 契约判断，再决定是否继续打开文件。

官方 io/fs 文档把路径定义为 UTF-8、未根、使用斜杠分隔的路径元素序列。反斜杠和冒号可以出现在名字中，但自定义 FS 不能擅自把它们当成分隔符。

先明确 FS 路径语义

普通合法路径的形态类似 config/app.yaml。它不能以 / 开始或结束，也不能含有空元素、. 或 .. 路径元素；唯一的点号特例是单独的 .，它表示 FS 的根目录。

这里的“未根”很关键。/etc/app.conf 是操作系统风格的绝对路径，但对 io/fs.FS 来说不满足普通名称约定；Windows 风格的 C:\\work\\app.txt 也不能被当成 FS 的目录层级。斜杠是 FS 层的分隔符，平台路径工具和 FS 路径工具不要混用。

用 ValidPath 做入口判断

把校验放在调用 FS 的边界处，返回一个明确的错误，让上层知道请求没有进入文件系统。下面的函数只负责判断名称，不负责把非法输入改写成另一个名称：

package main

import (
	"fmt"
	"io/fs"
)

// checkFSName 只接受 io/fs 约定的路径名，不替调用方清理输入。
func checkFSName(name string) error {
	if !fs.ValidPath(name) {
		// 让调用方区分“名称不合规”和“文件不存在”。
		return fmt.Errorf("invalid fs path %q", name)
	}
	return nil
}

// readText 在真正读取前先挡住不符合 FS 契约的输入。
func readText(fsys fs.FS, name string) ([]byte, error) {
	if err := checkFSName(name); err != nil {
		return nil, err
	}
	// ReadFile 负责打开、读取并关闭文件，调用方只处理结果和错误。
	return fs.ReadFile(fsys, name)
}

func main() {
	for _, name := range []string{".", "docs/readme.txt", "", "/docs/readme.txt", "docs//readme.txt", "../secret"} {
		fmt.Printf("%q: %t\\n", name, fs.ValidPath(name))
	}
}

判断结果可以按下面的边界表理解：

自定义 FS 的处理与回滚路径

如果你实现了自己的 fs.FS，Open(name string) 应该遵守同一约定：拒绝不满足 ValidPath(name) 的名称，并返回带有路径信息的错误。实现方不能因为底层存储使用 Windows 路径、对象存储键或数据库字段，就把反斜杠、冒号或其他字符重新解释成另一套目录语法。

处理失败时的回滚路径也很简单：保留原始输入用于日志，停止本次 FS 操作，返回“路径不合规”；不要在失败后自动把 ../secret 改成 secret，也不要把 /docs/a.txt 裁掉首斜杠再继续。改写会让审计记录和实际访问的名称不一致。

告警确认与复盘清单

• 告警确认：日志中区分 ValidPath 拒绝和文件不存在、权限不足等 FS 错误。
• 输入确认：确认上游传递的是 FS 名称，不是 filepath.Join 产生的系统路径。
• 实现确认：自定义 FS 的 Open、ReadDir 等入口保持同一 slash 分隔语义。
• 复盘确认：检查是否存在用 filepath.Clean 静默修正非法输入的代码，并决定改为显式拒绝。

复盘的目标不是让所有字符串都“变得可用”，而是让每个进入 FS 的名称都有稳定、可解释的边界。这样，合法路径才会继续走打开或读取逻辑，非法路径也能在最靠近入口的位置被识别。

常见问题

fs.ValidPath(".") 为什么应该通过？

在 io/fs 中，单独的 . 表示根目录，是路径名规则明确保留的特例。它与包含 ./ 或 a/./b 的普通路径不同。

反斜杠会自动被当成目录分隔符吗？

不会。io/fs 的分隔符统一是斜杠；反斜杠可以是名称中的普通字符，但 FS 实现不能把它偷偷解释成层级分隔。

能否先调用 filepath.Clean 再调用 ValidPath？

不建议把清理当作校验替代品。它可能删除点段、折叠斜杠或改变用户原始名称；如果业务允许规范化，应明确记录转换规则，否则直接用 ValidPath 拒绝不合规输入更容易审计。