不能直接用os.File抽象多存储驱动，因其绑定操作系统文件描述符，无法适配S3、内存缓存等后端；需自定义FileSystem接口统一路径语义、错误类型与基础操作，通过依赖注入切换驱动。
为什么不能直接用 os.File 抽象多存储驱动
因为 os.File 是对本地文件描述符的封装，它绑定在操作系统层，无法透明代理到对象存储（如 S3）、内存缓存或 HTTP 后端。一旦你写死 os.Open 或 os.Create，就锁死了本地磁盘路径语义——比如 /tmp/data.txt 在 S3 里根本不存在对应概念。
真正可行的路径是定义自己的接口，让具体驱动实现它。Go 标准库没提供“通用文件系统抽象”，所以得自己划边界：
-
ReadFile、WriteFile这类便捷函数不能直接复用，它们底层仍走os - 必须区分“路径”语义：S3 的
bucket/key不等于本地/a/b/c，但可以统一建模为string类型的path - 错误处理要收敛：S3 的
NoSuchKey、本地的os.ErrNotExist应映射为同一错误类型（如自定义fs.ErrNotExist）
定义最小可行接口：FileSystem 和 File
不要一上来就模仿 io/fs.FS（它不支持写），也不要塞太多方法。从最常操作的四个动作切入：
type FileSystem interface {
Open(path string) (File, error)
Stat(path string) (FileInfo, error)
WriteFile(path string, data []byte, perm fs.FileMode) error
Remove(path string) error
}
注意三点：
-
File接口只需嵌入io.ReadCloser，写操作由FileSystem.WriteFile承担，避免流式写入的生命周期管理混乱 -
FileInfo必须自定义，不能直接返回os.FileInfo，否则 S3 驱动无法填满Mode()、Sys()等字段；可只保留Name()、Size()、ModTime()、IsDir() - 所有方法参数中的
path统一不校验前导/，交由各驱动解释：本地驱动可自动补./，S3 驱动忽略开头斜杠
本地驱动和 S3 驱动的关键差异点
本地驱动看似简单，但容易漏掉权限和符号链接处理：
- 用
os.OpenFile(path, os.O_RDONLY, 0)而非os.Open，后者固定为0666，无法控制打开模式 -
Stat必须用os.Lstat，否则会跟随符号链接，导致路径解析错乱 -
WriteFile要先写临时文件再os.Rename，保证原子性；别用ioutil.WriteFile（已弃用）或os.WriteFile（Go 1.16+），后者在某些文件系统上不原子
S3 驱动则要注意：
- 路径分隔符统一转为
/，AWS SDK 不接受\ -
Stat实际发HeadObject请求，404 要转成fs.ErrNotExist，不能裸抛 AWS 错误 -
Remove对应DeleteObject，但批量删除要用DeleteObjects，单文件别滥用 - 所有
*Request调用后记得调.Send()，SDK v2 用context控制超时，别漏传
如何安全切换驱动而不改业务代码
靠依赖注入，而不是全局变量或单例。启动时根据配置创建对应驱动：
func NewFileSystem(cfg Config) (FileSystem, error) {
switch cfg.Type {
case "local":
return &LocalFS{Root: cfg.Root}, nil
case "s3":
return &S3FS{
Client: s3.New(s3.Options{Region: cfg.Region}),
Bucket: cfg.Bucket,
}, nil
default:
return nil, fmt.Errorf("unsupported fs type: %s", cfg.Type)
}
}
关键约束：
- 所有驱动构造函数不执行初始化 IO（如检查 bucket 是否存在），延迟到首次
Stat或Open时做，避免启动失败 - 业务层永远只持有
FileSystem接口，绝不断言为具体类型（如if local, ok := fs.(*LocalFS)） - 测试时用
memfs（如github.com/spf13/afero的Afero包装）替代真实驱动，但注意它不模拟网络分区或限速，压测需另配
路径拼接这种事，别信 path.Join —— 它在 Windows 下会产出 \，而 S3 只认 /。一律用 strings.Join([]string{a,b,c}, "/") 或 filepath.ToSlash 清洗。
