Go fs.FileInfoToDirEntry 怎样适配目录条目接口

如果手上已经有一个 fs.FileInfo，但下游函数要求的是 fs.DirEntry，直接做类型断言并不能完成适配。标准库提供的正确入口是 fs.FileInfoToDirEntry(info)：它返回一个由原始 FileInfo 驱动的 DirEntry 包装器；传入 nil 时返回 nil。

官方参考：https://pkg.go.dev/io/fs#FileInfoToDirEntry

先分清 FileInfo 和 DirEntry 的职责

fs.FileInfo 描述一个已经拿到的文件或目录信息，包含名称、大小、模式、修改时间、是否为目录以及底层系统信息。fs.DirEntry 则更像“目录读取结果中的一个条目”，除了名称和类型，还提供 Info() 来取得完整的 FileInfo。

这两个接口有重叠，但它们的调用场景不同。比如一个通用格式化函数只接受 DirEntry，而你的数据来自 fs.Stat 或 fs.Lstat，此时需要一个明确的接口适配层。不要自己定义一套匿名结构体去拼字段，标准库已经把这种映射固定下来了。

用 FileInfoToDirEntry 完成一次适配

最小用法只有一行。示例先构造一个测试用的 FileInfo，再把它交给只接受 DirEntry 的处理函数。实际项目中，info 常常来自 fs.Stat、fs.Lstat 或自定义文件系统。

package main

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

// printEntry 只依赖 DirEntry，调用方不需要知道条目最初来自哪里。
func printEntry(entry fs.DirEntry) error {
	if entry == nil {
		// nil 不能继续调用 Name、Type 或 Info，先把输入边界说清楚。
		return fmt.Errorf("目录条目为空")
	}

	info, err := entry.Info()
	if err != nil {
		// 通用 DirEntry 可能在 Info 阶段失败，不能忽略错误。
		return fmt.Errorf("读取条目详情失败: %w", err)
	}

	fmt.Printf("name=%s dir=%t size=%d\\n", entry.Name(), entry.IsDir(), info.Size())
	return nil
}

func main() {
	// MapFS 只用于提供一个可重复的 FileInfo 来源，不代表真实磁盘截图。
	fileSystem := fstest.MapFS{"docs/readme.md": {Data: []byte("hello")}}
	info, err := fs.Stat(fileSystem, "docs/readme.md")
	if err != nil {
		panic(err)
	}

	entry := fs.FileInfoToDirEntry(info)
	if err := printEntry(entry); err != nil {
		panic(err)
	}
}

这里的关键不是把具体类型“转换”为另一个具体类型，而是让同一份信息满足另一个接口。适配之后，printEntry 只关心 DirEntry 的契约，未来换成 os.DirFS、fstest.MapFS 或自定义文件系统时，处理函数不需要修改。

看懂四个方法到底返回什么

标准库内部用一个很薄的包装值保存原来的 FileInfo。因此，适配结果的四个方法可以按下面的关系理解：

package main

import (
	"fmt"
	"io/fs"
)

func describe(entry fs.DirEntry) {
	// Type 适合做轻量类型判断；需要大小、时间或权限时必须调用 Info。
	typeBits := entry.Type()
	info, err := entry.Info()
	if err != nil {
		fmt.Printf("%s: info error: %v\\n", entry.Name(), err)
		return
	}

	fmt.Printf("name=%s type=%s mode=%s size=%d\\n",
		entry.Name(), typeBits, info.Mode(), info.Size())
}

例如普通文件的 Type() 可能是零值，不能据此推断它没有权限信息；权限位要从 info.Mode() 读取。反过来，目录判断优先使用 IsDir()，语义更直观，也不需要调用者自己解析模式位。

把适配后的条目交给通用处理函数

适配最有价值的地方，是把“信息来源”和“条目处理”拆开。下面的函数只接受 DirEntry，同时演示了类型判断和完整信息读取。调用方可以把它接在目录读取结果、测试数据或 FileInfoToDirEntry 后面。

package main

