Go io/fs.ReadDirFile.ReadDir 怎样分批读取目录项

目录很大时，不要把“按批次读取”和“读取全部剩余项”混成同一个返回约定。io/fs.ReadDirFile.ReadDir 的关键是 n：当 n > 0 时，每次最多返回 n 个目录项，读到末尾用裸 io.EOF 表示结束；当 n 时，一次返回当前目录文件剩余的全部项，完整读完时错误值是 nil。

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

这篇只讨论接口契约、批次游标和错误处理，不把它扩展成目录遍历性能基准。实际代码还要记得关闭目录文件，并根据目录规模决定是否保留全部结果。

先确认目录文件能提供 ReadDirFile

fs.File 只要求提供 Stat、Read 和 Close。目录文件还应实现 fs.ReadDirFile，后者额外提供 ReadDir(n int)。因此，拿到 fs.File 后先做接口断言，不能假定任何文件都能读目录项。

package main

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

func readDirectory(fsys fs.FS, name string) error {
    file, err := fsys.Open(name)
    if err != nil {
        return err
    }
    // 目录句柄属于调用方，所有返回路径都要释放它。
    defer file.Close()

    dir, ok := file.(fs.ReadDirFile)
    if !ok {
        // 普通文件或不完整的 FS 实现不能直接调用 ReadDir。
        return fmt.Errorf("%s does not implement fs.ReadDirFile", name)
    }

    // 后续代码只使用 ReadDirFile 的目录读取契约。
    entries, err := dir.ReadDir(0)
    if err != nil {
        return err
    }
    for _, entry := range entries {
        fmt.Println(entry.Name())
    }
    return nil
}

func main() {
    if err := readDirectory(os.DirFS("."), "."); err != nil {
        fmt.Println(err)
    }
}

这里的 0 代表读取剩余项，后文会解释它与正数批次的差别。如果只需要通用的“按名称读取目录”，也可以使用顶层 fs.ReadDir；它会在底层打开目录文件、调用 ReadDir(-1)，并按文件名排序。直接调用接口则保留目录文件的游标和底层目录顺序。

n 大于 0 时怎样处理批次与 io.EOF

设定正数 n 后，同一个目录文件上的多次调用会继续读取后面的目录项。读到目录末尾时，规范要求空结果伴随非 nil 错误；此错误应当是 io.EOF 本身，而不是包了一层的同值错误。

package main

import (
    "fmt"
    "io"
    "io/fs"
)

func readBatches(dir fs.ReadDirFile, batchSize int) error {
    if batchSize  0 的末尾信号是裸 io.EOF，收到后结束循环。
            return nil
        }
        // 其他错误不能当作正常结束，交给上层决定是否重试或回滚。
        return err
    }
}

这个循环有两个容易漏掉的点。第一，先消费 entries 再判断错误，避免丢掉“部分结果 + 错误”的返回。第二，不能只判断 len(entries) == 0：空批次可能表示目录结束，也可能是底层 I/O 问题，必须读取 err。

n 小于等于 0 时不要等待 io.EOF

ReadDir(0)、ReadDir(-1) 都表示读取当前游标之后的全部目录项。如果一路成功读到末尾，返回的是结果切片和 nil，不是 io.EOF。只有中途出现错误，才会返回已经读取的部分结果与非 nil 错误。

func readRemaining(dir fs.ReadDirFile) ([]fs.DirEntry, error) {
    // 非正 n 一次取完当前目录文件剩余内容，适合目录规模可控的场景。
    entries, err := dir.ReadDir(-1)
    if err != nil {
        // 即使 err 非 nil，也要由调用方决定是否保留 entries。
        return entries, err
    }
    // 完整成功时不要把 nil 错误改写成 io.EOF。
    return entries, nil
}

如果代码把所有非 nil 都当成失败，那么正数批次的正常结束会被误报；如果代码把所有空结果都当成成功，那么权限错误或读取错误又会被吞掉。把 n 的取值和错误契约写在同一处，排查会更直接。

按场景选择批量读取还是一次取完

目录项数量可控、后续需要整体排序或一次性构建索引时，n 更简单；目录可能很大、需要边读边处理或希望限制单次内存占用时，使用正数批次。批量读取并不自动改变底层文件系统的耗时，也不保证网络文件系统或上层缓存立即返回固定数量的项，它只约束接口返回边界。

无论哪种方式，都要在同一个目录文件上连续调用，不能每次重新 Open 后期待自动接续；重新打开通常会得到新的目录读取位置。处理完成后调用 Close，让文件描述符或自定义文件系统资源及时释放。

常见问题

为什么正数批次读完是 io.EOF，而一次读取是 nil？

这是接口刻意区分的两种契约：正数 n 需要调用方知道“本批次之后是否还有项”，所以末尾用裸 io.EOF；非正 n 的目标就是读完剩余项，完整成功本身已经足够表达结束。

ReadDir 返回部分目录项和错误时能不能直接丢弃？

不要默认丢弃。先记录已处理范围和错误，再根据业务决定重试、跳过或终止。尤其是批量导入、索引构建这类任务，部分结果可能已经产生外部副作用。

小结

记住三条即可：正数 n 用来控制每批最多读取多少项；同一目录文件的后续调用会继续向后；正数批次的末尾检查裸 io.EOF，非正 n 完整成功则检查 nil。再配合接口断言和 Close，就能把目录读取的边界写清楚。