CloudFS 中文文档

CloudFS 是一个 Go 文件系统抽象库，用统一的 cloudfs.FS 接口封装本地磁盘和多种云存储/远程存储。调用方可以用一致的方式完成目录浏览、文件读取、文件写入、移动、复制、重命名和删除。

文档导航

• 中间件文档
• 驱动文档

功能概览

• 统一的 cloudfs.FS 接口
• 支持直接创建驱动，也支持按名称动态创建驱动
• 支持通过中间件包装已有驱动
• 支持按路径前缀挂载、缓存、限速、压缩、加密、自定义路径与文件映射

安装

1go get github.com/honmaple/cloudfs

按需引入驱动：

1import "github.com/honmaple/cloudfs/driver/webdav"

如果你希望通过 driver.New() 动态按名字创建驱动，需要额外引入聚合注册包：

1import _ "github.com/honmaple/cloudfs/driver/all"

快速开始

 1package main
 2
 3import (
 4	"context"
 5	"io"
 6	"strings"
 7
 8	"github.com/honmaple/cloudfs/driver/local"
 9)
10
11func main() {
12	fs, err := local.New(&local.Option{
13		Path: "/tmp/cloudfs",
14	})
15	if err != nil {
16		panic(err)
17	}
18	defer fs.Close()
19
20	ctx := context.Background()
21
22	if err := fs.MakeDir(ctx, "/docs"); err != nil {
23		panic(err)
24	}
25
26	w, err := fs.Create(ctx, "/docs/hello.txt")
27	if err != nil {
28		panic(err)
29	}
30	if _, err := io.Copy(w, strings.NewReader("hello cloudfs")); err != nil {
31		_ = w.Close()
32		panic(err)
33	}
34	if err := w.Close(); err != nil {
35		panic(err)
36	}
37
38	files, err := fs.List(ctx, "/docs")
39	if err != nil {
40		panic(err)
41	}
42	for _, file := range files {
43		println(file.Path(), file.Name(), file.Size())
44	}
45}

核心接口

CloudFS 的核心接口如下：

 1type FS interface {
 2	List(context.Context, string, ...ListOption) ([]FileInfo, error)
 3	Move(context.Context, string, string) error
 4	Copy(context.Context, string, string) error
 5	Rename(context.Context, string, string) error
 6	Remove(context.Context, string) error
 7	MakeDir(context.Context, string) error
 8	Stat(context.Context, string) (FileInfo, error)
 9	Open(context.Context, string) (File, error)
10	Create(context.Context, string) (FileWriter, error)
11	Close() error
12}

说明：

• 所有路径都使用以 / 开头的类 Unix 风格路径
• Open() 返回可读、可 Seek() 的文件对象
• Create() 返回 io.WriteCloser，必须显式 Close() 才能完成上传/落盘
• FileInfo 在标准 io/fs.FileInfo 基础上增加了 Path()、Type() 和 ExtraInfo()

创建驱动

方式一：直接创建

1fs, err := webdav.New(&webdav.Option{
2	Endpoint: "https://example.com/dav",
3	Username: "user",
4	Password: "pass",
5})

方式二：动态创建

 1import (
 2	"github.com/honmaple/cloudfs/driver"
 3	_ "github.com/honmaple/cloudfs/driver/all"
 4)
 5
 6fs, err := driver.New("webdav", map[string]any{
 7	"endpoint": "https://example.com/dav",
 8	"username": "user",
 9	"password": "pass",
10})

方式三：从 JSON 字符串创建

1fs, err := driver.NewFromString("local", `{"path":"/tmp/cloudfs"}`)

配置校验

1ok := driver.Exists("s3")
2err := driver.VerifyOption("s3", `{"endpoint":"https://s3.example.com","bucket":"files"}`)

注意：

• driver.New() 和 driver.NewFromString() 依赖每个驱动在 init() 中完成注册
• 校验错误消息目前使用中文返回

中间件包装

你可以通过 cloudfs.New() 或 middleware.NewFS() 叠加多个中间件：

 1import (
 2	"github.com/honmaple/cloudfs"
 3	"github.com/honmaple/cloudfs/driver/local"
 4	"github.com/honmaple/cloudfs/middleware"
 5)
 6
 7base, _ := local.New(&local.Option{Path: "/data"})
 8
 9fs, err := cloudfs.New(
10	base,
11	middleware.PrefixFS("/project-a"),
12	middleware.CacheFS(&middleware.CacheOption{ExpireTime: 120}),
13	middleware.RateLimitFS(&middleware.RateLimitOption{
14		Wait:  true,
15		Burst: 20,
16		Limit: 1,
17	}),
18)

更完整的中间件说明见 middleware.md。

常用操作

1ctx := context.Background()
2
3files, err := fs.List(ctx, "/")
4info, err := fs.Stat(ctx, "/file.txt")
5err = fs.MakeDir(ctx, "/new-dir")
6err = fs.Rename(ctx, "/file.txt", "new-name.txt")
7err = fs.Move(ctx, "/new-name.txt", "/new-dir")
8err = fs.Copy(ctx, "/new-dir/new-name.txt", "/")
9err = fs.Remove(ctx, "/new-dir/new-name.txt")

驱动能力矩阵

完整参数说明和驱动注意事项见 drivers.md。