import (
	"fmt"
	"io/fs"
)

// acceptEntry 展示一个可复用的 DirEntry 消费端。
func acceptEntry(entry fs.DirEntry) (string, error) {
	if entry == nil {
		return "", fmt.Errorf("不能处理 nil DirEntry")
	}

	if entry.IsDir() {
		// 目录只输出类型；是否继续遍历由上层策略决定。
		return entry.Name() + " (directory)", nil
	}

	info, err := entry.Info()
	if err != nil {
		return "", fmt.Errorf("读取 %q 的 FileInfo 失败: %w", entry.Name(), err)
	}
	// 文件大小来自完整 FileInfo，而不是 DirEntry.Type。
	return fmt.Sprintf("%s (%d bytes)", entry.Name(), info.Size()), nil
}

这个拆分方式也方便测试：可以用 fstest.MapFS 得到真实的 DirEntry，也可以用一个小型 FileInfo 实现经过适配后测试消费端。不要为了测试而让处理函数依赖操作系统路径。

类型断言和错误边界不要混在一起

FileInfoToDirEntry 的结果是一个 DirEntry，不是公开的具体包装类型。通常不应该把它断言回某个内部结构，也不能假设所有 DirEntry.Info() 都像这个适配器一样永远成功。

更稳妥的做法是：先检查 entry == nil，再按接口调用；需要完整属性时处理 Info() 的错误；只有在业务确实依赖某个自定义扩展接口时，才做带 ok 的类型断言。

func readEntry(entry fs.DirEntry) error {
	if entry == nil {
		return fmt.Errorf("nil DirEntry")
	}

	info, err := entry.Info()
	if err != nil {
		// 目录在读取后可能被删除或重命名，Info 失败必须由策略决定。
		return err
	}

	// 不把 Type 当作完整 Mode；完整权限和时间仍从 info 读取。
	_ = entry.Type()
	_ = info.Mode()
	return nil
}

最小测试覆盖三类输入

最后用三类断言收口：普通文件的名称和大小保持不变，目录仍被识别为目录，nil 输入得到 nil 输出。这里的测试重点是接口映射，不是验证某个真实目录的运行结果。

package main

import (
	"io/fs"
	"testing"
	"testing/fstest"
)

func TestFileInfoToDirEntry(t *testing.T) {
	// MapFS 让测试输入固定，避免依赖本机目录和权限。
	fileSystem := fstest.MapFS{
		"docs/readme.md": {Data: []byte("hello")},
		"docs":           {Mode: fs.ModeDir},
	}

	fileInfo, err := fs.Stat(fileSystem, "docs/readme.md")
	if err != nil {
		t.Fatal(err)
	}
	entry := fs.FileInfoToDirEntry(fileInfo)
	if entry == nil || entry.Name() != "readme.md" {
		t.Fatalf("unexpected entry: %#v", entry)
	}

	if got, err := entry.Info(); err != nil || got.Size() != 5 {
		t.Fatalf("unexpected info: got=%v err=%v", got, err)
	}

	if fs.FileInfoToDirEntry(nil) != nil {
		t.Fatal("nil FileInfo should produce nil DirEntry")
	}
}

常见问题

FileInfoToDirEntry 会重新访问磁盘吗？

它只是把已有的 FileInfo 包装成 DirEntry。这个适配动作本身不会再次 stat；原始信息什么时候取得，取决于调用它之前的代码。

为什么 Type 看不到 0644 这样的权限？

Type() 只返回类型位。需要权限、大小或修改时间时调用 Info()，再从 FileInfo.Mode() 读取完整模式。

FileInfoToDirEntry(nil) 应该怎么处理？

标准库会返回 nil。如果下游函数不接受空条目，应在适配后立即返回带上下文的错误，避免延迟到调用 Name() 时才出现问题。

可以把返回值断言回原来的 FileInfo 吗？

应该通过 DirEntry.Info() 获取原来的 FileInfo 接口。不要依赖标准库内部包装类型，业务代码只应依赖公开接口契约。