lingstorage

README

LingStorage SDK

LingStorage SDK is a Go language client library for interacting with LingStorage services. It provides easy-to-use APIs for uploading files, managing buckets, and other functions.

Features

• 文件操作
  • 文件上传（支持图片压缩和水印）
  • 文件删除
  • 文件复制和移动
  • 获取文件信息和访问URL
  • 批量上传
• 存储桶管理
  • 创建和删除存储桶
  • 列举存储桶和文件
  • 设置存储桶权限
  • 获取存储桶域名
• 其他功能
  • 多种存储后端支持（本地、七牛云、阿里云OSS、AWS S3等）
  • API Key 认证
  • 文件类型和大小限制
  • 上传进度回调
  • 错误重试机制
  • 全面的测试覆盖

快速开始

安装

go get github.com/LingByte/lingstorage-sdk-go

基本使用

package main

import (
    "fmt"
    "log"
    "time"
    
    lingstorage "github.com/LingByte/lingstorage-sdk-go"
)

func main() {
    // 创建客户端
    client := lingstorage.NewClient(&lingstorage.Config{
        BaseURL:   "https://your-lingstorage-server.com",
        APIKey:    "your-api-key",
        APISecret: "your-api-secret",
    })
    
    // 测试连接
    if err := client.Ping(); err != nil {
        log.Fatal("服务器连接失败:", err)
    }
    
    // 上传文件
    result, err := client.UploadFile(&lingstorage.UploadRequest{
        FilePath: "./example.jpg",
        Bucket:   "default",
        Key:      "uploads/example.jpg",
    })
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("文件上传成功: %s\n", result.URL)
}

API 文档

文件操作

上传文件

// 基本上传
result, err := client.UploadFile(&lingstorage.UploadRequest{
    FilePath: "./photo.jpg",
    Bucket:   "images",
    Key:      "uploads/photo.jpg",
})

// 图片压缩和水印
result, err := client.UploadFile(&lingstorage.UploadRequest{
    FilePath: "./photo.jpg",
    Bucket:   "images",
    
    // 图片压缩
    Compress: true,
    Quality:  80,
    
    // 添加水印
    Watermark: true,
    WatermarkText: "© 2024 My Company",
    WatermarkPosition: "bottom-right",
    
    // 进度回调
    OnProgress: func(uploaded, total int64) {
        fmt.Printf("上传进度: %.2f%%\n", float64(uploaded)/float64(total)*100)
    },
})

删除文件

err := client.DeleteFile("bucket-name", "file-key")
if err != nil {
    log.Printf("删除文件失败: %v", err)
}

获取文件信息

fileInfo, err := client.GetFileInfo("bucket-name", "file-key")
if err != nil {
    log.Printf("获取文件信息失败: %v", err)
} else {
    fmt.Printf("文件大小: %d bytes\n", fileInfo.Size)
    fmt.Printf("最后修改时间: %v\n", fileInfo.LastModified)
}

获取文件访问URL

// 获取1小时有效期的访问URL
fileURL, err := client.GetFileURL("bucket-name", "file-key", time.Hour)
if err != nil {
    log.Printf("获取文件URL失败: %v", err)
} else {
    fmt.Printf("文件URL: %s\n", fileURL)
}

复制文件

err := client.CopyFile(&lingstorage.CopyFileRequest{
    SrcBucket:  "source-bucket",
    SrcKey:     "source/file.jpg",
    DestBucket: "dest-bucket",
    DestKey:    "backup/file.jpg",
})

移动文件

err := client.MoveFile(&lingstorage.MoveFileRequest{
    SrcBucket:  "source-bucket",
    SrcKey:     "temp/file.jpg",
    DestBucket: "dest-bucket",
    DestKey:    "final/file.jpg",
})

存储桶管理

列举存储桶

buckets, err := client.ListBuckets("", false)
if err != nil {
    log.Printf("列举存储桶失败: %v", err)
} else {
    fmt.Printf("找到 %d 个存储桶: %v\n", len(buckets), buckets)
}

创建存储桶

