s3

package
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bucket

type Bucket struct {
	// contains filtered or unexported fields
}

Bucket 代表一个 S3 桶的客户端,提供上传/下载/删除/列举/预签名/分片上传等操作。

func (*Bucket) Check

func (b *Bucket) Check(ctx context.Context) error

Check 探活

func (*Bucket) Delete

func (b *Bucket) Delete(ctx context.Context, key string) error

Delete 删除指定 key,不存在不报错。

func (*Bucket) Download

func (b *Bucket) Download(ctx context.Context, key string, w io.WriterAt) error

Download 将指定 key 的内容写入 w(io.Writer),大文件自动分片下载。

func (*Bucket) DownloadBytes

func (b *Bucket) DownloadBytes(ctx context.Context, key string) ([]byte, error)

DownloadBytes 下载指定 key 的完整内容并返回字节切片。

func (*Bucket) Exists

func (b *Bucket) Exists(ctx context.Context, key string) (bool, error)

Exists 判断 key 是否存在

func (*Bucket) List

func (b *Bucket) List(ctx context.Context, prefix string, max int32) ([]ObjectInfo, error)

List 列举桶内对象,prefix 为前缀过滤,max 为最大返回数量(<=0 取 1000)。 返回的 ObjectInfo 含 Key/Size/LastModified/ETag/ContentType。

func (*Bucket) Name

func (b *Bucket) Name() string

Name 返回桶名

func (*Bucket) Presign

func (b *Bucket) Presign(ctx context.Context, key string) (string, error)

Presign 生成下载预签名 URL,有效期使用配置的 presignExpiry。

func (*Bucket) PresignUpload

func (b *Bucket) PresignUpload(ctx context.Context, key string) (string, error)

PresignUpload 生成上传预签名 URL(客户端直传)。

func (*Bucket) Put

func (b *Bucket) Put(ctx context.Context, key string, data []byte, contentType string) error

PutObject / Put 别名:上传字节

func (*Bucket) Upload

func (b *Bucket) Upload(ctx context.Context, key string, body io.Reader, contentType string) error

Upload 上传一个 Reader 内容到指定 key。 contentType 为空时使用桶的默认类型,再为空时按扩展名推断,仍为空则 application/octet-stream。 对于 *bytes.Reader 会自动判断是否超过单片大小从而选用分片上传;其他 Reader 走 PutObject。

func (*Bucket) UploadBytes

func (b *Bucket) UploadBytes(ctx context.Context, key string, data []byte, contentType string) error

UploadBytes 便捷方法:直接上传字节切片

func (*Bucket) UploadMultipart

func (b *Bucket) UploadMultipart(ctx context.Context, key, contentType string, body io.Reader, partSize int64) (string, error)

UploadMultipart 分片上传(适合超大文件)。 返回最终 ETag。body 可分多次写入通过 partSize 控制单片大小。

type BucketConfig

type BucketConfig struct {
	// Name 桶名(必填)
	Name string `yaml:"name"`
	// Public 是否为公有桶(用于预签名默认行为提示,不影响实际 ACL)
	Public bool `yaml:"public"`
	// DefaultContentType 该桶上传时未指定 ContentType 时的默认值
	DefaultContentType string `yaml:"defaultContentType"`
}

BucketConfig 单个桶的配置

type Config

type Config struct {
	// Enabled 是否启用(go.config.used 已包含 s3 时仍可用此开关二次控制)
	Enabled bool `yaml:"enabled"`
	// Endpoint S3 兼容服务地址,如 https://s3.amazonaws.comhttp://localhost:9000(MinIO)
	Endpoint string `yaml:"endpoint"`
	// Region 区域,如 cn-north-1 / us-east-1,兼容服务可填 auto
	Region string `yaml:"region"`
	// AccessKey 访问密钥 ID
	AccessKey string `yaml:"accessKey"`
	// SecretKey 访问密钥
	SecretKey string `yaml:"secretKey"`
	// SessionToken 可选,临时凭证的会话令牌
	SessionToken string `yaml:"sessionToken"`
	// PathStyle 是否使用路径风格寻址(MinIO 等自建服务必须为 true)
	PathStyle bool `yaml:"pathStyle"`
	// ForcePathStyle 的别名,等效于 PathStyle
	ForcePathStyle bool `yaml:"forcePathStyle"`
	// UsePathStyle 的别名,等效于 PathStyle
	UsePathStyle bool `yaml:"usePathStyle"`
	// SSL 是否启用 HTTPS,默认 true
	SSL bool `yaml:"ssl"`
	// MaxRetries 请求失败重试次数,默认 3
	MaxRetries int `yaml:"maxRetries"`
	// UploadPartSize 分片上传的单片大小(字节),默认 16MB
	UploadPartSize int64 `yaml:"uploadPartSize"`
	// DownloadPartSize 分片下载的单片大小(字节),默认 16MB
	DownloadPartSize int64 `yaml:"downloadPartSize"`
	// MaxUploadParts 分片上传最大并发数,默认 10
	MaxUploadParts int `yaml:"maxUploadParts"`
	// MaxDownloadParts 分片下载最大并发数,默认 10
	MaxDownloadParts int `yaml:"maxDownloadParts"`
	// PresignExpiry 预签名 URL 默认有效期(秒),默认 3600
	PresignExpiry int `yaml:"presignExpiry"`
	// SingleBucket 未配置 buckets 时使用的默认桶名
	SingleBucket string `yaml:"singleBucket"`
	// Buckets 多桶配置
	Buckets []BucketConfig `yaml:"buckets"`
}

Config 是 S3 存储插件的完整配置,对应 application.yml 中 go.s3 节点。

多 bucket:buckets 为空时自动以 endpoint 对应的默认桶(singleBucket)工作; buckets 非空时通过 Get(name) 区分不同用途的桶(如公有资源桶 / 私有文件桶)。

type ObjectInfo

type ObjectInfo struct {
	Key          string
	Size         int64
	LastModified time.Time
	ETag         string
	ContentType  string
}

ObjectInfo 列举返回的对象摘要

type S3

type S3 struct {
	// contains filtered or unexported fields
}

S3 是 S3 存储插件,实现 mgin.MginPlugin 接口。

用法:

mgin.UsePlugin("s3", storage.NewS3())
// 或手动初始化:
s := storage.NewS3()
s.Init(configBytes) // configBytes 为 go.s3 节点的 yaml 字节

业务侧取桶:

b := storage.GetS3().Default()       // 默认桶
b := storage.GetS3().Get("avatar")   // 指定桶
b.Upload(ctx, "users/1.png", data, "image/png")

func GetS3

func GetS3() *S3

GetS3 返回全局 S3 插件单例

func NewS3

func NewS3() *S3

NewS3 创建(或返回单例)S3 存储插件

func (*S3) Check

func (s *S3) Check() error

Check 实现 mgin.MginPlugin 接口,对默认桶做一次 HeadBucket 探活。

func (*S3) Close

func (s *S3) Close()

Close 实现 mgin.MginPlugin 接口。S3 客户端无持久连接,此处仅做清理。

func (*S3) Default

func (s *S3) Default() *Bucket

Default 返回默认桶(buckets 第一个,或 singleBucket)

func (*S3) Get

func (s *S3) Get(name string) *Bucket

Get 按桶名返回桶客户端,不存在返回 nil

func (*S3) Init

func (s *S3) Init(configData []byte)

Init 实现 mgin.MginPlugin 接口,解析配置并建立客户端。 configData 为 go.s3 节点对应的 yaml 字节。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL