Go io fs ReadDir 如何按目录层级筛选大批量文件

批量扫描归档目录时，最容易踩的坑不是“怎么读到文件”，而是一次性把不需要的层级和文件全塞进内存。Go 的 io/fs 提供了一个够小的入口：用 os.DirFS 固定扫描根目录，再用 fs.ReadDir 读取某一层的 DirEntry，把目录判断、文件名筛选和错误处理拆开。

如果只需要当前目录或有限层级，优先用 fs.ReadDir 做定向读取；不要为了筛几个后缀直接递归整棵目录树。

先把扫描范围固定在 os.DirFS

示例假设归档根目录是 /srv/archive，目标是只找第一层目录中的 .json 文件。os.DirFS(root) 返回一个 fs.FS，后续路径从这个根开始计算，因此调用时传 .、2026 这样的相对路径。

package main

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

func main() {
    archive := os.DirFS("/srv/archive")
    files, err := filesInLevel(archive, ".")
    if err != nil {
        log.Fatal(err)
    }
    for _, file := range files {
        fmt.Println(file)
    }
}

func filesInLevel(fsys fs.FS, dir string) ([]string, error) {
    entries, err := fs.ReadDir(fsys, dir)
    if err != nil {
        return nil, err
    }
    var matched []string
    for _, entry := range entries {
        if entry.IsDir() {
            continue
        }
        if strings.HasSuffix(entry.Name(), ".json") {
            matched = append(matched, dir+"/"+entry.Name())
        }
    }
    return matched, nil
}

fs.ReadDir 的结果为什么适合做当前层筛选

fs.ReadDir(fsys, dir) 会返回该目录的 []DirEntry，并按文件名排序。这个排序不是递归排序，也不会替你进入子目录；它只保证当前返回切片的文件名顺序稳定。代码里的控制流可以压缩成四个真实节点：fs.ReadDir 取得条目，DirEntry.IsDir 拦住下钻，entry.Name 读取名字，最后把命中的文件放进 matched。

因此，示例只扫描 . 这一层。若要扫描 2026/08，应显式把这个相对路径传给函数，而不是误以为 fs.ReadDir 会自动递归。

把文件名过滤和错误分支分开

过滤逻辑最好放在成功读取之后。目录不存在、权限不足、路径不合法时，fs.ReadDir 会先返回错误；如果此时仍然遍历 entries，很容易把真正的故障伪装成“没有匹配文件”。

func jsonFiles(fsys fs.FS, dir string) ([]string, error) {
    entries, err := fs.ReadDir(fsys, dir)
    if err != nil {
        return nil, fmt.Errorf("read %q: %w", dir, err)
    }

    matched := make([]string, 0, len(entries))
    for _, entry := range entries {
        if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
            continue
        }
        matched = append(matched, entry.Name())
    }
    return matched, nil
}

这里的验收点有两个：目录无权访问时调用方能看到带目录名的错误；目录正常但没有 .json 时返回空切片和 nil。两者不能混为一谈。

大目录不要把 ReadDir 的切片当成无限资源

fs.ReadDir 的便利代价是一次拿到当前目录的全部条目。如果单层目录里有几十万项，[]DirEntry 本身和底层文件系统读取都可能形成明显的瞬时内存压力。此时可以打开目录并使用 ReadDirFile.ReadDir(n)，让 n 控制每批读取数量。

f, err := fsys.Open("2026/08")
if err != nil {
    return nil, err
}
defer f.Close()

reader, ok := f.(fs.ReadDirFile)
if !ok {
    return nil, fmt.Errorf("%q does not support batched ReadDir", dir)
}

for {
    batch, err := reader.ReadDir(256)
    for _, entry := range batch {
        if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".json") {
            matched = append(matched, entry.Name())
        }
    }
    if err == io.EOF {
        break
    }
    if err != nil {
        return nil, err
    }
}

分批读取时要导入 io，并正确处理“最后一批数据同时伴随 io.EOF”的实现差异。上面的示例先消费 batch，再判断错误，避免漏掉末尾条目。需要全局字典序时，还要自行记录并排序命中结果；批量读取的目录顺序不等同于 fs.ReadDir 的排序承诺。

常见问题：ReadDir 筛选文件时的几个边界

fs.ReadDir 会递归子目录吗？

不会。它只读取传入路径对应的当前目录；需要递归时使用 fs.WalkDir，但要意识到递归会扩大访问范围和处理成本。

为什么不直接用 filepath.Join 拼路径？

io/fs 的路径约定是 UTF-8、无根、用斜杠分隔。对 os.DirFS 和其他 fs.FS 实现，优先使用 path.Join 或手动维护 slash 路径，别把系统绝对路径传进去。

只按后缀判断 JSON 文件够安全吗？

它只能判断名字，不验证内容。需要确认格式时，再用 os.Open 或 fs.ReadFile 读取并交给 JSON 解码器；不要把扩展名筛选当成内容校验。

把验收结果留在测试里

小目录测试应验证三件事：返回顺序稳定、子目录没有被误收集、读取错误没有被吞掉。可以用 testing/fstest.MapFS 构造内存文件系统，让测试与真实磁盘解耦；生产扫描再切换到 os.DirFS。这会把“目录范围”和“筛选规则”变成可复查的代码，而不是散落在调用方的字符串拼接里。