必须流式处理大文件哈希以避免OOM，禁用Gin自动解析表单，用mime/multipart.Reader定位file字段Part.Body，直接接入hash.Hash计算，避免SaveUploadedFile等额外I/O。
大文件直接读内存会OOM，必须流式处理
Go 的 gin.Context 默认把整个请求体加载进内存，上传几百 MB 甚至 GB 级文件时，ctx.Request.Body 一旦被完整读取（比如调用 ctx.ShouldBindJSON() 或直接 io.ReadAll()），立刻触发内存暴涨甚至 OOM。Gin 本身不提供“跳过解析、直通原始 Body”的开关，所以不能依赖中间件自动解包 —— 必须手动接管 ctx.Request.Body，并用 io.Copy 流式送入哈希器。
- 禁止调用
ctx.Request.MultipartForm()或ctx.FormFile()，它们内部会把文件全载入内存或临时磁盘，且无法控制哈希计算时机 - 上传接口必须设为
POST /hash，Content-Type 为multipart/form-data，但只取其中单个file字段，其余字段忽略 - 用
mime/multipart.Reader解析 boundary，定位到目标 part 后，直接将其Part.Body接入hash.Hash（如sha256.New()）
正确解析 multipart 文件 part 并流式哈希
很多人用 ctx.SaveUploadedFile() 先存盘再算 hash，多一次磁盘 I/O，还引入临时文件清理问题。其实 multipart.Reader 提供了无缓冲的流式访问能力 —— 关键是别让 Gin 自动解析表单，要禁用它：
- 在路由注册前加
gin.SetMode(gin.ReleaseMode)（非必需，但避免 debug 日志干扰） - 接口 handler 开头立即调用
ctx.Request.ParseMultipartForm(32 —— 这里参数是 maxMemory，设为 0 或太小会导致全部落盘；建议设为 32MB，足够解析 headers，又不至于吃光内存 - 然后用
reader, err := ctx.Request.MultipartReader()获取 reader，循环reader.NextPart()，比对part.Header.Get("Content-Disposition")是否含name="file" - 找到后，用
io.Copy(hasher, part)，无需 buffer，底层就是 syscall.read + write，吞吐取决于磁盘/网络带宽
hasher := sha256.New()
for {
part, err := reader.NextPart()
if err == io.EOF {
break
}
if err != nil {
return err
}
if strings.Contains(part.Header.Get("Content-Disposition"), `name="file"`) {
if _, err := io.Copy(hasher, part); err != nil {
return err
}
}
}
HTTP 响应要防超时，且返回值格式需明确
1GB 文件按 50MB/s 磁盘速度算，哈希要 20 秒 —— 默认 Gin 的 http.Server.ReadTimeout 和 Nginx 的 proxy_read_timeout 都可能中断连接。这不是代码 bug，而是配置缺失。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- Gin 启动时必须显式设置
http.Server实例的ReadTimeout和WriteTimeout（例如 300 * time.Second） - Nginx 反向代理需同步配
proxy_connect_timeout 300;、proxy_send_timeout 300;、proxy_read_timeout 300; - 响应 body 应为纯文本 JSON：
{"hash": "a1b2c3..."}，不要加多余空格或换行，避免某些客户端解析失败 - 别用
ctx.JSON(200, map[string]string{"hash": hex.EncodeToString(hasher.Sum(nil))})——Sum(nil)返回新 slice，没问题；但注意hex.EncodeToString是标准库函数，不是 Gin 自带
SHA256 vs MD5：选型要看校验目的
MD5 计算快 20%~30%，但已不安全，仅适合内部快速去重；SHA256 是当前通用底线。Golang 标准库的 crypto/sha256 在 AMD64 上有硬件加速支持，实际性能差距没想象中大。
立即学习“go语言免费学习笔记（深入）”；
- 若业务要求抗碰撞（如分发包签名校验），必须用
sha256.New()，别碰md5.New() - 若只是检测传输错误（如 CDN 回源一致性），
crc64.New(crc64.ISO)更快，且碰撞概率对单次传输可接受 - 别自己拼接
file.Size + file.Name + hash当“唯一值”—— 文件名可伪造，大小易冲突，真正唯一只能靠内容哈希
流式哈希真正难的不是代码，是确认整个链路（客户端上传 → 负载均衡 → Web Server → Go runtime）都支持长连接和大包，任何一个环节默认超时或缓冲区设得太小，都会让你以为 hash 逻辑错了。
