Files

T

4566704 455360bff0 feat: 支持 targetDir 指定上传目标目录（网盘式），固定路径模式不变

- 改动：init/check 接受可选 targetDir（相对 CloudDir，SanitizeDir 校验），merge 物理落盘 CloudDir/<targetDir>/
- 秒传跨目录 copy-on-hit：库把旧物理文件复制进目标目录，OnInstantHit 携带新路径；源缺失回退正常上传
- 断点续传按目录隔离：同 MD5 在途任务目录不同则另起新任务
- TaskInfo 新增 TargetDir（宿主须持久化）；Repository 12 方法接口零变更，向后兼容 v1.0.x
- 新增 dir.go（SanitizeDir/路径拼装反解/copyFile）与 service_test.go（10 个用例：双模式秒传/续传隔离/merge 回归）
- 原因：上传位置原本固定在 CloudDir 根，宿主无法实现网盘式选目录上传

2026-09-26 08:47:55 +08:00

3.7 KiB

Raw Permalink Blame History

fileupload

通用大文件分片上传 Go/Gin 服务端核心（独立库，原 zogo/fileupload 子包）。六接口（init/chunk/merge/check/task/abort）+ 分片幂等 + 断点续传 + .part 原子改名 + 合并整文件 MD5 校验 + 秒传 + 目标目录（targetDir）。不依赖宿主的响应封装、ORM 或业务表——存储走 Repository 接口注入，业务衔接走 Options 回调。

用法

import "git.zeroonesoft.cn/golib/fileupload"

opts := fileupload.Options{
    ChunkRoot:      "./data/upload-chunks",        // 分片临时目录（建议在静态根之外）
    CloudDir:       "./data/uploads/cloud",        // 合并产物目录（targetDir 的根）
    WebPathPrefix:  "cloud",                       // storagePath 的 Web 前缀（须与 CloudDir 相对静态根的子目录一致）
    URLPrefix:      "/uploads",                    // fileUrl = URLPrefix + "/" + storagePath
    MaxTotalSizeMB: 2048,                          // 0=不限
    OnMerged: func(t fileupload.TaskInfo) error {
        // 合并成功：宿主写自己的业务表（如云盘记录行）；失败则 merge 整体失败
        return nil
    },
    OnInstantHit: func(t fileupload.TaskInfo) error {
        // 秒传命中：宿主确保业务侧可见行（可空回调）；跨目录命中时携带新 StoragePath/TargetDir
        return nil
    },
    Envelope: func(c *gin.Context, resp any, err error) {
        // 宿主自己的响应封装，如 httpx.HandleResult(c, resp, err)
    },
}
_ = fileupload.Mount(api.Group("/upload"), opts, myRepo,
    fileupload.WithIdentity(func(c *gin.Context) (string, int64) {
        return c.GetString("UserName"), c.GetInt64("TenantId")
    }))

Repository（12 个方法）由宿主按自己的表结构实现；软删/硬删自定，但删除后查询必须不可见。鉴权由宿主路由组的 JWT 中间件统一负责，本库不感知。

目标目录（targetDir）

上传位置不再固定：init 请求可带 targetDir（相对 CloudDir，/ 分隔，空=根目录），合并产物物理落盘 CloudDir/<targetDir>/<产物名>，storagePath = WebPathPrefix + "/" + targetDir + "/" + 产物名。 /check 亦接受可选 query targetDir。宿主可用 fileupload.SanitizeDir 复用同款目录校验（拒绝 .././空段/绝对路径/Windows 非法字符，限长 500、限深 16）。

三档宿主形态（服务端无模式概念，字段缺省即固定路径模式，v1.0.x 行为不变）：

形态	客户端行为	服务端表现
固定路径（默认）	不传 targetDir	与 v1.0.x 完全一致，落 CloudDir 根
固定子目录	每次上传带同一 targetDir	固定落该子目录
网盘式自选	用户选目录后随 init 传入	落所选子目录，`MkdirAll` 自动创建

语义要点：

秒传 copy-on-hit：秒传按全局 MD5 命中。同目录（含根目录）命中直接复用旧文件；跨目录命中由库把旧物理文件复制进目标目录，OnInstantHit 携带新 StoragePath/TargetDir；旧物理文件缺失或复制失败自动回退为正常分片上传。
断点续传按目录隔离：同 MD5 在途任务目标目录不同时不复用，另起新任务。
宿主须持久化 TaskInfo.TargetDir（建议 upload_task 加 target_dir varchar(500)）：不持久化时目录上传的断点续传会退化为每次新建任务，其余功能不受影响。

版本

v1.1.0 新增 targetDir：init/check 支持目标目录，跨目录秒传 copy-on-hit，续传按目录隔离；Repository 接口零变更
v1.0.0 首个独立 tag：自 zogo/fileupload v0.3.2 抽出
v0.1.0 初版：自 FileUpload 项目 restful/upload 模块抽出

3.7 KiB Raw Permalink Blame History Unescape Escape

fileupload

用法

目标目录（targetDir）

版本

3.7 KiB

Raw Permalink Blame History