Go os.ReadDir 按名称读取目录条目的实现方式

做目录导入、模板扫描或配置发现时，最省心的入口通常是 os.ReadDir(path)：它一次读取目录，并把返回的 []fs.DirEntry 按文件名排序。需要注意的是，这个 API 适合拿到完整列表；如果目录很大，应该打开目录后用 File.ReadDir(n) 分批消费。

用 os.ReadDir 先得到稳定的目录清单

常见任务是扫描一个目录，只处理其中的配置文件或模板文件。下面的写法把错误处理放在入口，把排序交给标准库，循环中只保留当前任务真正需要的字段。

package main

import (
    "fmt"
    "log"
    "os"
)

func main() {
    // os.ReadDir 返回全部条目，并按文件名排序，适合生成可重复的清单。
    entries, err := os.ReadDir("fixtures")
    if err != nil {
        log.Fatal(err) // 目录不存在、无权限等错误在入口直接暴露。
    }
    for _, entry := range entries {
        kind := "file"
        if entry.IsDir() {
            kind = "dir"
        }
        fmt.Printf("%s\t%s\n", kind, entry.Name())
    }
}

排序依据是条目的文件名，而不是修改时间、文件大小或自然数顺序。例如 item-10 与 item-2 仍按字符串比较规则排列。需要自定义业务排序时，先复制名称或元数据，再使用自己的排序函数，不要把标准库的顺序误认为自然排序。

DirEntry 负责轻量判断，Info 负责补充元数据

fs.DirEntry 的价值在于先用轻量信息筛选目标。Name 得到基础名，IsDir 判断目录，Type 返回类型位；只有确实要拿文件大小、权限或时间时，才调用 Info。这样可以避免对不需要的条目逐一取完整状态。

for _, entry := range entries {
    // 先筛选扩展名和目录，避免对所有条目都调用 Info。
    if entry.IsDir() || filepath.Ext(entry.Name()) != ".tmpl" {
        continue
    }
    info, err := entry.Info()
    if err != nil {
        // 条目可能在扫描后被删除；单条失败时记录并继续处理其他文件。
        log.Printf("读取 %s 元数据失败: %v", entry.Name(), err)
        continue
    }
    fmt.Printf("%s %d bytes\n", entry.Name(), info.Size())
}

这段循环需要在 import 中补上 path/filepath、fmt 和 log。符号链接、权限变化或并发删除都可能让 Info 失败，所以不要把“清单已经拿到”理解成“每个条目的状态永远有效”。

读取失败时怎样判断部分结果能不能用

os.ReadDir 的返回值是“条目切片加错误”。官方语义允许在读取目录途中出错时返回已经读到的条目，同时返回错误。因此只要 err != nil，就不能把切片当作完整快照。若业务允许降级，可以把部分条目用于诊断；若要生成完整配置索引，应直接返回错误并重试或报警。

大目录用 File.ReadDir(n) 分批消费

当目录条目数量可能很大时，先打开目录，再控制每次取多少条。n>0 时，读到末尾会返回条目和 io.EOF；不要把 io.EOF 当成普通失败。与 os.ReadDir 不同，这个方法按目录顺序返回，若业务依赖稳定顺序，需要在每批或汇总后自行排序。

f, err := os.Open("fixtures")
if err != nil {
    return err
}
defer f.Close() // 文件描述符由当前函数负责关闭。

for {
    // 每批只保留 128 个条目，适合持续处理大型目录。
    batch, err := f.ReadDir(128)
    for _, entry := range batch {
        handle(entry.Name())
    }
    if errors.Is(err, io.EOF) {
        break // 读完目录是正常结束，不是业务错误。
    }
    if err != nil {
        return err
    }
}

示例中的 handle 代表业务处理函数，实际代码还需要导入 errors、io，并让外层函数返回 error。如果必须全局按文件名排序，可以收集名称后统一排序；如果只需要顺序处理，则保留分批读取能减少峰值内存。

常见问题

os.ReadDir 和 ioutil.ReadDir 有什么区别？

os.ReadDir 返回 []fs.DirEntry，并按文件名排序；旧的 ioutil.ReadDir 返回 []os.FileInfo。迁移时不能只改函数名，要按需把 FileInfo 的读取改成 DirEntry.Info。

os.ReadDir 会递归子目录吗？

不会。它只读取指定目录的一层条目。递归需求应明确使用 filepath.WalkDir 或自己的队列，并单独处理符号链接和权限错误。

为什么 File.ReadDir 读出来的顺序不一样？

File.ReadDir(n) 按目录顺序分批返回，服务的是流式消费；需要文件名顺序时，汇总后调用排序，不能直接与 os.ReadDir 的结果逐项比较。