fs.FS & embed — 文件系统抽象与静态嵌入

// FS — 文件系统：一个可以打开文件的命名空间
type FS interface {
    Open(name string) (File, error)
}

// File — 单个文件：可读、可查元信息
type File interface {
    Stat() (FileInfo, error)  // 获取文件元信息
    Read([]byte) (int, error)  // 读取文件内容
    Close() error              // 关闭文件
}

// FileInfo — 文件元信息（通过 Stat() 获取）
type FileInfo interface {
    Name() string       // 文件名（不含路径）
    Size() int64        // 文件大小（字节）
    Mode() FileMode     // 文件权限
    ModTime() time.Time // 最后修改时间
    IsDir() bool        // 是否为目录
    Sys() interface{}   // 底层系统信息
}

// DirEntry — 目录条目（比 FileInfo 更轻量，来自 ReadDir）
type DirEntry interface {
    Name() string      // 文件名
    IsDir() bool       // 是否为目录
    Type() FileMode    // 文件类型位
    Info() (FileInfo, error) // 获取完整 FileInfo（可能涉及系统调用）
}

// 读取整个文件 — 等价于 os.ReadFile，但接受 fs.FS
data, err := fs.ReadFile(fsys, "config.json")

// 读取目录 — 等价于 os.ReadDir，但接受 fs.FS
entries, err := fs.ReadDir(fsys, ".")

// 通配符匹配 — 等价于 filepath.Glob，但接受 fs.FS
matches, err := fs.Glob(fsys, "*.go")

// 遍历目录树 — 等价于 filepath.WalkDir
fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
    if err != nil {
        return err // 无法访问的路径
    }
    if d.IsDir() {
        fmt.Println("DIR:", path)
    } else {
        fmt.Println("FILE:", path, d.Name())
        info, _ := d.Info()
        fmt.Println("  Size:", info.Size())
    }
    return nil
})

// 子目录视图 — 将 subdir 作为新的 fs.FS 根
subFS, err := fs.Sub(fsys, "subdir")
// subFS 中 Open("config.json") 等价于原 fsys 中 Open("subdir/config.json")

// os.DirFS 返回一个只读的 fs.FS 视图
root := os.DirFS("./templates")
data, _ := fs.ReadFile(root, "index.html")

// ⚠️ os.DirFS 的路径陷阱：
// os.DirFS("./templates") 后，Open("index.html") → ./templates/index.html ✅
// os.DirFS("./templates") 后，Open("templates/index.html") → ./templates/templates/index.html ❌
// 因为 DirFS 已经把根定在了 templates/，不需要再加这个前缀

// 使用 testing/fstest.MapFS 创建内存文件系统（不依赖真实磁盘）
testFS := fstest.MapFS{
    "config.json": {
        Data: []byte(`{"port": 8080}`),
        Mode: 0644,
    },
    "data/users.txt": {
        Data: []byte("alice\nbob\n"),
    },
    "empty_dir/placeholder": {
        // Go 1.22+：嵌入空目录需要占位文件
        Data: nil, Mode: fs.ModeDir,
    },
}

// 测试代码使用 testFS 而不是真实磁盘
data, err := fs.ReadFile(testFS, "config.json")

// WalkDir 也能正常工作
fs.WalkDir(testFS, ".", func(path string, d fs.DirEntry, err error) error {
    fmt.Println(path)
    return nil
})

// ❌ 紧耦合于 os 文件系统：只能读真实磁盘，测试需要准备真实文件
func LoadConfigOS(path string) (*Config, error) {
    data, err := os.ReadFile(path) // 直接依赖 os 包
    if err != nil {
        return nil, err
    }
    return parseConfig(data)
}

// ✅ 接受 fs.FS：可以从任何文件系统读取，测试用内存 FS
func LoadConfig(fsys fs.FS, name string) (*Config, error) {
    data, err := fs.ReadFile(fsys, name) // 依赖接口
    if err != nil {
        return nil, err
    }
    return parseConfig(data)
}

// ✅ 生产环境使用 os.DirFS
config, err := LoadConfig(os.DirFS("."), "config.json")

// ✅ 测试环境使用 fstest.MapFS
func TestLoadConfig(t *testing.T) {
    testFS := fstest.MapFS{
        "config.json": {Data: []byte(`{"port": 8080}`)},
    }
    config, err := LoadConfig(testFS, "config.json")
    // ... 断言
}

// 这些都是 os 专有，fs.FS 不支持：
os.Create("newfile.txt")       // 创建文件
os.Mkdir("newdir", 0755)       // 创建目录
os.Remove("oldfile.txt")       // 删除文件
os.Chmod("script.sh", 0755)    // 修改权限
os.Rename("a.txt", "b.txt")    // 重命名

// 读写需要分别处理：
// - 读取：用 fs.FS 接口（可替换、可测试）
// - 写入：用 os 包（只有真实文件系统）

import _ "embed"  // 必须导入（即使不直接用，因为是编译器指令）

// 嵌入单个文件为字符串
//go:embed config.json
var configData string

// 嵌入单个文件为字节切片（适合二进制文件）
//go:embed logo.png
var logoData []byte

// 嵌入整个目录为 embed.FS（实现了 fs.FS 接口）
//go:embed static/*
var staticFS embed.FS

// 嵌入多个模式
//go:embed templates/*.html
//go:embed assets/css/* assets/js/*
var allAssets embed.FS

// ✅ 正确做法
//go:embed templates/*.html
var templates embed.FS

//go:embed static
var staticFS embed.FS  // 嵌入整个 static 目录

// ❌ 错误：指令与声明之间有空行
//go:embed data.txt

var data string  // ← 空行导致 embed 指令失效！

// ❌ 错误：路径不能包含 ..（安全限制）
//go:embed ../config.json

// ❌ 错误：路径不能是绝对路径
//go:embed /etc/config.json

// ❌ 错误：变量类型不匹配
//go:embed images/*
var images string // embed.FS 赋值给 string，编译器报错

// ❌ 错误：嵌入不存在的文件（编译时检查）
//go:embed nonexistent.txt
var data []byte // 编译错误：文件不存在

//go:embed static/*
var staticFiles embed.FS

func main() {
    // 作为 HTTP 文件服务器
    subFS, _ := fs.Sub(staticFiles, "static")
    http.Handle("/", http.FileServer(http.FS(subFS)))

    // 直接读取文件
    data, _ := staticFiles.ReadFile("static/style.css")

    // 遍历嵌入的文件
    fs.WalkDir(staticFiles, ".", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        fmt.Printf("%s (size=%d)\n", path, d.Size())
        return nil
    })

    // 检查嵌入的文件是否存在
    if _, err := staticFiles.Open("static/logo.png"); err == nil {
        fmt.Println("logo.png is embedded")
    }
}

// embed.FS 实现了 fs.FS 接口，但只能读取
data, _ := fs.ReadFile(staticFiles, "config.json") // ✅ 可以

// 以下操作不可用（embed.FS 没有 Write 方法）：
// staticFiles.Create("new.txt")     ❌ 没有此方法
// staticFiles.Remove("old.txt")     ❌ 没有此方法