err := client.CreateBucket(&lingstorage.CreateBucketRequest{
    BucketName: "my-new-bucket",
    Region:     "us-east-1",
})

删除存储桶

err := client.DeleteBucket("bucket-to-delete")

列举文件

result, err := client.ListFiles(&lingstorage.ListFilesRequest{
    Bucket:    "my-bucket",
    Prefix:    "uploads/",
    Limit:     100,
    Delimiter: "/",
})
if err != nil {
    log.Printf("列举文件失败: %v", err)
} else {
    fmt.Printf("找到 %d 个文件\n", len(result.Files))
    for _, file := range result.Files {
        fmt.Printf("  - %s (%d bytes)\n", file.Key, file.Size)
    }
}

获取存储桶域名

domains, err := client.GetBucketDomains("my-bucket")
if err != nil {
    log.Printf("获取域名失败: %v", err)
} else {
    fmt.Printf("存储桶域名: %v\n", domains)
}

设置存储桶权限

err := client.SetBucketPrivate(&lingstorage.SetBucketPrivateRequest{
    BucketName: "my-bucket",
    IsPrivate:  true,
})

高级功能

批量上传

files := []string{"file1.jpg", "file2.png", "file3.pdf"}
results, err := client.BatchUpload(&lingstorage.BatchUploadRequest{
    Files:  files,
    Bucket: "documents",
    
    // 批量上传进度回调
    OnProgress: func(completed, total int, current string) {
        fmt.Printf("批量上传进度: %d/%d - 当前文件: %s\n", completed, total, current)
    },
    
    // 单个文件上传进度回调
    OnFileProgress: func(uploaded, total int64) {
        fmt.Printf("文件上传进度: %.2f%%\n", float64(uploaded)/float64(total)*100)
    },
})

从内存上传

data := []byte("Hello, World!")
result, err := client.UploadBytes(&lingstorage.UploadBytesRequest{
    Data:     data,
    Filename: "hello.txt",
    Bucket:   "text-files",
    Key:      "greetings/hello.txt",
})

从 io.Reader 上传

file, err := os.Open("large-file.zip")
if err != nil {
    log.Fatal(err)
}
defer file.Close()

result, err := client.UploadFromReader(&lingstorage.UploadFromReaderRequest{
    Reader:   file,
    Filename: "large-file.zip",
    Size:     fileSize, // 如果已知文件大小
    Bucket:   "archives",
    Key:      "uploads/large-file.zip",
})

数据结构

客户端配置

type Config struct {
    BaseURL    string        // LingStorage 服务器地址
    APIKey     string        // API 密钥
    APISecret  string        // API 密钥对应的 Secret
    Timeout    time.Duration // 请求超时时间（默认30秒）
    RetryCount int           // 重试次数（默认3次）
    UserAgent  string        // 用户代理（可选）
}

上传请求

type UploadRequest struct {
    FilePath          string   // 本地文件路径
    Bucket            string   // 存储桶名称
    Key               string   // 文件键名（可选，自动生成）
    AllowedTypes      []string // 允许的文件类型（可选）
    
    // 图片处理选项
    Compress          bool     // 是否压缩图片
    Quality           int      // 压缩质量 1-100
    Watermark         bool     // 是否添加水印
    WatermarkText     string   // 水印文本
    WatermarkPosition string   // 水印位置
    
    // 回调函数
    OnProgress        func(uploaded, total int64) // 上传进度回调
}

上传响应

type UploadResult struct {
    Key          string `json:"key"`          // 文件键名
    Bucket       string `json:"bucket"`       // 存储桶名称
    Filename     string `json:"filename"`     // 原始文件名
    Size         int64  `json:"size"`         // 文件大小
    OriginalSize int64  `json:"originalSize"` // 原始文件大小
    Compressed   bool   `json:"compressed"`   // 是否已压缩
    Watermarked  bool   `json:"watermarked"`  // 是否已添加水印
    URL          string `json:"url"`          // 访问URL
}

文件信息

