attachment

package
v0.13.11 Latest Latest
Warning

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

Go to latest
Published: Dec 6, 2025 License: MIT Imports: 21 Imported by: 0

README

Attachment 组件

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

概述

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

功能特性

  • 多存储支持:支持本地存储、腾讯云 COS、阿里云 OSS、FTP、SFTP
  • 多种文件类型:支持图片、音频、视频、办公文件、压缩文件等
  • 灵活配置:可自定义文件大小限制、允许的文件扩展名
  • 自动目录管理:按年月自动创建目录结构
  • 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")
}
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")
}
使用分组管理
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, false)
    fmt.Printf("本地访问 URL: %s\n", localURL)
    
    // 远程访问 URL(带缓存时间戳)
    remoteURL := att.ToMedia(filePath, false, true)
    fmt.Printf("远程访问 URL: %s\n", remoteURL)
    
    // 不带时间戳的远程访问 URL
    remoteURLNoCache := att.ToMedia(filePath, false, false)
    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 数据格式不正确

性能优化建议

  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
  • HasError() bool - 检查是否有错误
  • Error() error - 获取第一个错误
  • Errors() []error - 获取所有错误
Options

上传选项配置结构体

字段:

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

版本历史

  • v1.0.0:初始版本,包含基本的文件上传和管理功能
  • 支持多种存储类型和文件类型

贡献指南

欢迎提交 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"},
		MaxSize:  5 * 1024 * 1024,
	},
	"voice": {
		TypeName: "音频",
		AllowExt: []string{".mp3", ".wma", ".wav", ".amr"},
		MaxSize:  50 * 1024 * 1024,
	},
	"video": {
		TypeName: "视频",
		AllowExt: []string{".rm", ".rmvb", ".wmv", ".avi", ".mpg", ".mpeg", ".mp4"},
		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"},
		MaxSize:  500 * 1024 * 1024,
	},
}

Types 附件类型

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) HasError

func (a *Attachment) HasError() bool

HasError 是否有错误

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

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