Go fs.Glob 怎么处理实现方返回的 I/O 错误

fs.Glob 不是一个用来汇报底层读取故障的接口。走标准回退实现时，它会忽略读取目录产生的 I/O 错误；因此“没有匹配项”和“某个目录没能读出来”都可能表现为没有返回错误。调用方如果必须知道结果是否完整，应改用 fs.WalkDir 或显式 fs.ReadDir，在自己的错误策略中决定停止、跳过还是记录。

官方文档：https://pkg.go.dev/io/fs#Glob

fs.Glob 解决的是名称匹配，不是完整性审计

fs.Glob(fsys, pattern) 返回匹配模式的文件名。模式语法与 path.Match 相同，可以包含分层名称，例如 assets/*/*.json。没有匹配文件时返回 nil，模式格式错误时返回 path.ErrBadPattern。

官方契约还明确说明：Glob 会忽略读取目录时遇到的文件系统错误，例如 I/O 错误。这个选择让“尽力找出能看到的匹配项”变得简单，但它也意味着返回的匹配列表不一定代表完整文件树。

matches, err := fs.Glob(fsys, "configs/*.json")
if err != nil {
    // 这里主要处理模式语法错误，而不是目录读取失败。
    return fmt.Errorf("glob pattern: %w", err)
}

// matches 可能为空，也可能只包含成功读取目录中的结果。
for _, name := range matches {
    fmt.Println(name)
}

核对点很简单：如果你的业务只需要“尽可能列出可见文件”，这套语义通常够用；如果业务要求证明“所有目录都已检查”，只看 err 不够。

两条实现路径对错误的处理并不完全一样

fs.Glob 会先判断传入的文件系统是否实现了 fs.GlobFS：

• 实现了 GlobFS：直接调用实现方的 Glob(pattern)。
• 没有实现 GlobFS：标准库使用 fs.ReadDir 遍历目录并用 path.Match 匹配名称。

在标准回退路径中，源码在 ReadDir 返回错误后直接保留已有匹配并返回，不把该 I/O 错误交给调用方。没有通配符时也类似：如果 Stat 失败，结果是 nil, nil。

而在 GlobFS 路径中，顶层函数直接返回实现方给出的结果。一个符合顶层 Glob 契约的实现应保持相同语义，不应把普通目录 I/O 错误混进公共返回值；但自定义实现如果返回了其他错误，当前委托路径会把它传出来。调用方不要依赖这种偏离契约的行为来做完整性检查，最好为严格查询定义单独接口。

模式错误可以直接处理

Glob 稳定向调用方暴露的错误是模式格式错误。建议用 errors.Is 判断 path.ErrBadPattern，不要依赖错误文本：

func findJSON(fsys fs.FS, pattern string) ([]string, error) {
    matches, err := fs.Glob(fsys, pattern)
    if errors.Is(err, path.ErrBadPattern) {
        // 把用户输入问题转换为更清楚的业务错误。
        return nil, fmt.Errorf("无效文件匹配模式 %q: %w", pattern, err)
    }
    if err != nil {
        // 兼容自定义 GlobFS 返回的其他错误。
        return nil, fmt.Errorf("匹配文件: %w", err)
    }
    return matches, nil
}

这里保留了第二个 err != nil 分支，是为了防御不完全遵循顶层契约的自定义 GlobFS。它不能让标准回退路径重新暴露已经被忽略的 ReadDir 错误。

需要 I/O 错误时改用 WalkDir

当配置加载、备份、迁移、发布打包或审计任务要求结果完整时，可以用 fs.WalkDir 遍历，再用 path.Match 做匹配。WalkDir 会把访问路径相关的错误传入回调；回调返回该错误后，遍历停止并把错误交给调用方。

func strictGlob(fsys fs.FS, root, pattern string) ([]string, error) {
    // 先校验模式，避免目录为空时漏掉格式错误。
    if _, err := path.Match(pattern, ""); err != nil {
        return nil, err
    }

    var matches []string
    err := fs.WalkDir(fsys, root, func(name string, d fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            // 保留权限、网络文件系统或设备 I/O 错误。
            return fmt.Errorf("访问 %q: %w", name, walkErr)
        }
        if d.IsDir() {
            return nil
        }

        matched, err := path.Match(pattern, name)
        if err != nil {
            return err
        }
        if matched {
            matches = append(matches, name)
        }
        return nil
    })
    if err != nil {
        return nil, err
    }
    return matches, nil
}

调用时让 root 与模式处于同一命名空间。例如从文件系统根开始遍历，可以传 root="." 和 pattern="configs/*.json"。path.Match 中的 * 不跨越斜杠，因此它只匹配这一层目录。

核对结果时，错误为空才代表遍历过程中没有被回调拒绝的访问错误；一旦收到错误，就不要把已有的局部 matches 当成完整清单。

自定义文件系统最好把两种语义分开

如果你正在实现 fs.FS，不要让同一个 Glob 方法在不同存储后端上随机改变错误策略。比较清晰的做法是：

• Glob 遵循标准库契约，面向“尽力匹配”场景。
• 另设 GlobStrict 或业务查询方法，明确承诺目录读取失败就返回错误。
• 在实现内部记录被忽略的 I/O 错误，用于指标、日志或诊断，但不要把日志记录等同于调用成功。

type StrictGlobFS interface {
    fs.FS

    // GlobStrict 要么返回完整结果，要么返回底层访问错误。
    GlobStrict(pattern string) ([]string, error)
}

func loadAll(fsys StrictGlobFS, pattern string) ([]string, error) {
    names, err := fsys.GlobStrict(pattern)
    if err != nil {
        return nil, fmt.Errorf("完整匹配失败: %w", err)
    }
    return names, nil
}

这样调用方从方法名和接口类型就能知道返回保证，不必猜测某个后端是否把错误吞掉。

完整性、性能和安全要一起判断

WalkDir 为了保证词法顺序，会先读取整个目录，因此超大目录会占用更多内存；严格遍历也可能比 Glob 的实现方优化路径更慢。反过来，在安全或完整性敏感任务中，性能不能成为静默忽略权限错误、设备错误或远程存储故障的理由。

常见问题

fs.Glob 返回空切片，能说明目录为空吗？

不能。它可能表示没有匹配项，也可能表示相关目录无法读取。需要区分时使用能传播错误的遍历方式。

实现了 GlobFS 后还能返回 I/O 错误吗？

代码层面，顶层 fs.Glob 会直接转交实现方的返回值；接口语义层面，建议实现方保持 Glob 的既定契约，把严格错误传播放到另一个明确命名的方法中。

能否先调用 fs.Glob，再逐个 Stat 验证？

逐个 Stat 只能验证已经返回的名称，无法发现某个未读目录里被遗漏的文件，因此不能证明匹配结果完整。

最终选择取决于结果保证：只要可见匹配就用 fs.Glob；任何目录读取失败都必须被知道，就用 fs.WalkDir、显式 fs.ReadDir 或单独的严格接口。