Go filepath用 Glob 匹配文件并区分空结果的排查指南

在 Go 里用 filepath.Glob 扫描配置文件时，最容易误判的一点是：没有找到文件并不代表调用失败。官方文档规定，模式合法但没有匹配项时，返回的 matches 是 nil，err 仍然是 nil；只有模式语法不合法时，才会得到 filepath.ErrBadPattern。排查时要先把这三种结果分开，再检查目录和模式是否真的覆盖了目标文件。

实用判断顺序是：先处理 err，再判断 len(matches) == 0，最后才进入文件读取逻辑。空结果应提示“没有匹配文件”，不要被包装成“Glob 失败”。

下面的例子围绕一个具体任务展开：从 data/incoming 中读取所有 JSON 文件，并让调用方知道是模式写错，还是目录中暂时没有文件。

先把空结果和错误分开

Glob 的返回值包含匹配路径和错误。它会忽略遍历目录时的文件系统 I/O 错误，能稳定报告的错误主要是 ErrBadPattern。因此不能只写一个“err 非空才失败”的粗略日志，也不能对空切片直接取第一项。

package main

import (
    "errors"
    "fmt"
    "path/filepath"
)

func findJSON(dir string) ([]string, error) {
    // Join 负责使用当前系统的路径分隔符，避免手写斜杠造成跨平台差异。
    pattern := filepath.Join(dir, "*.json")
    matches, err := filepath.Glob(pattern)
    if err != nil {
        // 模式错误与“目录里没有文件”是两种不同的故障。
        if errors.Is(err, filepath.ErrBadPattern) {
            return nil, fmt.Errorf("invalid glob pattern %q: %w", pattern, err)
        }
        return nil, err
    }
    if len(matches) == 0 {
        // 合法模式没有命中，交给上层决定是提示、跳过还是使用默认值。
        return nil, fmt.Errorf("no JSON files matched %q", pattern)
    }
    return matches, nil
}

如果业务需要把“无文件”当成正常状态，可以把这一步改成返回一个自定义哨兵错误，或者返回空的非 nil 切片并由调用方单独判断。关键是保留语义，不要把它和语法错误混在一起。

使用 filepath.Join 构造模式

模式中的 * 只匹配一个路径片段内的任意字符，不会自动跨过目录分隔符。filepath.Join(dir, "*.json") 适合扫描某一层目录；如果目标在子目录中，应明确增加层级，不能期待 dir/*.json 覆盖所有后代目录。

func jsonPattern(root, subdir string) string {
    // 先组合目录，再拼接文件名模式，保持模式的边界可读。
    return filepath.Join(root, subdir, "*.json")
}

// 例如：jsonPattern("data", "incoming") 得到当前系统可用的模式。
// 它只匹配 data/incoming 这一层的 JSON 文件，不递归进入更深目录。

在 Windows 上，路径分隔符由 filepath 负责处理；如果模式来自配置文件，最好先明确它是本地文件路径还是 URL。URL 统一使用正斜杠时，不应把 filepath 当作 URL 处理器。

用 ErrBadPattern 定位模式问题

常见错误包括没有闭合的字符类、把业务字符串直接拼进模式、或在 Windows 与 Unix 之间误用转义规则。可以先用 filepath.Match 对一个已知文件名做小范围判断，确认模式语法后再调用 Glob。

func checkPattern(pattern string) error {
    // 用固定样例只检查语法，不依赖真实目录是否存在。
    _, err := filepath.Match(pattern, "sample.json")
    if err != nil {
        return fmt.Errorf("check pattern %q: %w", pattern, err)
    }
    return nil
}

Match 要求整个文件名都匹配，* 不跨目录；它适合验证模式本身，不代表真实目录里一定有文件。验证通过后仍需检查工作目录、文件名大小写和实际层级。

检查相对路径、大小写和层级边界

空结果出现时，按下面顺序排查比盲目修改通配符更快：

• 记录最终传给 Glob 的模式，确认相对路径是相对于当前工作目录，而不是项目根目录。
• 列出目标目录的真实文件名，核对扩展名大小写；不同文件系统对大小写的行为可能不同。
• 确认 * 所在层级。需要递归扫描时，应改用 filepath.WalkDir 或明确的多层模式。
• 把外部输入当作数据处理，避免未经约束的 [、]、? 等字符改变模式含义。

还要注意，Glob 不会把“目录读取失败”统一变成显式错误。生产代码如果必须区分权限、软链接或遍历失败，应改用 WalkDir，在回调中接收具体错误。

封装稳定的结果分类

文件导入、配置加载等上层逻辑通常只关心“找到文件”“没有文件”“模式配置错误”三种状态。可以在边界层统一包装，日志中保留最终模式，调用方就不必重复猜测。

这也是排查的核心边界：不要用“换成更宽的 *”掩盖路径根目录错误；先打印模式，再确认目录，再决定是否扩大匹配范围。

相关问题

Glob 无匹配时 matches 一定是空切片吗？

官方语义是返回 nil，但业务代码应统一使用 len(matches) == 0 判断，不依赖 nil 身份。

Glob 能递归匹配所有子目录吗？

不能把单层 * 当递归符号。需要递归时使用 WalkDir，并在遍历回调里按扩展名或 Match 过滤。