Go os.ReadDir 与 DirEntry.Type 如何减少目录扫描中的额外 Stat 调用

做目录扫描时，最容易写出的代码是“先拿到文件名，再对每一项调用一次 Stat”。如果任务只是筛选普通文件，这一步往往是多余的：os.ReadDir 已经给了 DirEntry，可以先用 DirEntry.Type 判断类型，只有确实要读取大小或修改时间时，再调用 entry.Info。

目录扫描的省力写法不是永远不调用 Stat，而是把类型筛选放在前面，把完整元数据读取留给真正需要它的分支。

os.ReadDir 返回的 DirEntry 到底包含什么

os.ReadDir 适合一次读取一个目录。它返回的条目按文件名排序，调用方可以先拿到名称和类型位，再决定是否需要更重的元数据读取。这个顺序很适合配置目录、插件目录和上传目录的白名单扫描。

先用 DirEntry.Type 筛掉不需要的目录项

下面的例子只收集当前目录中的普通文件名。Type().IsRegular() 使用已有类型位做判断；对这个任务来说，拿到文件名就够了，不需要为每个条目继续读取完整信息。

package main

import (
    "fmt"
    "os"
)

func regularNames(dir string) ([]string, error) {
    entries, err := os.ReadDir(dir)
    if err != nil {
        return nil, err
    }

    names := make([]string, 0, len(entries))
    for _, entry := range entries {
        if !entry.Type().IsRegular() {
            continue
        }
        names = append(names, entry.Name())
    }
    return names, nil
}

func main() {
    names, err := regularNames("./configs")
    if err != nil {
        panic(err)
    }
    fmt.Println(names)
}

这里的控制流很窄：os.ReadDir 负责取目录项，DirEntry.Type 负责做一次类型判断，普通文件才进入结果切片。目录、符号链接或其他类型直接跳过，整个循环没有调用 entry.Info 或 Stat。

需要文件大小时，再让 entry.Info 进入分支

如果需求变成“只处理大于 1 MiB 的普通文件”，类型筛选仍然应该放前面。通过筛选后再调用 entry.Info，可以避免给目录和明显不相关的条目读取完整信息；同时，entry.Info 的错误必须保留在当前条目的处理路径里。

func largeRegularNames(dir string, limit int64) ([]string, error) {
    entries, err := os.ReadDir(dir)
    if err != nil {
        return nil, err
    }

    var names []string
    for _, entry := range entries {
        if !entry.Type().IsRegular() {
            continue
        }

        info, err := entry.Info()
        if err != nil {
            return nil, fmt.Errorf("read info for %s: %w", entry.Name(), err)
        }
        if info.Size() >= limit {
            names = append(names, entry.Name())
        }
    }
    return names, nil
}

这段代码把两个职责拆开：DirEntry.Type 负责便宜的前置筛选，entry.Info 只为需要比较大小的普通文件提供完整信息。不要把“可能要用大小”写成所有条目都先 Stat，那会让无关目录项也进入元数据路径。

Type 位不完整时，为什么不能把它当成完整结论

DirEntry.Type 返回的是类型位。某些文件系统或条目来源可能无法提供完整类型位，这时它未必能回答所有“它是不是某种对象”的问题。需要完整文件信息时，应使用 entry.Info，并根据错误决定跳过、记录或终止。

这个边界很重要：本文的优化目标是减少不必要的完整信息读取，不是把所有 Info 或 Stat 都删掉。对安全扫描、权限判断和归档规则，完整信息本身就是业务输入。

常见问题：os.ReadDir、Type 和 Info 怎么选

只想得到文件名，还需要调用 entry.Info 吗？

通常不需要。先用 DirEntry.Type 做必要的类型筛选，再读取 entry.Name() 即可。

DirEntry.Type 能替代 Stat 吗？

不能完全替代。它适合判断已有的类型位；需要大小、权限或修改时间时，仍应调用 entry.Info 或按场景使用完整状态读取。

entry.Info 失败时应该跳过还是返回错误？

配置发现类任务通常应记录条目并返回错误，避免静默漏配置；容错型索引任务可以记录后跳过，但要让调用方知道发生过不完整扫描。

把调用顺序变成扫描检查清单

• 先确认任务只需要名称、类型，还是还需要大小和时间。
• 用 os.ReadDir 读取目录后，优先用 DirEntry.Type 缩小候选。
• 只有进入完整元数据分支时才调用 entry.Info，并检查 error。
• 用真实目录规模和文件系统环境复测，确认减少的是无效读取，而不是漏掉必要信息。

目录扫描的性能收益来自调用边界清楚，而不是把某个 API 当成万能替代品。先筛选、后取详情，代码更容易解释，遇到特殊文件系统时也更容易补上准确的错误处理。