Go filepath.WalkDir 怎样判断输入是否满足边界

filepath.WalkDir 不会替业务自动判断“这个输入目录是否在允许范围内”。它只负责从给定的根路径遍历文件树，并把当前路径、目录项和访问错误交给回调。要判断输入是否满足边界，应先检查根路径，再在回调里按 err、DirEntry 和目录策略处理。

官方文档：https://pkg.go.dev/path/filepath#WalkDir

先把 WalkDir 的根路径边界定义清楚

这里的“输入边界”至少有三层含义：根路径是否为空或不存在，根节点是否符合业务要求，以及遍历是否允许进入某些子目录。WalkDir 的 root 参数只表示遍历起点，不等于“可信目录”。如果根路径来自配置、命令行或请求参数，应该先完成自己的规则判断。

官方文档说明，WalkDir 会把根节点本身也传给回调，并按字典序访问目录；它使用操作系统对应的分隔符。目录中的符号链接默认不会被跟随，因此不能用“路径看起来在目录里”替代真实的链接策略。

用调用前检查挡住明显的非法输入

一个可复用入口可以先拒绝空字符串，再用 os.Lstat 读取根节点本身。这样做的好处是：根路径是否存在、是否为目录、是否是符号链接，都能在进入遍历前有明确结论。是否允许根节点为普通文件，要根据业务决定；下面的示例只接受目录。

package main

import (
    "fmt"
    "io/fs"
    "os"
    "path/filepath"
)

func walkDirectory(root string) error {
    // 空字符串不能悄悄被 Clean 成当前目录，避免扩大遍历范围。
    if root == "" {
        return fmt.Errorf("根路径不能为空")
    }

    cleanRoot := filepath.Clean(root)
    info, err := os.Lstat(cleanRoot)
    if err != nil {
        return fmt.Errorf("读取根路径失败: %w", err)
    }

    // 这个入口只接受目录；是否允许根节点为文件应由调用方另设策略。
    if !info.IsDir() {
        return fmt.Errorf("根路径不是目录: %s", cleanRoot)
    }

    return filepath.WalkDir(cleanRoot, func(path string, d fs.DirEntry, err error) error {
        // 访问目录或条目失败时，先处理 err，不能假定 d 仍然可用。
        if err != nil {
            return fmt.Errorf("访问 %s 失败: %w", path, err)
        }

        // 目录和文件使用 DirEntry 的类型信息，不从字符串后缀猜类型。
        if d.IsDir() {
            fmt.Println("目录:", path)
            return nil
        }

        fmt.Println("文件:", path)
        return nil
    })
}

这段入口把“根目录检查”和“遍历回调”分开了。filepath.Clean 只做路径整理，不会验证路径存在，也不会赋予调用方额外权限；真正的存在性和类型判断仍由 os.Lstat 完成。若业务允许符号链接根节点，应显式设计跟随或拒绝规则，而不是依赖默认行为。

回调里先处理 err，再判断当前条目

WalkDir 的回调参数分别是路径、目录项和错误。读取目录或访问某个条目失败时，err 会携带原因；此时应该先决定是终止、记录后继续，还是跳过当前目录。只有 err == nil 时，才进入 d.IsDir()、d.Type() 或 d.Info() 之类的条目判断。

不要把 d.Info() 当成无成本的类型判断。DirEntry 已经提供了名称和类型相关能力；只有确实需要完整的 fs.FileInfo 时，再调用 Info()，并继续处理它返回的错误。

用 SkipDir 表达不进入某个子目录

当某个目录不属于本次任务范围时，可以返回 fs.SkipDir，让遍历跳过该目录的内容。这个返回值表达的是目录边界，不是普通文件过滤器。比如缓存目录、版本控制目录或生成目录，应该在确认 d.IsDir() 后再跳过。

func walkSource(root string) error {
    return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        // 目录读取失败时保留路径上下文，便于调用方决定是否继续。
        if err != nil {
            return fmt.Errorf("遍历 %s 失败: %w", path, err)
        }

        // 只对目录返回 SkipDir，避免把普通文件误当成子树处理。
        if d.IsDir() && d.Name() == ".cache" {
            return fs.SkipDir
        }

        // 这里按文件名做业务筛选，目录边界仍由 DirEntry 的类型决定。
        if !d.IsDir() && filepath.Ext(d.Name()) == ".go" {
            fmt.Println("源码文件:", path)
        }
        return nil
    })
}

如果遇到不允许继续的错误，可以直接返回该错误，让整个遍历停止；如果只是一个可忽略的子目录，则返回 fs.SkipDir。两者的含义不同：前者是错误策略，后者是目录范围策略。不要用一个宽泛的字符串前缀判断同时承担这两类职责。

符号链接和跨平台路径要单独处理

filepath.WalkDir 返回的路径使用当前操作系统的分隔符；需要处理 URL、归档内部路径或跨平台比较时，不要直接把它当成始终使用斜杠的字符串。可以在边界层明确转换，但转换后的值不应反过来替代文件系统访问路径。

另外，默认不跟随目录中的符号链接并不等于“所有输入都安全”。如果业务要求禁止链接逃出根目录，应在策略中明确检查链接，并在需要时用 os.Lstat 获取链接自身信息。对于用户可控根路径，还应在调用前限定允许的父目录，避免只检查字符串开头导致相邻目录名混淆。

把边界规则整理成一张速查表

因此，判断输入是否满足边界的关键不是找到一个“万能校验函数”，而是把规则放在正确的层次：根路径规则在调用前完成，访问错误在回调入口处理，目录范围用 SkipDir 表达，条目类型交给 DirEntry，跨平台路径和符号链接再单独制定策略。

相关问题

WalkDir 会遍历根路径本身吗？

会。官方说明它会把根节点也传给回调，所以回调逻辑不能只考虑根目录下的子项。

什么时候应该返回 SkipDir？

当当前条目是目录，且业务明确不需要继续进入这个目录时使用。普通文件筛选应返回 nil，不要把 SkipDir 当成通用停止信号。

为什么不能只用路径前缀判断是否越界？

字符串前缀可能把相邻目录误认为同一目录，还会忽略清理、符号链接和操作系统路径分隔符。应先明确允许的根，再结合文件系统信息和链接策略判断。

filepath.WalkDir 和 io/fs.WalkDir 的路径有什么区别？

filepath.WalkDir 面向操作系统文件路径，使用系统分隔符；io/fs.WalkDir 面向实现了 fs.FS 的文件系统，路径使用斜杠。选择哪一个取决于数据来源和后续路径语义。