Go io/fs.ReadDir 如何避免目录遍历顺序误判：排序约定、错误处理与测试边界

目录索引偶尔把同一批文件排成不同顺序时，先别急着给业务层补一个排序。Go 的 io/fs.ReadDir 本身承诺按文件名排序，但它和底层文件对象的分批读取接口不是同一个契约；如果代码把两者混用，错误处理和顺序假设就会一起出问题。

一次目录索引错乱，问题不在文件系统

一个小型构建工具会读取 assets/ 下的模板文件，生成索引 JSON。开发机上结果一直稳定，换成远端对象文件系统的适配器后，索引中的文件顺序偶尔变化。最初的修复是在业务层对结果再排一次序，但这掩盖了真正的边界：调用方有时使用了 fs.ReadDir，有时直接拿到底层文件的 ReadDir(20)。

这两个名字相似，返回的却是不同层次的能力。前者是 fs.FS 的便利函数；后者是目录文件的增量读取方法。排查时应先记录调用入口、传入的 n 和每批返回的文件名，别只看最后拼出的 JSON。

完整读取时，fs.ReadDir 会按文件名排序

fs.ReadDir 接收一个文件系统和目录名。成功时，它返回目录项列表，并按文件名排序；如果底层文件系统实现了 ReadDirFS，函数可以直接使用该优化接口，否则会打开目录并通过文件对象读取。

func listNames(fsys fs.FS, dir string) ([]string, error) {
	entries, err := fs.ReadDir(fsys, dir)
	if err != nil {
		return nil, err
	}

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

这段代码把稳定顺序交给了 fs.ReadDir。它适合生成索引、计算目录快照或编写期望顺序固定的测试。需要注意，排序依据是目录项的文件名，不是修改时间、文件大小，也不是业务里的自然语言顺序。

分批读取时，不要把每一批当成完整排序结果

如果拿到的是实现了 fs.ReadDirFile 的目录文件，可以调用 ReadDir(n) 分批读取。n > 0 表示最多返回 n 个目录项；n 则要求读取剩余目录项。分批接口的重点是游标和结束条件，不是让调用方重新猜测全局顺序。

func readInBatches(f fs.ReadDirFile, batchSize int) ([]fs.DirEntry, error) {
	var all []fs.DirEntry
	for {
		batch, err := f.ReadDir(batchSize)
		all = append(all, batch...)
		if err != nil {
			if errors.Is(err, io.EOF) {
				return all, nil
			}
			return all, err
		}
		if len(batch) == 0 {
			return all, nil
		}
	}
}

实际项目里，若业务只需要“整个目录按文件名排序”，优先用 fs.ReadDir 或一次性的 ReadDir(0)。只有目录很大、需要逐批处理或要控制内存时，才采用正向消费的批处理循环。是否有序，应由被调用实现的文档和最终验证决定，不能由某台机器上的样本推断。

部分结果和错误必须一起处理

目录读取可能在中途失败。分批读取时，函数可能已经返回一部分目录项，同时给出非空错误。此时最危险的写法是先把部分结果写入索引，再忽略错误；这样生成的文件看起来完整，实际上缺了一段。

entries, err := f.ReadDir(50)
if err != nil {
	// entries 可能不是空的，先记录数量，再决定是否放弃本次索引。
	return fmt.Errorf("read directory batch (%d entries): %w", len(entries), err)
}
consume(entries)

如果采用“尽力而为”的产品语义，也要把状态写出来，例如标记索引为 incomplete，并保留错误原因。对配置、模板和迁移文件这类输入，我更建议任何非 EOF 错误都让本次构建失败，避免把残缺目录当成合法结果。

把顺序和错误边界写进测试

testing/fstest.MapFS 适合验证普通的 fs.ReadDir 调用。测试重点不是重复标准库的排序实现，而是确认自己的业务确实使用了稳定入口，并且没有偷偷依赖修改时间或插入顺序。

func TestListNamesSortsByFileName(t *testing.T) {
	fsys := fstest.MapFS{
		"assets/zeta.txt":  &fstest.MapFile{},
		"assets/alpha.txt": &fstest.MapFile{},
		"assets/mid.txt":   &fstest.MapFile{},
	}

	got, err := listNames(fsys, "assets")
	if err != nil {
		t.Fatal(err)
	}
	want := []string{"alpha.txt", "mid.txt", "zeta.txt"}
	if !reflect.DeepEqual(got, want) {
		t.Fatalf("got %v, want %v", got, want)
	}
}

对批处理代码，再增加三组用例：目录项多于批大小时是否消费完；空目录是否返回空切片和 nil；自定义文件系统在第二批失败时，调用方是否保留错误而不是发布残缺结果。测试里可以使用一个专门记录调用次数的假实现，观察边界，不要只用本机真实目录。

这几个近似写法最容易留下隐患

• 用 os.File.Readdir 的返回顺序代表所有 fs.FS 实现的顺序。不同接口的契约不能互相替代。
• 把 io.EOF 当成普通失败，导致已经完整读取的批处理被判错；也不能把其他错误都当成 EOF。
• 只断言文件数量，不断言文件名顺序，结果把顺序回归留到了线上。
• 读取过程中遇到错误仍生成成功状态的索引，下一步再由业务层猜哪些文件缺失。

常见问题

fs.ReadDir 返回结果一定按修改时间排列吗？

不是。它按文件名排序。如果产品要求“最近修改的文件在前”，需要显式调用 entry.Info() 取得时间后重新排序，并处理元数据读取错误。

为什么分批读取还要单独处理 EOF？

分批接口用 EOF 表示已经读到目录末尾。EOF 不是业务失败，但其他错误可能伴随部分结果返回，必须保留并向上层报告。

目录很小时可以总是调用 fs.ReadDir 吗？

可以。它更适合需要完整、稳定列表的场景；只有需要限制内存、边读边处理或目录规模很大时，才值得引入分批接口。

结语

目录顺序问题的关键不在于“再加一次 sort”，而在于先选对读取接口。完整列表用 fs.ReadDir 获得文件名排序；分批读取则围绕游标、EOF、部分结果和中途错误设计循环。把这些契约写成测试后，换文件系统实现、换部署环境或调整批大小，都不会再靠偶然顺序维持正确性。