Go io/fs.ValidPath 怎样组合到一个小型工具中

把 Go io/fs.ValidPath 组合进小工具时，适合让它负责第一层“原始路径名称语法”判断，再单独检查业务允许范围，最后通过 fs.Stat 判断目标当前是否存在、能否取得元信息。不要先用 Clean 把异常输入改成另一个名称，也不要把 ValidPath 返回 true 当成文件存在或允许访问。

Go 官方地址：https://go.dev/。本文用一个本地文件清单检查器说明组合方式：操作者给出可信目录和若干相对名称，工具逐项报告问题，只查询元信息，不读写文件正文。

从一份名称清单的误判说起

设想一个教学场景：团队在打包前整理资料清单。最初的检查器会清理路径，然后只判断名称是否“看起来正常”。一条带有多余路径元素的输入被清理成普通名称，另一条格式正常但实际缺失的输入也被标记通过。打包者看到的“通过”，与最初提交的名称、磁盘上的文件状态没有建立可靠对应。

这是为解释代码而构造的故障场景，并非某次真实线上事故。其演变可分为三个阶段：先把路径清理当作容错，接着把字符串检查的通过结果当作文件检查结果，最后才在后续处理时发现名称或文件不符合预期。本文修复的是检查器的判断职责和报告方式，不假定发生过数据泄漏。

影响范围也要说清楚：这是一个命令行清单辅助工具，它不替代最终打包时的错误处理，更不充当网络服务的文件授权系统。

把触发条件拆成三个判断

ValidPath 使用 io/fs 的统一路径语法：UTF-8 编码、斜杠分隔、相对名称，不能带空路径元素或单独的点、双点元素；单独的点作为根目录名称是特例。它不查询磁盘。

本例再增加业务规则：只接受文件名称，不接受根目录名称；为统一清单格式，拒绝反斜杠、冒号和空字节。这里尤其要注意，反斜杠和冒号并非 ValidPath 自身一律拒绝的字符。应用政策必须在代码和提示语里独立表达。

根因可以归结为两处职责混淆：清理输入改变了待检查对象；名称判断又被赋予了文件状态判断的含义。修复时直接保留原始名称，让每层只回答自己的问题。

用完整小工具保留原始输入

下面是完整的 main.go。第一个参数 ROOT 是操作者指定的可信资料目录，后续参数都是相对于它的 io/fs 名称。目录路径与文件名称分别处理，不把 ROOT 传给 ValidPath，因为它是操作系统目录参数。

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "os"
    "strings"
)

// 先检查原始 io/fs 名称，再应用本工具自己的命名政策。
func acceptName(name string) error {
    if !fs.ValidPath(name) {
        return fmt.Errorf("不是合法的 io/fs 路径")
    }
    if name == "." {
        return fmt.Errorf("请指定文件，不能使用根目录名称")
    }
    // 反斜杠和冒号可被 ValidPath 接受，本工具为统一输入额外禁止。
    if strings.ContainsAny(name, "\\:\x00") {
        return fmt.Errorf("本工具不接受反斜杠、冒号或空字节")
    }
    return nil
}

// 只检查文件元信息，不创建文件、不读取正文、不自动修改名称。
func inspect(fsys fs.FS, name string) error {
    info, err := fs.Stat(fsys, name)
    if err != nil {
        switch {
        case errors.Is(err, fs.ErrNotExist):
            return fmt.Errorf("文件不存在: %w", err)
        case errors.Is(err, fs.ErrPermission):
            return fmt.Errorf("没有访问权限: %w", err)
        default:
            return fmt.Errorf("读取元信息失败: %w", err)
        }
    }
    if !info.Mode().IsRegular() {
        return fmt.Errorf("目标不是普通文件")
    }
    return nil
}

func run(args []string) int {
    if len(args) 

acceptName 只处理字符串；inspect 接收 fs.FS，只查询目标；run 把逐项结果写到标准输出或标准错误，并汇总退出码。调用者可以把这三个职责分别接入自己的清单处理程序，而不需要把整段命令行逻辑复制到每个业务函数。

代码中用 errors.Is 区分不存在与权限问题，其余错误保留原始原因。遇到一个坏名称仍会继续检查后续项，避免操作者一次只能发现一处问题；最终退出码仍能告诉脚本是否有项目失败。

例如，自己在资料目录中准备 notes/intro.txt 后，可以按下列方式传入名称。命令只是使用示例，本文未执行它，实际结果取决于本地文件和权限。

# 逐项检查资料目录中的名称；引号保留每个参数的原始内容。
go run main.go ./materials 'notes/intro.txt' 'notes//draft.txt' 'missing.txt'
# 有失败项时 go run 会报告程序的非零退出状态；自动化分支可使用编译后的二进制退出码。

程序自身约定：全部项目通过返回 0，有名称或文件检查失败返回 1，缺少必要参数返回 2。go run 外层还会报告被运行程序退出失败；若脚本必须精确区分 1 与 2，应执行编译后的程序并读取它的退出码。

用输入矩阵约定行为

下表描述代码的设计预期，不是本机运行输出。假定操作者提供的 ROOT 可访问；“进入文件检查”只表示允许调用 inspect，不代表它必定成功。

不要悄悄对输入调用 TrimSpace。带空格的名称可能是操作者真实想检查的对象；本工具没有把空格定义为无效字符。若清单业务决定禁止首尾空格，应添加明确的拒绝规则，而不是删除后假装原输入通过。

这里也没有 URL 解码、环境变量展开或通配符展开。若从 HTTP 请求或其他编码格式接入，应先按该接口的协议得到最终名称，再把它原样交给名称政策；检查通过后不能另作一次会改变路径含义的转换。

防止检查器承担它没有的能力

os.DirFS 并不是符号链接越界访问的沙箱。若目录树内容来自不可信参与者，ValidPath 通过也不能证明符号链接目标仍在树内。本例限定为操作者控制的目录；需要约束目录树访问时，应结合实际 Go 版本研究 os.Root，而不能把这个小检查器直接改成任意用户可访问的下载服务。

fs.Stat 的结果也是查询时刻的状态。文件可能在后续打开前被替换，目录权限可能变化。最终真正读取或打包时仍必须处理打开、读取和关闭错误，不能复用一份过时的“通过”报告绕过这些操作。

防复发的重点是保持接口契约清楚：清单中存原始名称，报告保留原始输入，业务政策集中在一个函数里，文件检查错误携带底层原因。若以后增加“自动修正名称”，应把它做成独立、需要操作者选择的功能，明确显示修正前后值。

常见问题

为什么不先清理成正常路径？这个工具的任务是检查提交的名称。先清理会让被检查对象发生变化，也会掩盖清单里的实际问题。

ValidPath 为 true，为什么还是文件不存在？它只检查路径名称语法。磁盘状态由 fs.Stat 查询，不存在是独立结果。

可以把 Windows 完整路径当 NAME 吗？本工具的 NAME 是 io/fs 相对名称；操作系统目录应通过 ROOT 参数指定，不应混用两类输入。

报告通过是否说明文件正文可读？这里只证明查询时能取得普通文件元信息；没有执行正文读取，也没有承诺后续文件状态不变。

官方文档：https://pkg.go.dev/io/fs#ValidPath（名称语法与接口）；https://pkg.go.dev/os#DirFS（目录视图及符号链接限制）。