Documentation
¶
Overview ¶
Package storage 提供强大的通用文件服务工具库
设计目标 ¶
- 提供统一的文件操作接口,屏蔽底层实现细节
- 集成多个主流开源库,提供丰富的文件处理能力
- 支持多种文件系统类型(OS、内存、只读等)
- 提供文件监听、复制、MIME检测、Excel处理、图片处理等功能
集成的开源库 ¶
- github.com/spf13/afero - 抽象文件系统
- github.com/fsnotify/fsnotify - 文件监听
- github.com/otiai10/copy - 高性能文件复制
- github.com/gabriel-vasile/mimetype - MIME类型检测
- github.com/xuri/excelize/v2 - Excel文件处理
- github.com/disintegration/imaging - 图片处理
使用示例 ¶
基础文件操作:
cfg := &storage.Config{
FSType: storage.FSTypeOS,
BasePath: "./data",
}
fs, err := storage.New(cfg)
if err != nil {
log.Fatal(err)
}
defer fs.Close()
// 读写文件
err = fs.WriteFile("test.txt", []byte("hello"), 0644)
data, err := fs.ReadFile("test.txt")
文件复制:
// 复制单个文件
err = fs.Copy("source.txt", "dest.txt")
// 复制目录
err = fs.CopyDir("./source_dir", "./dest_dir",
storage.WithPreserveTimes(true))
MIME检测:
mimeType, err := fs.DetectMIME("image.jpg")
fmt.Println(mimeType) // "image/jpeg"
文件监听:
err = fs.Watch("./watch_dir", func(event storage.WatchEvent) {
fmt.Printf("File %s: %s\n", event.Op, event.Path)
})
defer fs.StopWatch("./watch_dir")
Excel处理:
// 读取Excel
rows, err := fs.ReadExcelSheet("data.xlsx", "Sheet1")
// 创建Excel
file := fs.CreateExcel()
file.SetCellValue("Sheet1", "A1", "Hello")
err = fs.SaveExcel(file, "output.xlsx")
图片处理:
// 调整图片大小
err = fs.ResizeImage("input.jpg", "output.jpg", 800, 600, imaging.JPEG)
// 裁剪图片
rect := image.Rect(0, 0, 200, 200)
err = fs.CropImage("input.jpg", "cropped.jpg", rect, imaging.PNG)
接口设计 ¶
- Storage: 主接口,提供所有文件操作方法
- WatchHandler: 文件监听事件处理函数
- CopyOption: 文件复制选项接口
线程安全 ¶
所有方法都是并发安全的,使用 sync.RWMutex 保护内部状态。
Index ¶
Constants ¶
View Source
const ( // DefaultBasePath 默认基础路径 DefaultBasePath = "." // DefaultFSType 默认文件系统类型 DefaultFSType = FSTypeOS )
默认配置值
View Source
const ( // WatchEventCreate 文件创建事件 WatchEventCreate = "CREATE" // WatchEventWrite 文件写入事件 WatchEventWrite = "WRITE" // WatchEventRemove 文件删除事件 WatchEventRemove = "REMOVE" // WatchEventRename 文件重命名事件 WatchEventRename = "RENAME" // WatchEventChmod 文件权限变更事件 WatchEventChmod = "CHMOD" )
文件监听事件类型
Variables ¶
View Source
var ( // ErrInvalidConfig 无效配置错误 ErrInvalidConfig = errors.New("Storage: invalid configuration") // ErrPathNotFound 路径不存在错误 ErrPathNotFound = errors.New("Storage: path not found") // ErrNotDirectory 非目录错误 ErrNotDirectory = errors.New("Storage: not a directory") // ErrNotFile 非文件错误 ErrNotFile = errors.New("Storage: not a file") // ErrWatcherNotFound 监听器不存在错误 ErrWatcherNotFound = errors.New("Storage: watcher not found") // ErrInvalidFSType 无效的文件系统类型 ErrInvalidFSType = errors.New("Storage: invalid filesystem type") // ErrWatcherAlreadyExists 监听器已存在错误 ErrWatcherAlreadyExists = errors.New("Storage: watcher already exists for this path") )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// FSType 文件系统类型 (os, memory, readonly, basepath)
FSType FSType `mapstructure:"fs_type"`
// BasePath 基础路径,用于 basepath 文件系统类型
BasePath string `mapstructure:"base_path"`
// EnableWatch 是否启用文件监听功能
EnableWatch bool `mapstructure:"enable_watch"`
// WatchBufferSize 文件监听事件缓冲区大小
WatchBufferSize int `mapstructure:"watch_buffer_size"`
}
Config 保存文件服务配置
type CopyOption ¶
type CopyOption interface {
// contains filtered or unexported methods
}
CopyOption 文件复制选项接口
type Storage ¶
type Storage interface {
// FileSystem 返回底层的 afero 文件系统实例
// 用于执行 afero 提供的高级操作
FileSystem() afero.Fs
// ReadFile 读取文件内容
// 参数:
// path: 文件路径
// 返回:
// []byte: 文件内容
// error: 读取失败时的错误
ReadFile(path string) ([]byte, error)
// WriteFile 写入文件内容
// 参数:
// path: 文件路径
// data: 要写入的数据
// perm: 文件权限
// 返回:
// error: 写入失败时的错误
WriteFile(path string, data []byte, perm os.FileMode) error
// Remove 删除文件或空目录
// 参数:
// path: 路径
// 返回:
// error: 删除失败时的错误
Remove(path string) error
// RemoveAll 递归删除目录及其内容
// 参数:
// path: 目录路径
// 返回:
// error: 删除失败时的错误
RemoveAll(path string) error
// Exists 检查路径是否存在
// 参数:
// path: 路径
// 返回:
// bool: 是否存在
// error: 检查失败时的错误
Exists(path string) (bool, error)
// MkdirAll 递归创建目录
// 参数:
// path: 目录路径
// perm: 目录权限
// 返回:
// error: 创建失败时的错误
MkdirAll(path string, perm os.FileMode) error
// IsDir 判断路径是否为目录
// 参数:
// path: 路径
// 返回:
// bool: 是否为目录
// error: 检查失败时的错误
IsDir(path string) (bool, error)
// IsFile 判断路径是否为文件
// 参数:
// path: 路径
// 返回:
// bool: 是否为文件
// error: 检查失败时的错误
IsFile(path string) (bool, error)
// FileSize 获取文件大小
// 参数:
// path: 文件路径
// 返回:
// int64: 文件大小(字节)
// error: 获取失败时的错误
FileSize(path string) (int64, error)
// ListDir 列出目录内容
// 参数:
// path: 目录路径
// 返回:
// []os.FileInfo: 文件信息列表
// error: 列出失败时的错误
ListDir(path string) ([]os.FileInfo, error)
// Copy 复制单个文件
// 参数:
// src: 源文件路径
// dst: 目标文件路径
// opts: 复制选项
// 返回:
// error: 复制失败时的错误
Copy(src, dst string, opts ...CopyOption) error
// CopyDir 递归复制目录
// 参数:
// src: 源目录路径
// dst: 目标目录路径
// opts: 复制选项
// 返回:
// error: 复制失败时的错误
CopyDir(src, dst string, opts ...CopyOption) error
// DetectMIME 从文件路径检测MIME类型
// 参数:
// path: 文件路径
// 返回:
// string: MIME类型 (如 "image/jpeg")
// error: 检测失败时的错误
DetectMIME(path string) (string, error)
// DetectMIMEFromBytes 从字节数据检测MIME类型
// 参数:
// data: 文件数据
// 返回:
// string: MIME类型
// error: 检测失败时的错误
DetectMIMEFromBytes(data []byte) (string, error)
// Watch 监听文件或目录的变化
// 参数:
// path: 要监听的路径
// handler: 事件处理函数
// 返回:
// error: 监听失败时的错误
// 注意:
// - 如果路径已被监听,返回 ErrWatcherAlreadyExists
// - handler 在独立的 goroutine 中执行
Watch(path string, handler WatchHandler) error
// StopWatch 停止监听指定路径
// 参数:
// path: 路径
// 返回:
// error: 停止失败时的错误(如路径未被监听)
StopWatch(path string) error
// StopAllWatch 停止所有监听
StopAllWatch()
// OpenExcel 打开 Excel 文件
// 参数:
// path: Excel 文件路径
// 返回:
// *excelize.File: Excel 文件对象
// error: 打开失败时的错误
OpenExcel(path string) (*excelize.File, error)
// CreateExcel 创建新的 Excel 文件
// 返回:
// *excelize.File: Excel 文件对象
CreateExcel() *excelize.File
// SaveExcel 保存 Excel 文件
// 参数:
// file: Excel 文件对象
// path: 保存路径
// 返回:
// error: 保存失败时的错误
SaveExcel(file *excelize.File, path string) error
// ReadExcelSheet 读取 Excel 工作表数据
// 参数:
// path: Excel 文件路径
// sheet: 工作表名称
// 返回:
// [][]string: 二维字符串数组(行x列)
// error: 读取失败时的错误
ReadExcelSheet(path, sheet string) ([][]string, error)
// OpenImage 打开图片文件
// 参数:
// path: 图片文件路径
// 返回:
// image.Image: 图片对象
// error: 打开失败时的错误
OpenImage(path string) (image.Image, error)
// SaveImage 保存图片文件
// 参数:
// img: 图片对象
// path: 保存路径
// format: 图片格式 (如 imaging.JPEG, imaging.PNG)
// 返回:
// error: 保存失败时的错误
SaveImage(img image.Image, path string, format imaging.Format) error
// ResizeImage 调整图片大小
// 参数:
// src: 源图片路径
// dst: 目标图片路径
// width: 目标宽度 (0表示按比例)
// height: 目标高度 (0表示按比例)
// format: 输出格式
// 返回:
// error: 处理失败时的错误
ResizeImage(src, dst string, width, height int, format imaging.Format) error
// CropImage 裁剪图片
// 参数:
// src: 源图片路径
// dst: 目标图片路径
// rect: 裁剪区域
// format: 输出格式
// 返回:
// error: 处理失败时的错误
CropImage(src, dst string, rect image.Rectangle, format imaging.Format) error
// Close 关闭文件服务,释放资源
// 返回:
// error: 关闭失败时的错误
Close() error
// Reload 重新加载配置
// 参数:
// ctx: 上下文
// config: 新配置
// 返回:
// error: 重载失败时的错误
Reload(ctx context.Context, config *Config) error
}
Storage 定义文件服务的接口 提供统一的文件操作API,集成多个开源库提供强大的文件处理能力
设计目标:
- 抽象文件系统操作,支持多种文件系统类型
- 集成文件监听、复制、MIME检测等功能
- 支持 Excel 和图片文件的专业处理
- 提供统一、易用的接口
使用示例:
cfg := &Storage.Config{
FSType: Storage.FSTypeOS,
BasePath: "./data",
}
fs, err := Storage.New(cfg)
if err != nil {
log.Fatal(err)
}
defer fs.Close()
// 读写文件
err = fs.WriteFile("test.txt", []byte("hello"), 0644)
data, err := fs.ReadFile("test.txt")
type SymlinkAction ¶
type SymlinkAction int
SymlinkAction 符号链接处理动作
const ( // SymlinkShallow 浅复制符号链接 SymlinkShallow SymlinkAction = iota // SymlinkDeep 深复制符号链接指向的内容 SymlinkDeep // SymlinkSkip 跳过符号链接 SymlinkSkip )
Click to show internal directories.
Click to hide internal directories.