更新注释

pkg/s3/s3.go

@@ -16,26 +16,32 @@ import (
 	"github.com/minio/minio-go/v7/pkg/credentials"
 )
 
+// ctx 全局上下文，用于在整个包中传递请求范围的数据
 var (
 	//client *minio.Client
 	ctx = gctx.New()
 )
 
+// DataType 定义了 S3 配置的数据结构，用于存储访问 S3 所需的各种信息
 type DataType struct {
-	AccessKey     string `json:"access_key"`
-	SecretKey     string `json:"secret_key"`
-	Address       string `json:"address"`
-	Ssl           bool   `json:"ssl"`
-	Url           string `json:"url"`
-	BucketName    string `json:"bucket_name"`
-	BucketNameCdn string `json:"bucket_name_cdn"`
+	AccessKey     string `json:"access_key"` // 访问 S3 的密钥 ID
+	SecretKey     string `json:"secret_key"` // 访问 S3 的密钥
+	Address       string `json:"address"`    // S3 服务的地址
+	Ssl           bool   `json:"ssl"`        // 是否使用 SSL 加密连接
+	Url           string `json:"url"`        // S3 服务的访问 URL
+	BucketName    string `json:"bucket_name"` // 默认存储桶名称
+	BucketNameCdn string `json:"bucket_name_cdn"` // CDN 存储桶名称
 }
 
+// Mod 定义了 S3 模块的结构体，包含一个 S3 客户端实例和配置信息
 type Mod struct {
-	client *minio.Client
-	cfg    DataType
+	client *minio.Client // Minio S3 客户端实例
+	cfg    DataType      // S3 配置信息
 }
 
