goss

README

goss

✨ goss 是一个简洁的云存储 golang 库，兼容 amazon s3 协议，支持但不限于阿里云、腾讯云、七牛云、华为云、aws s3、minio。

🚀 安装

go get -u github.com/eleven26/goss/v4

⚙️ 配置

所有支持的配置项：

type Config struct {
    Endpoint          string `yaml:"endpoint"`
    AccessKey         string `yaml:"access_key"`
    SecretKey         string `yaml:"secret_key"`
    Region            string `yaml:"region"`
    Bucket            string `yaml:"bucket"`

    // 如果是使用 minio，并且没有使用 https，需要设置为 true
    UseSsl            *bool  `yaml:"use_ssl"`
    // 如果是使用 minio，需要设置为 true
    HostnameImmutable *bool  `yaml:"hostname_immutable"`
}

配置的方式，在创建实例的时候通过 WithConfig 来传递：

goss, err := goss.New(goss.WithConfig(&Config{
    Endpoint: "",
    AccessKey: "",
    SecretKey: "",
    Region: "",
    Bucket: "",
}))

💡 基本用法

1. 你可以通过下面的代码来导入 goss:

import "github.com/eleven26/goss/v4"

1. 使用之前需要创建实例：

goss, err := goss.New(goss.WithConfig(&Config{
    Endpoint: "",
    AccessKey: "",
    SecretKey: "",
    Region: "",
    Bucket: "",
}))

1. 使用

// goss.GetString 会获取路径指定的文件，返回字符串
fmt.Println(goss.GetString(context.TODO(), "test/foo.txt"))

📚 接口

goss 支持以下操作：

• Put
• PutFromFile
• Get
• GetString
• GetBytes
• GetToFile
• Delete
• Exists
• Files
• Size

Put

上传文件到云存储。第一个参数是 key，第二个参数是 io.Reader。

data := []byte("this is some data stored as a byte slice in Go Lang!")
r := bytes.NewReader(data)
err := goss.Put(context.TODO(), "test/test.txt", r)

PutFromFile

上传文件到云存储。第一个参数是 key，第二个参数是本地文件路径。

err := goss.PutFromFile(context.TODO(), "test/test.txt", "/path/to/test.txt")

Get

从云存储获取文件。参数是 key。返回值是 io.ReadCloser 和 error。

// rc 是 `io.ReadCloser`
rc, err := goss.Get(context.TODO(), "test/test.txt")
defer rc.Close()

bs, err := io.ReadAll(rc)
fmt.Println(string(bs))

GetString

从云存储获取文件。参数是 key。返回值是 string 和 error

content, err := goss.GetString(context.TODO(), "test/test.txt")
fmt.Println(content)

GetBytes

从云存储获取文件。参数是 key。返回值是 []byte 和 error

bs, err := goss.GetBytes(context.TODO(), "test/test.txt")
fmt.Println(string(bs))

GetToFile

下载云存储文件到本地。第一个参数是 key，第二个参数是本地路径。

// 第一个参数是云端路径，第二个参数是本地路径
err := goss.GetToFile(context.TODO(), "test/test.txt", "/path/to/local")

Delete

删除云存储文件。

err := goss.Delete(context.TODO(), "test/test.txt")

Exists

判断云存储文件是否存在。

exists, err := goss.Exists(context.TODO(), "test/test.txt")

Files

根据前缀获取文件列表。

exists, err := goss.Files(context.TODO(), "test/")

Size

获取云存储文件大小。

size, err := goss.Size(context.TODO(), "test/test.txt")

参考文档

1. 阿里云对象存储
2. 腾讯云对象存储
3. 七牛云对象存储
4. 华为云对象存储
5. aws s3
6. minio

各云厂商对 s3 的支持

1. 阿里云: OSS与Amazon S3的兼容性
2. 腾讯云: 使用 AWS S3 SDK 访问 COS
3. 七牛云: AWS S3 兼容
4. 华为云：支持 s3，但是官网文档找不到相关关于 s3 兼容的相关描述
5. minio: AWS S3 Compatibility

注意事项

1. 七牛云的 endpoint 和 region 配置请参考这个文档：AWS S3 兼容 - 服务域名

Changelog

[4.0.0] - 2023-09-28

Changed

• 所有方法添加 context.Context 作为第一个参数。

Documentation

Index

• type Config
• type File
• type Goss
  • func New(opts ...Option) (*Goss, error)
• type Option
  • func WithConfig(config *Config) Option
• type Store

Types

type Config

type Config struct {
	Endpoint          string `yaml:"endpoint"`
	AccessKey         string `yaml:"access_key"`
	SecretKey         string `yaml:"secret_key"`
	Region            string `yaml:"region"`
	Bucket            string `yaml:"bucket"`
	UseSsl            *bool  `yaml:"use_ssl"`
	HostnameImmutable *bool  `yaml:"hostname_immutable"`
}

type File

type File interface {
	// Key is the object key.
	Key() string

	// Type is the object type.
	Type() string

	// Size is the size of current file.
	Size() int64

	// ETag is etag return by cloud storage providers.
	ETag() string

	// LastModified is the time when the object was last updated.
	LastModified() time.Time
}

File A slice of File is returned when all files are fetched through Store.Files. File hides differences in object returns from different cloud storage providers, but at the same time, it can only return less information.

type Goss

type Goss struct {
	Store
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) (*Goss, error)

type Option

type Option func(goss *Goss)

func WithConfig

func WithConfig(config *Config) Option

type Store

type Store interface {
	// Put saves the content read from r to the key of oss.
	Put(ctx context.Context, key string, r io.Reader) error

	// PutFromFile saves the file pointed to by the `localPath` to the oss key.
	PutFromFile(ctx context.Context, key string, localPath string) error

	// Get gets the file pointed to by key.
	Get(ctx context.Context, key string) (io.ReadCloser, error)

	// GetString gets the file pointed to by key and returns a string.
	GetString(ctx context.Context, key string) (string, error)

	// GetBytes gets the file pointed to by key and returns a byte array.
	GetBytes(ctx context.Context, key string) ([]byte, error)

	// GetToFile saves the file pointed to by key to the localPath.
	GetToFile(ctx context.Context, key string, localPath string) error

	// Delete the file pointed to by key.
	Delete(ctx context.Context, key string) error

	// Exists determines whether the file exists.
	Exists(ctx context.Context, key string) (bool, error)

	// Files list all files in the specified directory.
	Files(ctx context.Context, dir string) ([]File, error)

	// Size fet the file size.
	Size(ctx context.Context, key string) (int64, error)
}

Store defines interface for cloud storage.