attachment

package
v0.18.3 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 26 Imported by: 0

README

Attachment 组件

附件管理组件提供统一的文件上传、存储和管理功能,支持本地存储和多种云存储服务。

概述

Attachment 组件是一个功能强大的文件附件管理工具,支持多种文件类型(图片、音频、视频、办公文件、压缩文件等)的上传、存储和访问。组件提供统一的 API 接口,支持本地存储、腾讯云 COS、阿里云 OSS、FTP 和 SFTP 等多种存储方式。

功能特性

  • 多存储支持:支持本地存储、腾讯云 COS、阿里云 OSS、FTP、SFTP
  • 预签名上传:OSS 与 COS 支持生成预签名 URL,客户端直传文件,服务端不中转数据
  • 多种文件类型:支持图片、音频、视频、办公文件、压缩文件等
  • 灵活配置:可自定义文件大小限制、允许的文件扩展名
  • 自动目录管理:按年月自动创建目录结构
  • Base64 支持:支持 Base64 编码的文件数据上传
  • 图片处理:自动获取图片尺寸信息
  • 错误处理:完善的错误处理和验证机制
  • 回调函数:支持保存前的自定义回调函数

快速开始

安装
go get github.com/jcbowen/jcbaseGo/component/attachment
基本使用示例
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    "github.com/jcbowen/jcbaseGo"
    "github.com/jcbowen/jcbaseGo/component/attachment"
)

func main() {
    r := gin.Default()

    r.POST("/upload", func(c *gin.Context) {
        // 获取上传的文件
        file, err := c.FormFile("file")
        if err != nil {
            c.JSON(400, gin.H{"error": "文件上传失败"})
            return
        }

        // 配置附件存储
        config := &jcbaseGo.AttachmentStruct{
            StorageType: "local",
            LocalDir:    "uploads",
        }

        // 创建附件实例
        att := attachment.New(c, config)

        // 配置上传选项
        opt := &attachment.Options{
            FileData: file,
            FileType: "image",
            MaxSize:  5 * 1024 * 1024, // 5MB
            AllowExt: []string{".jpg", ".jpeg", ".png", ".gif"},
        }

        // 上传并保存文件
        result := att.Upload(opt).Save()

        if result.HasError() {
            c.JSON(400, gin.H{"error": result.Error().Error()})
            return
        }

        // 返回上传结果
        c.JSON(200, gin.H{
            "message": "文件上传成功",
            "data": gin.H{
                "filename": result.FileName,
                "filepath": result.FileAttachment,
                "filesize": result.FileSize,
                "width":    result.Width,
                "height":   result.Height,
                "md5":      result.FileMD5,
            },
        })
    })

    r.Run(":8080")
}
URL / 域名转换示例
config := &jcbaseGo.AttachmentStruct{
    StorageType: "local",
    LocalDir:    "uploads",
    VisitDomain: "https://cdn.example.com/",
    LocalVisitDomain: "https://localhost:8080/",
}

att := attachment.New(c, config)
fullURL := att.ToMedia("images/avatar.png")
source := att.ToSource(fullURL)
querySource := att.ToSource(fullURL+"?v=123", false)
// fullURL => https://localhost:8080/uploads/images/avatar.png
// source  => images/avatar.png
// querySource => images/avatar.png?v=123