type FileInfo struct {
    Key          string    `json:"key"`          // 文件键名
    Size         int64     `json:"size"`         // 文件大小
    LastModified time.Time `json:"lastModified"` // 最后修改时间
    ETag         string    `json:"etag"`         // ETag
    ContentType  string    `json:"contentType"`  // 内容类型
}

错误处理

SDK 提供了详细的错误信息：

result, err := client.UploadFile(req)
if err != nil {
    if apiErr, ok := err.(*lingstorage.APIError); ok {
        fmt.Printf("API 错误: %s (状态码: %d)\n", apiErr.Message, apiErr.StatusCode)
    } else {
        fmt.Printf("其他错误: %s\n", err.Error())
    }
}

Examples

查看 examples/ 目录获取更多使用示例：

• 基本上传
• 批量上传
• 图片处理
• 进度监控
• 文件管理 - 新增

测试

# 运行所有测试
go test ./...

# 运行测试并显示覆盖率
go test -cover ./...

# 生成测试报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

更新日志

v1.1.0 (最新)

• ✨ 新增文件删除功能
• ✨ 新增文件信息获取功能
• ✨ 新增文件URL获取功能
• ✨ 新增文件复制和移动功能
• ✨ 新增存储桶管理功能（创建、删除、列举）
• ✨ 新增文件列举功能
• ✨ 新增存储桶域名获取功能
• ✨ 新增存储桶权限设置功能
• 🔧 优化错误处理和重试机制
• 📚 完善文档和示例

v1.0.0

• 🎉 初始版本
• ✨ 文件上传功能
• ✨ 图片压缩和水印支持
• ✨ 批量上传功能
• ✨ 进度回调支持

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

Documentation

Index

• func CreateProgressBar(percentage, width int) string
• func FormatBytes(bytes int64) string
• func FormatDuration(d time.Duration) string
• type APIError
  • func (e *APIError) Error() string
• type BatchUploadRequest
• type BatchUploadResult
• type Client
  • func NewClient(config *Config) *Client
  • func (c *Client) BatchUpload(req *BatchUploadRequest) (*BatchUploadResult, error)
  • func (c *Client) CopyFile(req *CopyFileRequest) error
  • func (c *Client) CreateBucket(req *CreateBucketRequest) error
  • func (c *Client) DeleteBucket(bucketName string) error
  • func (c *Client) DeleteFile(bucket, key string) error
  • func (c *Client) GetBucketDomains(bucketName string) ([]string, error)
  • func (c *Client) GetFileInfo(bucket, key string) (*FileInfo, error)
  • func (c *Client) GetFileURL(bucket, key string, expires time.Duration) (string, error)
  • func (c *Client) ListBuckets(tagCondition string, shared bool) ([]string, error)
  • func (c *Client) ListFiles(req *ListFilesRequest) (*ListFilesResult, error)
  • func (c *Client) MoveFile(req *MoveFileRequest) error
  • func (c *Client) Ping() error
  • func (c *Client) SetBucketPrivate(req *SetBucketPrivateRequest) error
  • func (c *Client) UploadBytes(req *UploadBytesRequest) (*UploadResult, error)
  • func (c *Client) UploadFile(req *UploadRequest) (*UploadResult, error)
  • func (c *Client) UploadFromReader(req *UploadFromReaderRequest) (*UploadResult, error)
• type Config
• type CopyFileRequest
• type CreateBucketRequest
• type FileInfo
• type ListFilesRequest
• type ListFilesResult
• type MoveFileRequest
• type ProgressMonitor
  • func NewProgressMonitor() *ProgressMonitor
  • func (pm *ProgressMonitor) GetTotalDuration() time.Duration
  • func (pm *ProgressMonitor) OnProgress(uploaded, total int64)
• type SetBucketPrivateRequest
• type UploadBytesRequest
• type UploadError
• type UploadFromReaderRequest
• type UploadRequest
• type UploadResult

Functions

func CreateProgressBar

func CreateProgressBar(percentage, width int) string

CreateProgressBar 创建进度条

func FormatBytes

func FormatBytes(bytes int64) string

FormatBytes formats byte counts

func FormatDuration

func FormatDuration(d time.Duration) string

Types

