Go 目录读取部分成功时怎样处理错误

目录扫描遇到错误时，最容易写出的一句代码是 if err != nil { return err }，但这可能把本次调用已经返回的目录项一起丢掉。Go 的目录读取 API 允许“结果和错误同时有值”，正确顺序通常是先处理 entries，再根据 err 判断是目录结束还是读取失败。

对于 os.ReadDir，错误发生前已经读到的目录项会随错误返回；对于 (*os.File).ReadDir(n)，批量读取时要保留已经拿到的条目，空结果配合 io.EOF 表示正常读完。不要因为 error 非 nil 就先 return。

• 全量入口：os.ReadDir(path) 返回按文件名排序的目录项。
• 批量入口：file.ReadDir(n) 保留目录读取位置，适合大目录分批处理。
• 判断顺序：先消费本次返回的 []fs.DirEntry，再区分 io.EOF 与真实错误。

先分清两个 ReadDir 的返回约定

os.ReadDir(name) 面向路径，调用方不需要自己打开和关闭目录。它会返回目录项，并按文件名排序；如果读取过程中出现错误，官方约定是把能够读到的条目和错误一起返回。因此，下面这种写法会损失部分结果：

entries, err := os.ReadDir(path)
if err != nil {
    // 这里直接返回会丢掉 entries 中已经读到的目录项。
    return err
}
for _, entry := range entries {
    // 成功路径才处理条目，无法表达“部分成功”。
    handle(entry)
}

如果任务只接受完整快照，遇到错误后直接失败可以是合理策略，但仍建议记录已经读取到的数量，方便排查。若任务是清理、索引或迁移这类允许尽力完成的扫描，就应该先处理已返回的条目，再把错误交给上层。

(*os.File).ReadDir(n) 面向已经打开的目录文件。n > 0 时每次最多返回 n 个条目，后续调用会继续读取；读到目录末尾时，空结果配合 io.EOF 表示结束。n 时读取剩余条目，成功结束返回 nil error，遇到中途错误则保留已读条目并返回错误。

用固定批次读取并先处理已有目录项

对大目录或需要边读边处理的任务，打开目录后使用固定批次更容易控制单次返回量。关键不在于把 128 换成某个“完美数字”，而在于每轮都先遍历 entries，再处理 readErr：

package main

import (
    "errors"
    "fmt"
    "io"
    "os"
)

// scanDirBatch 按批次扫描目录，并保留已经读取到的条目数量。
func scanDirBatch(path string, handle func(os.DirEntry) error) (int, error) {
    dir, err := os.Open(path)
    if err != nil {
        return 0, fmt.Errorf("open directory %q: %w", path, err)
    }
    defer dir.Close() // 无论扫描成功还是失败，都释放目录句柄。

    processed := 0
    for {
        entries, readErr := dir.ReadDir(128) // 固定批次，避免一次拿完大目录。

        // 即使 readErr 非 nil，也先处理本轮已经返回的 entries。
        for _, entry := range entries {
            if err := handle(entry); err != nil {
                return processed, fmt.Errorf("handle %q: %w", entry.Name(), err)
            }
            processed++
        }

        if readErr == nil {
            // 还有可能存在下一批，继续从同一个目录位置读取。
            continue
        }
        if errors.Is(readErr, io.EOF) && len(entries) == 0 {
            // n > 0 时，空批次 + EOF 表示已经正常读完。
            return processed, nil
        }

        // 非 EOF 错误表示扫描未完成，但前面的条目已经处理过。
        return processed, fmt.Errorf("read directory %q: %w", path, readErr)
    }
}

这个函数把三个结果分开：处理器失败属于业务错误；空批次的 io.EOF 是正常结束；其他读取错误则保留处理数量并向上返回。这样调用方既不会重复处理前面的条目，也不会把目录未读完误报成完整成功。

为什么要先处理 entries，再判断 err

Go 的许多读取接口都允许一次调用返回“已经取得的部分数据”和错误。目录读取尤其适合采用这种约定：操作系统或文件系统层可能在枚举过程中遇到权限、I/O 或目录状态变化，但此前已经返回的 DirEntry 仍然是有效的本轮结果。

因此不要把错误判断写在处理循环前面。更稳妥的最小模板如下：

entries, err := dir.ReadDir(batchSize)

// 先消费本轮结果，避免非 nil error 掩盖已读条目。
for _, entry := range entries {
    if err := consume(entry); err != nil {
        return err
    }
}

// 处理完 entries 后，再判断本轮是否结束或失败。
if err != nil {
    if errors.Is(err, io.EOF) && len(entries) == 0 {
        return nil
    }
    return err
}

对于 n > 0 的 File.ReadDir，通常在最后一次空读取时收到 io.EOF。保留 len(entries) == 0 这个条件，可以避免把一个同时携带条目的异常返回误当作普通结束；非 EOF 错误也不应该被吞掉。

按任务选择全量、批量或容错策略

如果业务要求一致性快照，例如生成完整的目录清单，那么“处理部分结果后返回错误”并不等于业务成功：可以把结果写入临时集合，但最终状态必须标记为未完成。相反，如果只是尽可能删除过期文件，已完成的删除可以保留，调用方只需记录失败路径和错误。

完整片段：把部分成功交给上层决定

package main

import (
    "errors"
    "fmt"
    "io"
    "os"
)

// readNames 返回已经读到的名称；只要扫描未完成，就同时返回错误。
func readNames(path string) ([]string, error) {
    dir, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer dir.Close() // 目录句柄的释放不依赖最终是否读到 EOF。

    names := make([]string, 0, 128)
    for {
        entries, readErr := dir.ReadDir(128)
        for _, entry := range entries {
            // 先保存本轮结果；下方的错误判断不能覆盖它们。
            names = append(names, entry.Name())
        }

        if readErr == nil {
            continue
        }
        if errors.Is(readErr, io.EOF) && len(entries) == 0 {
            return names, nil
        }
        return names, fmt.Errorf("read %q after %d entries: %w", path, len(names), readErr)
    }
}

调用方可以依据返回的 names 和 err 作不同决定：err == nil 表示目录完整读完；err != nil 但 len(names) > 0 表示拿到部分结果，不能当成完整快照；len(names) == 0 则需要重点查看打开目录或第一次读取的错误。

常见问题

os.ReadDir 返回非 nil error 时，entries 还能用吗？

能。官方约定是错误发生前读到的目录项会一起返回。是否继续使用它们由业务一致性要求决定，但不应因为 error 非 nil 就无条件丢弃。

File.ReadDir 读到末尾一定会返回 io.EOF 吗？

当 n > 0 时，读到末尾的空批次用 io.EOF 表示；当 n 时，成功读完剩余条目返回 nil error，不要把正常完成误判为 EOF 错误。

为什么不能只写 if err != nil 就 return？

因为一次读取可能同时带回已读条目和错误。提前返回会丢掉可处理的数据，也让上层无法知道扫描已经完成了多少。

大目录应该把 n 设置得越小越好吗？

不一定。较小批次降低单次结果量，但会增加系统调用和循环次数；应根据单条处理成本、内存预算和错误恢复粒度选择，并保持“先处理 entries，再判断 err”的顺序。

官方 API 参考：https://pkg.go.dev/os#ReadDir、https://pkg.go.dev/os#File.ReadDir、https://pkg.go.dev/io/fs#ReadDirFile、https://pkg.go.dev/io/fs#DirEntry。