+// New 根据配置创建一个新的 S3 模块实例
+// 如果未提供名称，则从配置中获取默认的 S3 类型
+// 配置错误时会触发 panic
 func New(_name ...string) *Mod {
 	var name string
 	if len(_name) > 0 {
@@ -52,7 +58,7 @@ func New(_name ...string) *Mod {
 	var cfg DataType
 	get.Scan(&cfg)
 
-	// 使用minio-go创建S3客户端
+	// 使用 minio-go 创建 S3 客户端
 	obj, err := minio.New(
 		cfg.Address,
 		&minio.Options{
@@ -72,183 +78,111 @@ func New(_name ...string) *Mod {
 	return mod
 }
 
-//func (s *Mod) Load() {
-//	//导入配置
-//	get, err := g.Cfg().Get(ctx, "s3.type")
-//	cfgType := get.String()
-//	if cfgType == "" {
-//		cfgType = "default"
-//	}
-//
-//	cfgData, err := g.Cfg().Get(ctx, "s3."+cfgType)
-//	if cfgData.IsEmpty() {
-//		panic("当前配置中未配置s3：" + cfgType)
-//	}
-//
-//	get, err = g.Cfg().Get(ctx, "s3."+cfgType)
-//	err = get.Scan(&Cfg)
-//
-//	// 使用minio-go创建S3客户端
-//	obj, err := minio.New(
-//		Cfg.Address,
-//		&minio.Options{
-//			Creds:  credentials.NewStaticV4(Cfg.AccessKey, Cfg.SecretKey, ""),
-//			Secure: Cfg.Ssl,
-//		},
-//	)
-//	if err != nil {
-//		log.Fatalln(err)
-//	}
-//
-//	client = obj
-//}
-//
-//func (s *Mod) S3(name string) {
-//	get, err := g.Cfg().Get(ctx, "s3."+name)
-//	if err != nil {
-//		panic(err)
-//	}
-//	get.Scan(&Cfg)
-//
-//	// 使用minio-go创建S3客户端
-//	obj, err := minio.New(
-//		Cfg.Address,
-//		&minio.Options{
-//			Creds:  credentials.NewStaticV4(Cfg.AccessKey, Cfg.SecretKey, ""),
-//			Secure: Cfg.Ssl,
-//		},
-//	)
-//	if err != nil {
-//		log.Fatalln(err)
-//	}
-//
-//	client = obj
-//
-//}
-
-// GetCfg 获取配置
+// GetCfg 获取当前 S3 模块的配置信息
 func (s *Mod) GetCfg() *DataType {
 	return &s.cfg
 }
 
-// GetFileUrl 生成指向S3存储桶中指定文件的预签名URL
-//
-// @Description: 生成一个具有有限有效期的预签名URL，可用于访问S3存储桶中的文件。
-// @receiver s: S3的实例，用于执行S3操作。
-// @param name: 要获取预签名URL的文件名。
-// @param bucketName: 文件所在的存储桶名称。
-// @return presignedURL: 生成的预签名URL，可用于访问文件。
-// @return err: 在获取预签名URL过程中遇到的任何错误。
+// GetFileUrl 生成指向 S3 存储桶中指定文件的预签名 URL
+// 预签名 URL 可用于在有限时间内访问 S3 存储桶中的文件
+// 支持从缓存中获取预签名 URL，以减少重复请求
 func (s *Mod) GetFileUrl(name string, bucketName string, _expires ...time.Duration) (presignedURL *url.URL, err error) {
-	// 设置预签名URL的有效期为1小时
+	// 设置预签名 URL 的有效期为 1 小时，可通过参数覆盖
 	expires := time.Hour * 1
 	if len(_expires) > 0 {
 		expires = _expires[0]
 	}
+	// 生成缓存键
 	cacheKey := fmt.Sprintf("s3:%v:%v", name, bucketName)
+	// 尝试从缓存中获取预签名 URL
 	get, _ := gcache.Get(ctx, cacheKey)
-	//g.Dump(get.Vars())
 	if !get.IsEmpty() {
+		// 将缓存中的值转换为 *url.URL 类型
 		err = gconv.Struct(get.Val(), &presignedURL)
-		//presignedURL =
 		return
 	}
-	//expires := time.Duration(604800)
-	// 调用s3().PresignedGetObject方法生成预签名URL
+	// 调用 S3 客户端生成预签名 URL
 	presignedURL, err = s.client.PresignedGetObject(ctx, bucketName, name, expires, nil)
+	// 将生成的预签名 URL 存入缓存
 	err = gcache.Set(ctx, cacheKey, presignedURL, expires)
 	return
 }
 
-// PutFileUrl 生成一个用于上传文件到指定bucket的预签名URL
-//
-//	@Description:
-//	@receiver s
-//	@param name 文件名
-//	@param bucketName 存储桶名称
-//	@return presignedURL 预签名的URL，用于上传文件
-//	@return err 错误信息，如果在生成预签名URL时发生错误
+// PutFileUrl 生成一个用于上传文件到指定存储桶的预签名 URL
+// 预签名 URL 的有效期默认为 10 分钟
 func (s *Mod) PutFileUrl(name string, bucketName string) (presignedURL *url.URL, err error) {
-	// 设置预签名URL的有效期
-	//expires := time.Now().Add(time.Minute * 30).Unix() // 例如：有效期30分钟
-	//expires2 := time.Duration(expires)
+	// 设置预签名 URL 的有效期为 10 分钟
 	expires := time.Minute * 10
-	// 生成预签名URL
+	// 调用 S3 客户端生成预签名 URL
 	presignedURL, err = s.client.PresignedPutObject(ctx, bucketName, name, expires)
-
 	return
 }
 
-// 获取储存桶列表
+// ListBuckets 获取当前 S3 客户端可访问的所有存储桶列表
+// 出错时返回 nil
 func (s *Mod) ListBuckets() []minio.BucketInfo {
 	buckets, err := s.client.ListBuckets(ctx)
-	//g.Dump(buckets)
 	if err != nil {
-		//fmt.Println(err)
 		return nil
 	}
 	return buckets
 }
 
-// PutObject 上传文件到指定的存储桶中。
-//
-// @Description: 上传一个文件到指定的存储桶。
-// @receiver s *Mod: 表示调用此方法的Mod实例。
-// @param f io.Reader: 文件的读取器，用于读取待上传的文件内容。
-// @param name string: 待上传文件的名称。
-// @param bucketName string: 存储桶的名称。
-// @param _size ...int64: 可选参数，指定上传文件的大小。如果未提供，则默认为-1，表示读取文件直到EOF。
-// @return res minio.UploadInfo: 上传成功后返回的上传信息。
-// @return err error: 如果上传过程中出现错误，则返回错误信息。
+// PutObject 上传文件到指定的存储桶中
+// 支持指定文件大小，未指定时将读取文件直到结束
 func (s *Mod) PutObject(f io.Reader, name string, bucketName string, _size ...int64) (res minio.UploadInfo, err error) {
-	// 初始化文件大小为-1，表示将读取文件至结束。
+	// 初始化文件大小为 -1，表示将读取文件至结束
 	var size = int64(-1)
-	// 如果提供了文件大小，则使用提供的大小值。
 	if len(_size) > 0 {
 		size = _size[0]
 	}
-
-	// 调用client的PutObject方法上传文件，并设置内容类型为"application/octet-stream"。
+	// 调用 S3 客户端上传文件，设置内容类型为 "application/octet-stream"
 	res, err = s.client.PutObject(ctx, bucketName, name, f, size, minio.PutObjectOptions{ContentType: "application/octet-stream"})
 	if err != nil {
+		// 记录上传错误日志
 		g.Log().Error(ctx, err)
 	}
 	return
 }
 
-// RemoveObject 删除文件
+// RemoveObject 从指定存储桶中删除指定名称的文件
 func (s *Mod) RemoveObject(name string, bucketName string) (err error) {
 	opts := minio.RemoveObjectOptions{
 		//GovernanceBypass: true,
 		//VersionID:        "myversionid",
 	}
+	// 调用 S3 客户端删除文件
 	err = s.client.RemoveObject(ctx, bucketName, name, opts)
 	return
 }
 
-// ListObjects 文件列表
+// ListObjects 获取指定存储桶中指定前缀的文件列表
+// 返回一个包含文件信息的通道
 func (s *Mod) ListObjects(bucketName string, prefix string) (res <-chan minio.ObjectInfo, err error) {
+	// 调用 S3 客户端获取文件列表
 	res = s.client.ListObjects(ctx, bucketName, minio.ListObjectsOptions{
 		Prefix: prefix,
 	})
 	return
 }
 
-// SetBucketPolicy 设置bucket或对象前缀的访问权限
+// SetBucketPolicy 设置指定存储桶或对象前缀的访问策略
+// 目前使用固定的策略，可根据需求修改
 func (s *Mod) SetBucketPolicy(bucketName string, prefix string) (err error) {
-
+	// 定义访问策略
 	policy := `{"Version": "2012-10-17","Statement": [{"Action": ["s3:GetObject"],"Effect": "Allow","Principal": {"AWS": ["*"]},"Resource": ["arn:aws:s3:::my-bucketname/*"],"Sid": ""}]}`
-
+	// 调用 S3 客户端设置存储桶策略
 	err = s.client.SetBucketPolicy(ctx, bucketName, policy)
 	return
 }
 
-// GetUrl 获取文件访问地址
+// GetUrl 获取文件的访问地址
+// 支持返回默认文件地址，根据 SSL 配置生成不同格式的 URL
 func (s *Mod) GetUrl(filePath string, defaultFile ...string) (url string) {
 	bucketName := s.cfg.BucketNameCdn
 	get := s.cfg.Url
 
-	//如果没有图片，返回默认的图片地址
+	// 如果没有指定文件路径，且提供了默认文件路径，则使用默认路径
 	if filePath == "" && len(defaultFile) > 0 {
 		filePath = defaultFile[0]
 	}
@@ -262,6 +196,7 @@ func (s *Mod) GetUrl(filePath string, defaultFile ...string) (url string) {
 	return
 }
 
+// GetPath 从文件访问 URL 中提取文件路径
 func (s *Mod) GetPath(url string) (filePath string) {
 	bucketName := s.cfg.BucketNameCdn
 	get := s.cfg.Url
@@ -269,21 +204,22 @@ func (s *Mod) GetPath(url string) (filePath string) {
 	return url[len(get+bucketName)+1:]
 }
 
-// 复制文件
+// CopyObject 在指定存储桶内复制文件
+// 支持指定源文件和目标文件路径
 func (s *Mod) CopyObject(bucketName string, dstStr string, srcStr string) (err error) {
-
-	// 原始文件
+	// 定义目标文件选项
 	var dst = minio.CopyDestOptions{
 		Bucket: bucketName,
 		Object: dstStr,
 	}
 
-	// 新文件
+	// 定义源文件选项
 	var src = minio.CopySrcOptions{
 		Bucket: bucketName,
 		Object: srcStr,
 	}
 
+	// 调用 S3 客户端复制文件
 	_, err = s.client.CopyObject(ctx, dst, src)
 	return
 }