type APIError

type APIError struct {
	StatusCode int    `json:"statusCode"`
	Message    string `json:"message"`
	Details    string `json:"details"`
}

APIError API Error

func (*APIError) Error

func (e *APIError) Error() string

type BatchUploadRequest

type BatchUploadRequest struct {
	Files             []string                                   // file list
	Bucket            string                                     // bucket name
	KeyPrefix         string                                     // key prefix
	AllowedTypes      []string                                   // all types
	Compress          bool                                       // if compress file
	Quality           int                                        // quality 1-100 - default 100
	Watermark         bool                                       // if watermark
	WatermarkText     string                                     // watermark text
	WatermarkPosition string                                     // watermark position
	OnProgress        func(completed, total int, current string) // batch upload progress callback
	OnFileProgress    func(uploaded, total int64)                // signal file upload progress
}

BatchUploadRequest batch upload request

type BatchUploadResult

type BatchUploadResult struct {
	Success []UploadResult `json:"success"`
	Failed  []UploadError  `json:"failed"`
	Total   int            `json:"total"`
}

BatchUploadResult batch upload result

type Client

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

Client LingStorage SDK Client

func NewClient

func NewClient(config *Config) *Client

NewClient create new lingStorage client

func (*Client) BatchUpload

func (c *Client) BatchUpload(req *BatchUploadRequest) (*BatchUploadResult, error)

BatchUpload batch upload files

func (*Client) CopyFile

func (c *Client) CopyFile(req *CopyFileRequest) error

CopyFile 复制文件

func (*Client) CreateBucket

func (c *Client) CreateBucket(req *CreateBucketRequest) error

CreateBucket 创建存储桶

func (*Client) DeleteBucket

func (c *Client) DeleteBucket(bucketName string) error

DeleteBucket 删除存储桶

func (*Client) DeleteFile

func (c *Client) DeleteFile(bucket, key string) error

DeleteFile 删除文件

func (*Client) GetBucketDomains

func (c *Client) GetBucketDomains(bucketName string) ([]string, error)

GetBucketDomains 获取存储桶域名

func (*Client) GetFileInfo

func (c *Client) GetFileInfo(bucket, key string) (*FileInfo, error)

GetFileInfo 获取文件信息

func (*Client) GetFileURL

func (c *Client) GetFileURL(bucket, key string, expires time.Duration) (string, error)

GetFileURL 获取文件访问URL

func (*Client) ListBuckets

func (c *Client) ListBuckets(tagCondition string, shared bool) ([]string, error)

ListBuckets 列举存储桶

func (*Client) ListFiles

func (c *Client) ListFiles(req *ListFilesRequest) (*ListFilesResult, error)

ListFiles 列举文件

func (*Client) MoveFile

func (c *Client) MoveFile(req *MoveFileRequest) error

MoveFile 移动文件

func (*Client) Ping

func (c *Client) Ping() error

Ping check server if is alive

func (*Client) SetBucketPrivate

func (c *Client) SetBucketPrivate(req *SetBucketPrivateRequest) error

SetBucketPrivate 设置存储桶权限

func (*Client) UploadBytes

func (c *Client) UploadBytes(req *UploadBytesRequest) (*UploadResult, error)

UploadBytes upload file from bytes

func (*Client) UploadFile

func (c *Client) UploadFile(req *UploadRequest) (*UploadResult, error)

UploadFile upload single files

func (*Client) UploadFromReader

func (c *Client) UploadFromReader(req *UploadFromReaderRequest) (*UploadResult, error)

UploadFromReader upload from io.Reader

type Config

type Config struct {
	BaseURL    string        // LingStorage server address
	APIKey     string        // API Key
	APISecret  string        // API Secret
	Timeout    time.Duration // Request Timeout
	RetryCount int           // retry times
	UserAgent  string        // user agent
}

Config LingStorage client config

type CopyFileRequest

type CopyFileRequest struct {
	SrcBucket  string `json:"srcBucket"`
	SrcKey     string `json:"srcKey"`
	DestBucket string `json:"destBucket"`
	DestKey    string `json:"destKey"`
}

