正确返回二进制流需手动控制响应：显式设 Content-Type、Content-Disposition 和 Content-Encoding；长度未知时省略 Content-Length 以启用 chunked；支持 Range 需解析并返回 206 状态及 Content-Range；用 io.CopyBuffer 流式透传，配合超时、限速与安全过滤。
Go 语言原生 http.ServeFile 和 http.ServeContent 都不适合直接用于「带权限校验、断点续传、大文件流式下载」的二进制流场景；真正可靠的做法是手动控制响应体写入 + 显式设置 header。
如何用 net/http 正确返回二进制流（不落地、不全加载）
核心是绕过中间缓存，直接从数据源（如数据库 BLOB、对象存储 SDK、加密解密管道）读取并写入 ResponseWriter。关键不是“返回文件”，而是“流式透传字节”。
- 必须显式调用
w.Header().Set("Content-Type", "application/octet-stream")，不能依赖http.DetectContentType—— 它只读前 512 字节，对加密或压缩流会误判 - 务必设置
Content-Disposition：例如w.Header().Set("Content-Disposition", `attachment; filename="report.pdf"`)，注意 filename 值需用双引号包裹，且非 ASCII 名称要 RFC 5987 编码 - 禁用 Gzip 压缩：在 handler 开头加
w.Header().Set("Content-Encoding", "identity")，否则某些反向代理（如 Nginx）可能二次压缩导致客户端解包失败 - 使用
io.CopyBuffer(w, reader)而非io.Copy，可指定缓冲区（如 64KB），避免小包频繁 syscall
gin.Context 中处理下载时的常见陷阱
gin 默认会自动写入 Content-Length，但流式场景下你往往不知道总长度（比如边解密边读取），此时强行设 Content-Length 会导致客户端卡住或截断。
- 若长度已知：调用
c.Writer.WriteHeader(http.StatusOK)后再设Content-Length，**不能**用c.Header("Content-Length", ...)—— gin 的 Header 是 lazy write，可能被后续c.Data()覆盖 - 若长度未知（典型如加密流、实时生成报表）：必须省略
Content-Length，并确保Transfer-Encoding: chunked自动生效（Go http server 默认支持），此时客户端只能靠 EOF 判断结束 - 不要用
c.Data(...)或c.File(...)：它们内部强制读取全部内容到内存或触发os.Open，破坏流式语义
支持断点续传（Range 请求）的最小可行实现
不是所有下载都需要 Range，但视频、大模型权重、离线包等场景必须支持。Go 标准库不自动处理，得自己解析 Range header 并切片 reader。
立即学习“go语言免费学习笔记（深入）”；
- 检查请求头：
range := c.Request.Header.Get("Range")，为空则走完整流逻辑 - 解析格式：
bytes=0-1023或bytes=500-，用http.ParseRange（注意它返回[]http.Range，只取第一个即可） - 关键：响应状态码必须是
http.StatusPartialContent (206)，且必须返回Content-Range，例如w.Header().Set("Content-Range", "bytes 500-1023/2048") - 底层 reader 必须支持
io.ReadSeeker（如os.File、bytes.NewReader），否则无法跳转偏移；若来源是 HTTP 流或加密管道，需先缓存到临时*os.File或用io.SectionReader包装
性能与安全边界必须手动加固
流式下载容易成为 DoS 入口：攻击者可发起大量长连接、小 range 请求，耗尽 goroutine 或 fd。
- 用
context.WithTimeout(c.Request.Context(), 30*time.Second)包裹整个读取流程，超时即断开 - 对非可信文件名做白名单过滤：
filepath.Base(filename)+ 正则^[a-zA-Z0-9._-]+\.[a-zA-Z0-9]{2,}$，防止路径遍历 - 限制最大单次响应体积（如 2GB）：
io.LimitReader(reader, 2*1024*1024*1024)，配合io.Copy自动截断 - 若后端是 S3 兼容存储，优先用
PresignedGetObject生成直链，把压力卸给对象存储，而不是用 Go 服务中转
最易被忽略的一点：HTTP/2 下的流控窗口和 WriteHeader 时机必须严格匹配。一旦在 WriteHeader 前往 ResponseWriter 写入任何字节，Go 会自动发送 200 状态并关闭流控协商能力 —— 这会导致大文件传输中途被 client 重置连接。
