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 负责去除访问域名并返回相对路径(逻辑对齐 PHP 端 Util::removeMediaDomain:命中附件域名后从文件类型目录 images/、videos/ 等处截取,本地 LocalDir 前缀会被一并剥离;本地 /static/ 内部资源则保留 static 起始路径)。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 主机密钥)与内存文件系统实现 |
设计要点:
- 零外部依赖:服务器绑定回环地址的随机端口,不占用固定端口,不产生端口冲突。
- 不落磁盘:FTP 使用内存目录树,SFTP 使用内存文件系统,测试结束后数据随进程释放。
- 不新增依赖:实现全部基于项目已有依赖(标准库、
jlaffaye/ftp、pkg/sftp、golang.org/x/crypto/ssh)。
- COS / OSS 用例:仅做预签名 URL 的本地签名计算、存在性探测的上下文取消处理与客户端构造,不发起任何网络请求。
已移除的真实测试服依赖
早期 FTP / SFTP 用例需要连接测试服才能执行,相关环境变量(FTP_TEST_ADDRESS、FTP_TEST_USERNAME、FTP_TEST_PASSWORD、FTP_TEST_SKIP、SFTP_TEST_RUN、SFTP_TEST_ADDRESS 等)已全部废弃并移除,源码中不再保留任何指向测试服的地址。
性能优化建议
- 文件大小限制:根据实际需求设置合理的文件大小限制
- 存储类型选择:根据访问频率选择合适的存储类型
- CDN 加速:对于图片等静态资源,建议使用 CDN 加速
- 异步上传:对于大文件上传,可以考虑使用异步处理
安全考虑
- 严格验证文件类型,防止恶意文件上传
- 设置合理的文件大小限制
- 对上传的文件进行病毒扫描(如果适用)
- 使用安全的存储服务,配置适当的访问权限
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 许可证。