CopyFileRequest 复制文件请求

type CreateBucketRequest

type CreateBucketRequest struct {
	BucketName string `json:"bucketName"`
	Region     string `json:"region"`
}

CreateBucketRequest 创建存储桶请求

type FileInfo

type FileInfo struct {
	Key          string    `json:"key"`
	Size         int64     `json:"size"`
	LastModified time.Time `json:"lastModified"`
	ETag         string    `json:"etag"`
	ContentType  string    `json:"contentType"`
}

FileInfo 文件信息

type ListFilesRequest

type ListFilesRequest struct {
	Bucket    string `json:"bucket"`
	Prefix    string `json:"prefix"`
	Marker    string `json:"marker"`
	Delimiter string `json:"delimiter"`
	Limit     int    `json:"limit"`
}

ListFilesRequest 列举文件请求

type ListFilesResult

type ListFilesResult struct {
	Files       []FileInfo `json:"files"`
	Directories []string   `json:"directories"`
	NextMarker  string     `json:"nextMarker"`
	IsTruncated bool       `json:"isTruncated"`
}

ListFilesResult 列举文件结果

type MoveFileRequest

type MoveFileRequest struct {
	SrcBucket  string `json:"srcBucket"`
	SrcKey     string `json:"srcKey"`
	DestBucket string `json:"destBucket"`
	DestKey    string `json:"destKey"`
}

MoveFileRequest 移动文件请求

type ProgressMonitor

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

func NewProgressMonitor

func NewProgressMonitor() *ProgressMonitor

func (*ProgressMonitor) GetTotalDuration

func (pm *ProgressMonitor) GetTotalDuration() time.Duration

func (*ProgressMonitor) OnProgress

func (pm *ProgressMonitor) OnProgress(uploaded, total int64)

type SetBucketPrivateRequest

type SetBucketPrivateRequest struct {
	BucketName string `json:"bucketName"`
	IsPrivate  bool   `json:"isPrivate"`
}

SetBucketPrivateRequest 设置存储桶权限请求

type UploadBytesRequest

type UploadBytesRequest struct {
	Data              []byte                      // file data
	Filename          string                      // file name
	Bucket            string                      // bucket name
	Key               string                      // file key
	AllowedTypes      []string                    // all types
	Compress          bool                        // if compress file
	Quality           int                         // quality 1-100 - default 100
	Watermark         bool                        // if watermark
	WatermarkText     string                      // watermark text
	WatermarkPosition string                      // watermark position
	OnProgress        func(uploaded, total int64) // upload progress callback
}

UploadBytesRequest upload request from bytes

type UploadError

type UploadError struct {
	File  string `json:"file"`
	Error string `json:"error"`
}

UploadError upload error

type UploadFromReaderRequest

type UploadFromReaderRequest struct {
	Reader            io.Reader
	Filename          string
	Size              int64
	Bucket            string
	Key               string
	AllowedTypes      []string
	Compress          bool
	Quality           int
	Watermark         bool
	WatermarkText     string
	WatermarkPosition string
	OnProgress        func(uploaded, total int64)
}

UploadFromReaderRequest read from io.Reader

type UploadRequest

type UploadRequest struct {
	FilePath          string                      // file path
	Bucket            string                      // bucket name
	Key               string                      // file key name
	AllowedTypes      []string                    // all file types
	Compress          bool                        // if compress file
	Quality           int                         // quality 1-100 - default 100
	Watermark         bool                        // if watermark
	WatermarkText     string                      // watermark text
	WatermarkPosition string                      // watermark position
	OnProgress        func(uploaded, total int64) // upload progress callback
}

UploadRequest upload request

type UploadResult

type UploadResult struct {
	Key          string `json:"key"`
	Bucket       string `json:"bucket"`
	Filename     string `json:"filename"`
	Size         int64  `json:"size"`
	OriginalSize int64  `json:"originalSize"`
	Compressed   bool   `json:"compressed"`
	Watermarked  bool   `json:"watermarked"`
	URL          string `json:"url"`
}

UploadResult upload result