ToMedia 负责补全访问域名,ToSource 负责去除访问域名并返回相对路径,按输入形态与存储模式分支:命中本地访问域名时从文件类型目录 images/、videos/ 等处截取(本地 /static/ 内部资源保留 static 起始路径;未命中类型目录时剥离 LocalDir 前缀,覆盖 /uploads/seed/** 等非类型目录路径);命中远程访问域名时按对象 Key 语义处理,Key 中合法的 uploads 等目录段不会因 LocalDir 被误剥;未命中任何域名的 URL 在 local 存储模式下按 /<LocalDir>/ 路径前缀剥离(可归一历史按任意请求域名拼出的存量附件 URL),其余视为外链原样返回且保留查询参数,带参数外链(如占位图服务)不会被破坏。ToMedia 同样对齐 PHP 端 Util::toMedia:相对路径含 static/ 时从 static/ 处拼接本地资源域名(不追加 LocalDir);传入完整本地附件 URL 且命中类型目录时,会剥离域名与 LocalDir 前缀后重新拼装,远程存储开启时可借此切换到远程访问域名。附件 URL 默认会自动移除查询参数(如 ?v=123),如需保留则调用 att.ToSource(url, false),便于在服务端存储、展示和转发时保持统一的路径格式。

Base64 图片上传示例
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    "github.com/jcbowen/jcbaseGo"
    "github.com/jcbowen/jcbaseGo/component/attachment"
)

func main() {
    r := gin.Default()

    r.POST("/upload-base64", func(c *gin.Context) {
        var req struct {
            ImageData string `json:"image_data"`
        }
        
        if err := c.BindJSON(&req); err != nil {
            c.JSON(400, gin.H{"error": "请求参数错误"})
            return
        }

        config := &jcbaseGo.AttachmentStruct{
            StorageType: "local",
            LocalDir:    "uploads",
        }

        att := attachment.New(c, config)

        opt := &attachment.Options{
            FileData: req.ImageData, // Base64 编码的图片数据
            FileType: "image",
            MaxSize:  2 * 1024 * 1024, // 2MB
            AllowExt: []string{".jpg", ".jpeg", ".png"},
        }

        result := att.Upload(opt).Save()

        if result.HasError() {
            c.JSON(400, gin.H{"error": result.Error().Error()})
            return
        }

        c.JSON(200, gin.H{
            "message": "Base64 图片上传成功",
            "data": gin.H{
                "filename": result.FileName,
                "filepath": result.FileAttachment,
                "full_url": att.ToMedia(result.FileAttachment),
            },
        })
    })

    r.Run(":8080")
}
使用回调函数示例
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    "github.com/jcbowen/jcbaseGo"
    "github.com/jcbowen/jcbaseGo/component/attachment"
)

func main() {
    r := gin.Default()

    r.POST("/upload-with-callback", func(c *gin.Context) {
        file, err := c.FormFile("file")
        if err != nil {
            c.JSON(400, gin.H{"error": "文件上传失败"})
            return
        }

        config := &jcbaseGo.AttachmentStruct{
            StorageType: "local",
            LocalDir:    "uploads",
        }

        att := attachment.New(c, config)

        opt := &attachment.Options{
            FileData: file,
            FileType: "image",
            MaxSize:  5 * 1024 * 1024,
        }

        // 设置保存前的回调函数
        att.SetBeforeSave(func(a *attachment.Attachment) bool {
            // 检查文件大小是否超过 1MB
            if a.FileSize > 1*1024*1024 {
                a.addError(fmt.Errorf("文件大小不能超过 1MB"))
                return false
            }
            
            // 可以在这里添加其他自定义验证逻辑
            fmt.Printf("文件信息: %s, 大小: %d bytes\n", a.FileName, a.FileSize)
            return true
        })

        result := att.Upload(opt).Save()

        if result.HasError() {
            c.JSON(400, gin.H{"error": result.Error().Error()})
            return
        }

        c.JSON(200, gin.H{
            "message": "文件上传成功",
            "data": gin.H{
                "filename": result.FileName,
                "filepath": result.FileAttachment,
            },
        })
    })

    r.Run(":8080")
}

详细配置

AttachmentStruct 配置

AttachmentStruct 是附件存储的基础配置结构体:

type AttachmentStruct struct {
    StorageType      string `json:"storage_type" default:"local"` // 存储类型: local/cos/oss/ftp/sftp
    LocalDir         string `json:"local_dir" default:"uploads"`  // 本地存储目录
    VisitDomain      string `json:"visit_domain" default:"/"`     // 访问域名
    LocalVisitDomain string `json:"local_visit_domain"`           // 本地访问域名
}
Options 配置

Options 是文件上传的选项配置:

type Options struct {
    Group    string      // 附件分组
    FileData interface{} // 文件数据: *multipart.FileHeader, string(base64), []byte
    FileType string      // 文件类型: image/voice/video/office/zip
    MaxSize  int64       // 最大文件大小(字节)
    AllowExt []string    // 允许的文件扩展名
}
预定义文件类型

组件预定义了多种文件类型的配置:

// 图片类型
Types["image"] = &typeInfo{
    TypeName: "图片",
    AllowExt: []string{".gif", ".jpg", ".jpeg", ".bmp", ".png", ".ico"},
    MaxSize:  5 * 1024 * 1024, // 5MB
}

// 音频类型  
Types["voice"] = &typeInfo{
    TypeName: "音频",
    AllowExt: []string{".mp3", ".wma", ".wav", ".amr"},
    MaxSize:  50 * 1024 * 1024, // 50MB
}

// 视频类型
Types["video"] = &typeInfo{
    TypeName: "视频",
    AllowExt: []string{".rm", ".rmvb", ".wmv", ".avi", ".mpg", ".mpeg", ".mp4"},
    MaxSize:  300 * 1024 * 1024, // 300MB
}

// 办公文件类型
Types["office"] = &typeInfo{
    TypeName: "办公文件",
    AllowExt: []string{".wps", ".wpt", ".doc", ".dot", ".docx", ".docm", ".dotm", 
                      ".et", ".ett", ".xls", ".xlt", ".xlsx", ".xlsm", ".xltx", ".xltm", ".xlsb",
                      ".dps", ".dpt", ".ppt", ".pps", ".pot", ".pptx", ".ppsx", ".potx",
                      ".txt", ".csv", ".prn", ".pdf", ".xml"},
    MaxSize:  50 * 1024 * 1024, // 50MB
}

// 压缩文件类型
Types["zip"] = &typeInfo{
    TypeName: "压缩文件",
    AllowExt: []string{".zip", ".rar"},
    MaxSize:  500 * 1024 * 1024, // 500MB
}

高级功能

使用云存储(腾讯云 COS)
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    "github.com/jcbowen/jcbaseGo"
    "github.com/jcbowen/jcbaseGo/component/attachment"
)

func main() {
    r := gin.Default()

    r.POST("/upload-cos", func(c *gin.Context) {
        file, err := c.FormFile("file")
        if err != nil {
            c.JSON(400, gin.H{"error": "文件上传失败"})
            return
        }

        // 基础配置
        config := &jcbaseGo.AttachmentStruct{
            StorageType: "cos",
            LocalDir:    "uploads",
        }

        // 腾讯云 COS 配置
        cosConfig := jcbaseGo.COSStruct{
            SecretId:  "your-secret-id",
            SecretKey: "your-secret-key",
            Region:    "ap-beijing",
            BucketName: "your-bucket-name",
            CustomizeVisitDomain: "https://your-cdn-domain.com",
        }

        // 创建附件实例(传入 COS 配置)
        att := attachment.New(c, config, cosConfig)

        opt := &attachment.Options{
            FileData: file,
            FileType: "image",
            MaxSize:  10 * 1024 * 1024, // 10MB
        }

        result := att.Upload(opt).Save()

        if result.HasError() {
            c.JSON(400, gin.H{"error": result.Error().Error()})
            return
        }

        c.JSON(200, gin.H{
            "message": "文件上传到 COS 成功",
            "data": gin.H{
                "filename": result.FileName,
                "filepath": result.FileAttachment,
                "full_url": att.ToMedia(result.FileAttachment),
            },
        })
    })

    r.Run(":8080")
}
预签名上传(OSS / COS)

当需要由客户端直传文件到对象存储时,可以调用 GetPresignURL 生成预签名上传 URL,服务端无需中转文件数据。目前 oss 与 cos 两种存储类型支持该能力。

阿里云 OSS 预签名上传
package main

import (
    "context"
    "time"
    "github.com/gin-gonic/gin"
    "github.com/jcbowen/jcbaseGo"
    "github.com/jcbowen/jcbaseGo/component/attachment"
    "github.com/jcbowen/jcbaseGo/component/attachment/remote"
)

func main() {
    r := gin.Default()

    r.POST("/presign-oss", func(c *gin.Context) {
        // 基础配置,存储类型必须为 oss
        baseConfig := &jcbaseGo.AttachmentStruct{
            StorageType: "oss",
            LocalDir:    "uploads",
        }

        // OSS 远程配置
        ossConfig := jcbaseGo.OSSStruct{
            AccessKeyId:     "your-access-key-id",
            AccessKeySecret: "your-access-key-secret",
            Endpoint:        "oss-cn-hangzhou.aliyuncs.com",
            BucketName:      "your-bucket-name",
        }

        // 创建附件实例
        att := attachment.New(c, baseConfig, ossConfig)

        // 生成预签名上传 URL,有效期 10 分钟
        opts := &remote.PresignOptions{
            Expires:     10 * time.Minute,
            ContentType: "image/jpeg", // 如需限制文件类型,可指定 Content-Type
        }
        url, headers, err := att.GetPresignURL(c.Request.Context(), "images/2024/01/example.jpg", opts)
        if err != nil {
            c.JSON(400, gin.H{"error": err.Error()})
            return
        }

        c.JSON(200, gin.H{
            "message": "预签名 URL 生成成功",
            "data": gin.H{
                "url":     url,
                "headers": headers,
                "method":  "PUT",
            },
        })
    })

    r.Run(":8080")
}
腾讯云 COS 预签名上传
package main

import (
    "context"
    "time"
    "github.com/gin-gonic/gin"
    "github.com/jcbowen/jcbaseGo"
    "github.com/jcbowen/jcbaseGo/component/attachment"
    "github.com/jcbowen/jcbaseGo/component/attachment/remote"
)

func main() {
    r := gin.Default()

    r.POST("/presign-cos", func(c *gin.Context) {
        // 基础配置,存储类型必须为 cos
        baseConfig := &jcbaseGo.AttachmentStruct{
            StorageType: "cos",
            LocalDir:    "uploads",
        }

        // COS 远程配置
        // - Url 为存储桶访问域名,可省略;省略时使用 Bucket 与 Region 自动构造
        //   https://{Bucket}.cos.{Region}.myqcloud.com
        // - Token 为可选字段,使用 STS 临时密钥时填写
        cosConfig := jcbaseGo.COSStruct{
            SecretId:  "your-secret-id",
            SecretKey: "your-secret-key",
            Token:     "your-session-token", // 使用临时密钥时填写,永久密钥可留空
            Region:    "ap-guangzhou",
            Bucket:    "your-bucket-1250000000",
            Url:       "https://your-bucket-1250000000.cos.ap-guangzhou.myqcloud.com",
        }

        att := attachment.New(c, baseConfig, cosConfig)

        opts := &remote.PresignOptions{
            Expires:     10 * time.Minute,
            ContentType: "image/jpeg",
            // COS 自定义元数据需使用 x-cos-meta- 前缀才会参与签名;
            // 未加前缀的 key 会自动补齐为 x-cos-meta-{key}
            Metadata: map[string]string{
                "x-cos-meta-uid": "12345",
            },
        }
        url, headers, err := att.GetPresignURL(c.Request.Context(), "images/2024/01/example.jpg", opts)
        if err != nil {
            c.JSON(400, gin.H{"error": err.Error()})
            return
        }

        c.JSON(200, gin.H{
            "message": "预签名 URL 生成成功",
            "data": gin.H{
                "url":     url,
                "headers": headers,
                "method":  "PUT",
            },
        })
    })

    r.Run(":8080")
}

注意事项:

  • 当前仅 StorageType 为 oss 与 cos 时支持预签名上传,其余存储类型返回 remote.ErrPresignNotSupported;新增存储类型只需实现 remote.PresignUploader 接口即可接入,无需修改上层方法。
  • 客户端需要使用 PUT 方法将文件内容上传至返回的 url。
  • 如果生成时指定了 ContentType 或 Metadata,返回的 headers 会包含对应签名头,客户端必须原样携带,否则签名校验会失败。
  • COS 仅对 Content-Type 等特定请求头以及 x-cos- 前缀的请求头参与签名。自定义元数据建议使用 x-cos-meta- 前缀;若未使用,组件会自动补齐为 x-cos-meta-{key}。
  • COS 预签名默认签入 Host,客户端必须使用返回的域名上传,不可改写为其他域名。
  • COS 支持使用永久密钥或 STS 临时密钥生成预签名 URL;使用临时密钥时需在 COSStruct.Token 中传入 SessionToken,生成的 URL 会自动携带 x-cos-security-token。
  • 预签名有效期最长不超过 7 天(604800 秒),超出会返回错误;Expires 为零时默认使用 10 分钟。
  • 远程客户端实例在首次调用时创建并缓存在 Attachment 实例中,同一实例重复调用时直接复用,无需重复创建;若运行期间修改了 RemoteConfig,会自动重建客户端。
对象存在性检测

预签名上传存在「客户端拿到 URL 却未真正上传」的情况,因此秒传命中时需要校验对象是否真实存在:

ok, err := att.ObjectExists(ctx, "images/2024/01/example.jpg")
  • oss 与 cos 通过 HEAD Object 低成本探测,对象不存在时返回 (false, nil)。
  • 不支持探测的存储类型(如 FTP/SFTP)按「存在」处理,返回 (true, nil),以保持既有秒传行为。
使用分组管理
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    "github.com/jcbowen/jcbaseGo"
    "github.com/jcbowen/jcbaseGo/component/attachment"
)

func main() {
    r := gin.Default()

    r.POST("/upload-group", func(c *gin.Context) {
        file, err := c.FormFile("file")
        if err != nil {
            c.JSON(400, gin.H{"error": "文件上传失败"})
            return
        }

        config := &jcbaseGo.AttachmentStruct{
            StorageType: "local",
            LocalDir:    "uploads",
        }

        att := attachment.New(c, config)

        // 使用分组管理
        opt := &attachment.Options{
            Group:    "user_avatar", // 分组名称
            FileData: file,
            FileType: "image",
            MaxSize:  2 * 1024 * 1024,
        }

        result := att.Upload(opt).Save()

        if result.HasError() {
            c.JSON(400, gin.H{"error": result.Error().Error()})
            return
        }

        c.JSON(200, gin.H{
            "message": "分组文件上传成功",
            "data": gin.H{
                "filename": result.FileName,
                "filepath": result.FileAttachment,
                "group":   "user_avatar",
            },
        })
    })

    r.Run(":8080")
}
生成访问 URL
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/attachment"
)

func main() {
    // 创建附件实例(不需要 gin 上下文)
    att := attachment.New(nil, nil)

    // 生成完整的访问 URL
    filePath := "images/2023/10/0112345678901234567890.jpg"
    
    // 本地访问 URL(不追加时间戳)
    localURL := att.ToMedia(filePath, true, true)
    fmt.Printf("本地访问 URL: %s\n", localURL)
    
    // 远程访问 URL(第二个参数传 false 会追加 ?v= 时间戳以绕过缓存)
    remoteURL := att.ToMedia(filePath, false, false)
    fmt.Printf("远程访问 URL(带缓存时间戳): %s\n", remoteURL)
    
    // 不带时间戳的远程访问 URL
    remoteURLNoCache := att.ToMedia(filePath, false, true)
    fmt.Printf("不带缓存时间戳的远程访问 URL: %s\n", remoteURLNoCache)
}

错误处理

错误检查方法
result := att.Upload(opt).Save()

// 检查是否有错误
if result.HasError() {
    // 获取第一个错误
    fmt.Printf("错误: %v\n", result.Error())
    
    // 获取所有错误
    errors := result.Errors()
    for _, err := range errors {
        fmt.Printf("详细错误: %v\n", err)
    }
}
常见错误类型
  • 文件类型不支持:文件扩展名不在允许的列表中
  • 文件大小超限:文件大小超过配置的最大限制
  • 目录创建失败:无法创建文件存储目录
  • 文件保存失败:无法将文件保存到目标位置
  • Base64 解析失败:Base64 数据格式不正确

测试

组件测试全部可以在本地完成,运行 go test 时不需要连接任何外部服务器,也不依赖网络环境。

# 运行组件全部测试
go test ./component/attachment/...

# 带竞态检测运行
go test ./component/attachment/... -race
本地测试服务器

FTP 与 SFTP 的用例在测试进程内启动本地服务器,测试结束自动关闭,文件只保存在进程内存中:

文件 说明
remote/ftpserver_test.go 内存 FTP 服务器,监听 127.0.0.1 随机端口,实现 USER / PASS / FEAT / TYPE / EPSV / PASV / STOR / RETR / MLSD / MKD / CWD / DELE / SIZE / MDTM / NOOP / QUIT 等命令
remote/sftpserver_test.go 内存 SFTP 服务器,基于 SSH 服务端(测试期生成 ed25519 主机密钥)与内存文件系统实现

设计要点:

  1. 零外部依赖:服务器绑定回环地址的随机端口,不占用固定端口,不产生端口冲突。
  2. 不落磁盘:FTP 使用内存目录树,SFTP 使用内存文件系统,测试结束后数据随进程释放。
  3. 不新增依赖:实现全部基于项目已有依赖(标准库、jlaffaye/ftp、pkg/sftp、golang.org/x/crypto/ssh)。
  4. COS / OSS 用例:仅做预签名 URL 的本地签名计算、存在性探测的上下文取消处理与客户端构造,不发起任何网络请求。
已移除的真实测试服依赖

早期 FTP / SFTP 用例需要连接测试服才能执行,相关环境变量(FTP_TEST_ADDRESS、FTP_TEST_USERNAME、FTP_TEST_PASSWORD、FTP_TEST_SKIP、SFTP_TEST_RUN、SFTP_TEST_ADDRESS 等)已全部废弃并移除,源码中不再保留任何指向测试服的地址。

性能优化建议

  1. 文件大小限制:根据实际需求设置合理的文件大小限制
  2. 存储类型选择:根据访问频率选择合适的存储类型
  3. CDN 加速:对于图片等静态资源,建议使用 CDN 加速
  4. 异步上传:对于大文件上传,可以考虑使用异步处理

安全考虑

  • 严格验证文件类型,防止恶意文件上传
  • 设置合理的文件大小限制
  • 对上传的文件进行病毒扫描(如果适用)
  • 使用安全的存储服务,配置适当的访问权限

API 参考

主要结构体
Attachment

附件管理的主要结构体

字段:

  • Opt *Options - 上传选项配置
  • GinContext *gin.Context - Gin 上下文
  • BaseConfig *jcbaseGo.AttachmentStruct - 基础配置
  • RemoteConfig interface{} - 远程存储配置
  • FileType string - 文件类型
  • FileName string - 文件名
  • FileSize int64 - 文件大小
  • FileAttachment string - 文件相对路径
  • FileMD5 string - 文件 MD5 值
  • FileExt string - 文件扩展名
  • Width int - 图片宽度
  • Height int - 图片高度

方法:

  • New(args ...interface{}) *Attachment - 创建附件实例
  • Upload(opt *Options) *Attachment - 配置上传选项
  • SetBeforeSave(fn func(a *Attachment) bool) *Attachment - 设置保存前回调
  • Save() *Attachment - 保存文件
  • ToMedia(src string, args ...interface{}) string - 生成访问 URL
  • ToSource(src string, args ...bool) string - 将访问 URL 还原为相对路径(对齐 PHP 端 Util::removeMediaDomain)
  • GetPresignURL(ctx context.Context, remotePath string, opts *remote.PresignOptions) (string, map[string]string, error) - 生成预签名上传 URL,支持 oss 与 cos
  • ObjectExists(ctx context.Context, remotePath string) (bool, error) - 判断远端对象是否存在,支持 oss 与 cos
  • HasError() bool - 检查是否有错误
  • Error() error - 获取第一个错误
  • Errors() []error - 获取所有错误
Options

上传选项配置结构体

字段:

  • Group string - 附件分组
  • FileData interface{} - 文件数据
  • FileType string - 文件类型
  • MaxSize int64 - 最大文件大小
  • AllowExt []string - 允许的文件扩展名

贡献指南

欢迎提交 Issue 和 Pull Request 来改进 Attachment 组件。

许可证

Attachment 组件遵循 MIT 许可证。

Documentation

Index

Constants

This section is empty.

Variables

View Source
var Types = map[string]*typeInfo{
	"image": {
		TypeName: "图片",
		AllowExt: []string{".gif", ".jpg", ".jpeg", ".bmp", ".png", ".ico", ".webp", ".heic"},
		MaxSize:  5 * 1024 * 1024,
	},
	"voice": {
		TypeName: "音频",
		AllowExt: []string{".mp3", ".wma", ".wav", ".amr", ".m4a", ".aac", ".ogg", ".flac"},
		MaxSize:  50 * 1024 * 1024,
	},
	"video": {
		TypeName: "视频",
		AllowExt: []string{".rm", ".rmvb", ".wmv", ".avi", ".mpg", ".mpeg", ".mp4", ".mov", ".mkv", ".flv", ".webm", ".3gp", ".m4v"},
		MaxSize:  300 * 1024 * 1024,
	},
	"office": {
		TypeName: "办公文件",
		AllowExt: []string{
			".wps", ".wpt", ".doc", ".dot", ".docx", ".docm", ".dotm",
			".et", ".ett", ".xls", ".xlt", ".xlsx", ".xlsm", ".xltx", ".xltm", ".xlsb",
			".dps", ".dpt", ".ppt", ".pps", ".pot", ".pptx", ".ppsx", ".potx",
			".txt", ".csv", ".prn", ".pdf", ".xml",
		},
		MaxSize: 50 * 1024 * 1024,
	},
	"zip": {
		TypeName: "压缩文件",
		AllowExt: []string{".zip", ".rar", ".apk", ".7z", ".wgt", ".tar", ".gz", ".bz2"},
		MaxSize:  500 * 1024 * 1024,
	},
}

Types 附件类型 注意:扩展名白名单需与 PHP 主体服务(jcbase-yii2,业务层经 Yii::$app->params['upload']['{type}']['extensions'] 配置覆盖)保持对齐, 单侧新增格式可能导致跨系统附件通道读不通。

Functions

This section is empty.

Types

type Attachment

type Attachment struct {
	Opt *Options // 附件实例化时的参数选项

	GinContext   *gin.Context               // gin上下文
	BaseConfig   *jcbaseGo.AttachmentStruct // 附件配置信息
	RemoteConfig interface{}                // 远程附件配置

	FileType       string // 附件类型
	FileName       string // 附件名
	FileSize       int64  // 附件大小
	FileAttachment string // 附件相对路径
	FileMD5        string // 附件MD5
	FileExt        string // 文件扩展名
	Width          int    // 图片宽
	Height         int    // 图片高
	// contains filtered or unexported fields
}

Attachment 附件结构体,包含文件头信息、扩展名、保存目录和错误列表

func New

func New(args ...interface{}) *Attachment

New 创建一个新的附件实例 args:

  • GinContext *gin.Context Gin 上下文
  • BaseConfig *jcbaseGo.AttachmentStruct 附件配置
  • RemoteConfig interface{} 远程附件配置

func (*Attachment) Error

func (a *Attachment) Error() error

Error 返回第一个捕获的错误

func (*Attachment) Errors

func (a *Attachment) Errors() []error

Errors 返回所有捕获的错误

func (*Attachment) GetPresignURL added in v0.13.24

func (a *Attachment) GetPresignURL(ctx context.Context, remotePath string, opts *remote.PresignOptions) (string, map[string]string, error)

GetPresignURL 生成预签名上传 URL。 - ctx: 请求上下文。 - remotePath: 对象在存储桶中的路径(Key)。 - opts: 预签名选项,nil 时表示使用默认选项。 返回值:

  • string: 预签名 URL,客户端可通过 PUT 请求将文件上传至此 URL。
  • map[string]string: 需要在上传请求中携带的已签名请求头。
  • error: 当存储类型不受支持、远程配置错误或客户端不支持预签名时返回错误。

说明:

  • 是否支持预签名由远程客户端是否实现 remote.PresignUploader 接口决定, 新增存储类型实现该接口后无需修改本方法。
  • 远程客户端实例在首次调用时创建并缓存在 Attachment 实例中,重复调用时直接复用。

func (*Attachment) HasError

func (a *Attachment) HasError() bool

HasError 是否有错误

func (*Attachment) ObjectExists added in v0.14.0

func (a *Attachment) ObjectExists(ctx context.Context, remotePath string) (bool, error)

ObjectExists 判断指定路径的对象是否已存在于远端存储。 参数:

  • ctx context.Context: 上下文,可用于控制探测超时
  • remotePath string: 对象在存储中的相对路径

返回值:

  • bool: 对象存在返回 true;存储类型不支持探测时同样返回 true
  • error: 远程客户端创建失败或探测过程异常时返回错误

说明:

  • 是否支持探测由远程客户端是否实现 remote.ObjectExister 接口决定。
  • 不支持探测时按「存在」处理,以保持 FTP/SFTP 等存储类型的既有秒传行为。

使用示例:

ok, err := att.ObjectExists(ctx, "images/2026/08/xxx.png")

func (*Attachment) Save

func (a *Attachment) Save() *Attachment

Save 保存文件到指定的附件目录

func (*Attachment) SetBeforeSave

func (a *Attachment) SetBeforeSave(fn func(a *Attachment) bool) *Attachment

SetBeforeSave 设置保存文件前的回调函数 - 回调函数返回 true 则继续保存,回调函数返回 false 则跳过

func (*Attachment) ToMedia

func (a *Attachment) ToMedia(src string, args ...interface{}) string

ToMedia 将附件相对路径补全为可访问的完整 URL。 参数:

  • src: 附件源路径(可为相对路径、绝对路径或已带协议的 URL)
  • args: 可选参数,args[0] 表示是否强制使用本地访问域名;args[1] 表示是否启用缓存,传 false 时会在路径尾部追加 ?v= 时间戳以绕过缓存(与 PHP 端 $is_cache 语义一致,默认 true 不追加)

返回值:

  • 访问链接,若 src 为空则返回空字符串

异常:

  • 若 args 中类型不匹配,则使用默认值,避免因强制类型转换导致 panic

示例:

att.ToMedia("avatar.png") => "https://host/uploads/avatar.png" // 本地存储:域名 + LocalDir + 相对路径
att.ToMedia("images/avatar.png") => "https://cdn.host/images/avatar.png" // 远程存储:仅补全访问域名
att.ToMedia("static/js/app.js") => "https://host/static/js/app.js" // 含 static/ 的资源:从 static/ 处拼接本地域名
att.ToMedia("https://host/uploads/images/avatar.png") => "https://cdn.host/images/avatar.png" // 本地完整 URL 重组(远程存储时切换到远程域名)

func (*Attachment) ToSource added in v0.15.4

func (a *Attachment) ToSource(src string, args ...bool) string

ToSource 将附件访问 URL 或带域名的路径还原为相对路径。 还原规则按输入形态与存储模式分支:

  • 命中本地访问域名(LocalVisitDomain):优先从文件类型目录(images/videos/offices 等)截取; 未命中类型目录与 static 时剥离 LocalDir 前缀(覆盖 /uploads/seed/** 等非类型目录路径)
  • 命中远程访问域名(VisitDomain):按对象 Key 语义从类型目录截取; 对象 Key 合法含 uploads 等目录段时不做强行剥离(远程 Key 与本地 LocalDir 无关)
  • 未命中任何域名的 http(s) URL:local 存储模式下路径命中 /<LocalDir>/ 前缀即剥离 (覆盖历史按任意请求域名拼出的存量附件 URL);其余视为外链原样返回,且不再剥除 查询参数,保证带参数外链(如占位图服务)不被破坏
  • 纯路径形态(/uploads/... 或 uploads/...):local 存储模式下剥离 LocalDir 前缀, 其余仅去掉开头的 /

参数:

  • src: 带附件域名的 URL 或路径
  • args: 可选参数,args[0] 表示是否移除 URL 中的查询参数;默认 true

返回值:

  • 剥离域名后的相对路径,若 src 为空则返回空字符串

异常:

  • 无异常;无法识别的 URL 会原样返回

示例:

att.ToSource("https://localhost:8080/uploads/images/logo.png")        => "images/logo.png"
att.ToSource("https://old-host.example/uploads/images/logo.png")      => "images/logo.png" // 历史请求域名存量,按路径前缀剥离
att.ToSource("https://localhost:8080/uploads/seed/x.png")             => "seed/x.png"      // 非类型目录路径剥离 LocalDir
att.ToSource("https://cdn.example.com/uploads/myzipfile/x.png")       => "uploads/myzipfile/x.png" // 远程 Key 不做 LocalDir 剥离
att.ToSource("https://placehold.co/300x300?text=Tomato")              => 原样返回(外链保留查询参数)
att.ToSource("https://host/attachment/avatar.png?v=123", false)       => "attachment/avatar.png?v=123"

func (*Attachment) Upload

func (a *Attachment) Upload(opt *Options) *Attachment

Upload 初始化文件上传参数

type Options

type Options struct {
	Group string // 附件组,默认不分组(分组会文件类型目录前多一级分组目录)

	FileData interface{} // 文件数据,支持 base64 字符串、*multipart.FileHeader、[]byte
	FileType string      // 文件类型,默认为 image
	MaxSize  int64       // 最大文件大小
	AllowExt []string    // 允许的文件扩展名
}

Options 附件实例化时的参数选项

Directories

Path Synopsis
Package remote 提供多种远程存储方式的统一接口。
Package remote 提供多种远程存储方式的统一接口。

Jump to

Keyboard shortcuts

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