Iris框架需手动实现流式下载：用ctx.WriteStream配合io.Copy边读边写，必须显式设置Content-Type和Content-Disposition头，校验文件名防路径穿越，避免使用ctx.ServeFile处理动态内容，并配置写超时防止大文件传输中断。
Iris 框架本身不内置 downloadHandler 这类 Shiny 风格的声明式下载处理器，文件下载和流式传输必须手动构造响应，否则容易触发内存溢出或连接中断。
如何用 iris.Context.WriteStream 实现大文件流式下载
Iris 提供 ctx.WriteStream 方法，底层调用 http.ResponseWriter 的 Write，适合边读边写、避免全量加载到内存。但注意它不自动设置 Content-Length 或 Content-Disposition，漏掉会导致浏览器无法识别为可下载文件。
- 必须手动调用
ctx.Header("Content-Type", "application/octet-stream")，PDF 用"application/pdf"，CSV 用"text/csv" - 必须设置
ctx.Header("Content-Disposition", "attachment; filename=\"report.pdf\"")，否则浏览器可能尝试内嵌打开 - 推荐搭配
io.Copy使用：传入一个io.Reader（如os.File或bytes.NewReader）和ctx.Response().Writer - 若文件路径来自用户输入，务必做白名单校验或路径规范化，防止
../目录穿越
app.Get("/download/{filename}", func(ctx iris.Context) {
filename := ctx.Params().Get("filename")
// 简单白名单：只允许字母、数字、下划线、点
if !regexp.MustCompile(`^[a-zA-Z0-9_.-]+$`).MatchString(filename) {
ctx.StatusCode(400)
ctx.WriteString("Invalid filename")
return
}
filepath := "./uploads/" + filename
f, err := os.Open(filepath)
if err != nil {
ctx.StatusCode(404)
return
}
defer f.Close()
ctx.Header("Content-Type", "application/octet-stream")
ctx.Header("Content-Disposition", "attachment; filename="+filename)
io.Copy(ctx.Response().Writer, f)
})
为什么不能直接用 ctx.ServeFile 处理动态生成文件
ctx.ServeFile 适合静态资源，它会调用 http.ServeFile，内部使用 http.ServeContent 做范围请求（Range）支持和 ETag 缓存。但如果你要动态生成 CSV、PDF 或 ZIP，ServeFile 无法对接内存中的字节流或临时文件句柄。
- 动态内容必须走
WriteStream或Write，自己控制写入时机 - 若用
ctx.ServeFile指向临时文件，需确保文件写完再调用，且注意并发时文件名冲突（比如多个用户同时导出，都写到temp.csv） - 临时文件未清理还会导致磁盘占满；而流式传输可完全绕过磁盘，直接从内存或数据库游标写入响应体
处理超大文件时的连接超时与缓冲区陷阱
Iris 默认复用 net/http 的底层连接，但不会自动禁用 HTTP/1.1 的 keep-alive 或调整写超时。当传输 GB 级文件时，客户端可能断连，服务端却还在写——最终 panic 报错 "write: broken pipe" 或 "i/o timeout"。
- 在
app.Run前显式配置服务器写超时：iris.Addr(":8080", iris.WithoutServerError(iris.ErrServerClosed), iris.WithWriteTimeout(30*time.Minute)) - 避免用
ctx.WriteString或ctx.JSON后再调用WriteStream—— 响应头已发送，再写会 panic - 若后端是慢存储（如 NFS、S3），建议加一层
bufio.NewWriterSize(ctx.Response().Writer, 1 提升吞吐，但注意Flush必须由你控制，Iris 不自动刷
真正难的不是“怎么写出数据”，而是“怎么在不阻塞主线程、不耗尽内存、不被中间代理截断”的前提下，把数据一帧一帧送出去。Iris 给你的是原始控制权，但也意味着所有边界条件都得自己兜底。
