Go Doublestar 模式的静态前缀不存在时为什么返回空结果

我在把目录扫描从“找到就处理”改成“找不到就报警”时，遇到过一个很容易误判的结果：Doublestar 的模式明明写了固定目录，目录不存在时却得到空切片，err 还是 nil。这不是 ** 失效，也不代表扫描成功，而是库默认把“模式没有匹配项”和“扫描路径不存在”放在了同一条无错误结果路径上。

官方地址：https://github.com/bmatcuk/doublestar

如果你的业务要求静态前缀必须存在，请在 Glob、GlobWalk 或 FilepathGlob 中显式加入 doublestar.WithFailOnPatternNotExist()。WithFailOnIOErrors() 只控制普通 I/O 错误是否向上返回，不能替代前缀存在性检查。

先区分三种“结果为空”的原因

这几个结果在日志里都可能表现为“没有文件”，但处理策略完全不同：

因此，看到 matches == nil 时不能直接得出“目标目录存在，只是里面没有文件”。如果扫描的是发布目录、租户目录或必须由部署步骤创建的目录，这个差异很重要。

为什么默认 Glob 会把不存在前缀变成空结果

以 configs/missing/**/*.yaml 为例，configs/missing/ 是第一个元字符以前的静态前缀，后面的 **/*.yaml 才是递归匹配部分。Doublestar 在遍历目录时遇到 fs.ErrNotExist，默认会把它按“没有匹配”处理；默认的 WithFailOnIOErrors 也不会把这个特例改成普通 I/O 错误。

这个设计适合“尽力扫描”：某个可选目录没有部署，就返回空集，调用方继续处理其它输入。但它不适合“目录缺失就是配置错误”的任务。问题不在 ** 能不能跨多层目录，而在调用方是否表达了静态前缀必须存在的约束。

源码路径可以概括为：先递归处理元字符前的目录；读取目录得到 fs.ErrNotExist 后，交给内部的 handlePatternNotExist；默认选项不会返回错误，开启强检查时才返回 ErrPatternNotExist。

WithFailOnIOErrors 不是这个问题的开关

最常见的迁移误区是只补上 WithFailOnIOErrors()：

package main

import (
    "fmt"
    "io/fs"

    "github.com/bmatcuk/doublestar/v4"
)

func scanOptional(fsys fs.FS) error {
    // 这个模式允许目录不存在：不存在时 matches 可能为空，err 仍可能为 nil。
    matches, err := doublestar.Glob(fsys, "configs/missing/**/*.yaml",
        doublestar.WithFailOnIOErrors(),
    )
    if err != nil {
        return fmt.Errorf("扫描配置失败: %w", err)
    }
    fmt.Printf("找到 %d 个配置文件\n", len(matches))
    return nil
}

如果目录是可选输入，这样的语义正合适；如果目录必须存在，就要改变选项，而不是在返回空切片后猜测原因。

需要强约束时怎样写

将 WithFailOnPatternNotExist() 与原来的模式一起传入即可。它检查的是元字符出现以前的固定路径，例如 configs/missing/；模式中由 * 或 ** 代表的可变部分不属于静态前缀。

package main

import (
    "errors"
    "fmt"
    "io/fs"

    "github.com/bmatcuk/doublestar/v4"
)

func scanRequired(fsys fs.FS) ([]string, error) {
    // 让部署缺目录变成明确错误，避免把配置缺失当成“没有匹配文件”。
    matches, err := doublestar.Glob(fsys, "configs/missing/**/*.yaml",
        doublestar.WithFailOnPatternNotExist(),
        doublestar.WithFailOnIOErrors(),
    )
    if err != nil {
        if errors.Is(err, doublestar.ErrPatternNotExist) {
            return nil, fmt.Errorf("必需的配置前缀不存在: %w", err)
        }
        return nil, fmt.Errorf("读取配置目录失败: %w", err)
    }
    return matches, nil
}

两个选项可以同时使用：前者负责“固定前缀是否存在”，后者负责其它读取目录时的 I/O 错误。调用方不要把所有错误都改写成“没有匹配项”，否则排障时会丢掉最有价值的信息。

从旧写法迁移时检查四个位置

1. 确认 FS 根目录。 Glob 接收的是 fs.FS，模式通常使用正斜杠；如果用了 os.DirFS，先确认传入的根目录和模式相对关系。
2. 标出第一个元字符。 元字符以前的内容是静态前缀，只有这一段会触发 ErrPatternNotExist 的专门检查。
3. 决定目录是否必需。 缓存、可选插件目录可以保留默认空结果；配置、迁移文件和发布产物目录通常应该开启强检查。
4. 区分空集和错误。 强检查打开后，针对 ErrPatternNotExist 做单独日志和告警；不要用 len(matches) == 0 代替全部错误判断。

如果模式包含 /./、/../ 或以斜杠开头，还要先按 Doublestar 的规则处理路径基准；这类模式可能直接返回空结果，和静态前缀不存在不是同一个问题。

几个容易混淆的问题

只想匹配文件，能解决前缀不存在吗？

不能。WithFilesOnly() 只改变结果中是否包含目录，不负责检查静态前缀。

** 写在前缀后面就一定会递归吗？

只有把 ** 作为独立路径组件使用，才符合 Doublestar 的 globstar 语义。像 path/to/**.yaml 与 path/to/**/*.yaml 的含义不同。

什么时候应该保留默认空结果？

当目录本来就是可选来源，而且“没有来源”不会破坏任务语义时可以保留。只要缺目录意味着部署不完整、配置缺失或租户初始化失败，就应该显式开启 WithFailOnPatternNotExist()。

这次问题的结论并不是“Doublestar 找不到目录却成功了”，而是默认 API 把不存在前缀归入了无匹配结果。把目录必需性表达在选项里，再分别处理 ErrPatternNotExist、ErrBadPattern 和普通 I/O 错误，空结果才不会掩盖部署问题。