不能把io/fs.FS当主存储接口用，因为它仅支持只读操作（无写、删、建目录能力），fs.File为一次性对象（Close后Read必panic），且设计目标仅为静态资源加载；应定义读写分离、带context、错误归一的五方法接口：ReadFile、Stat、WriteFile、Delete、Exists。
直接用 io/fs.FS 做业务文件存储抽象是错的——它只读、不支持写/删/建目录，且 fs.File 是一次性对象，Close() 后再 Read() 必 panic。你需要的是读写分离、带 context、错误归一的自定义接口。
为什么不能把 io/fs.FS 当主存储接口用
io/fs.FS 的设计目标明确：静态资源加载（如 embed.FS、模板文件）。它不提供 WriteFile、Delete、MkdirAll 等能力，连 fs.File 都要求“用完即弃”。常见踩坑点包括：
- 把
embed.FS传给需要保存上传文件的函数，运行时静默失败或 panic - 用
os.DirFS("/data")却漏掉os.MkdirAll，调用Save("logs/2026/06/app.log")直接报no such file or directory - 误以为
fs.ReadFile能覆盖写入场景，但业务需要的是原子覆盖、权限控制、超时取消——这些io/fs.FS都不关心
该定义哪五个核心方法的接口
真正要抽象的，是「存 / 取 / 删 / 查是否存在 / 获取元信息」这五类动作，且必须读写分离。最小可行接口示例如下：
type FileStore interface {
ReadFile(ctx context.Context, path string) ([]byte, error)
Stat(ctx context.Context, path string) (FileStat, error)
WriteFile(ctx context.Context, path string, data []byte, perm fs.FileMode) error
Delete(ctx context.Context, path string) error
Exists(ctx context.Context, path string) (bool, error)
}
-
FileStat必须是自定义结构体（含Name()、Size()、IsDir()、ModTime()），不能直接返回fs.FileInfo；否则 S3 实现得伪造os.FileInfo，语义错位 - 所有方法必须带
ctx context.Context，由调用方控制超时与取消，禁止内部硬编码context.WithTimeout - 错误必须归一：统一返回
ErrNotFound、ErrPermissionDenied等领域错误，而非暴露os.PathError或云 SDK 错误
如何让内存实现和磁盘实现行为一致
关键不是“都实现同一个 interface”，而是路径处理、并发安全、错误映射三者一致。最容易被忽略的是路径标准化逻辑：
Golang Samber Hot
下载
在 Golang 中使用 samber/hot 进行内存缓存，支持 LRU、LFU、TinyLFU、W‑TinyLFU、S3FIFO、ARC、TwoQueue、SIEVE、FIFO 等淘汰算法，提供 TTL、缓存加载器及分片功能。
立即学习“go语言免费学习笔记（深入）”；
- 测试用
memFS时，"./a/../b"被自动清理为"b"；生产用os.DirFS也必须走filepath.Clean，否则测试通过、线上因路径不一致失败 - 对非本地后端（如 S3、memFS），应跳过
filepath.Join和filepath.FromSlash，直接拼接或使用url.PathEscape；否则 Windows 下filepath.Join("s3://bucket", "path/to/file")会把/转成\，导致远程路径失效 - 所有实现必须统一处理
../：内存实现里若不做清理，Exists("../etc/passwd")可能意外返回 true；磁盘实现若没校验，可能越权访问父目录
扩展新能力时别改接口，用组合嵌入
一旦 FileStore 被多个实现（LocalStorage、MemStorage、S3Storage）依赖，添加方法就是破坏性变更。正确做法是组合增强：
type LoggingStore struct {
store FileStore // 嵌入原始接口
}
func (l *LoggingStore) WriteFile(ctx context.Context, path string, data []byte, perm fs.FileMode) error {
log.Printf("Writing %s (%d bytes)", path, len(data))
return l.store.WriteFile(ctx, path, data, perm)
}
- 嵌入后自动获得所有方法，只重写需增强的，其余自动委托
- 调用方仍可把
*LoggingStore当作FileStore使用，零侵入 - 想加重试逻辑？写个
RetryStore；想加限速？写个RateLimitedStore；都不需要动原接口
真正的难点不在定义接口，而在让不同实现对路径边界、错误分类、并发模型保持严格一致——接口只是契约，落地靠的是每一处 filepath.Clean 的位置、每一个 errors.Is(err, ErrNotFound) 的判断、每一次 ctx.Done() 的响应。
