Iris 路由中接收 multipart/form-data 文件上传需显式调用 ctx.FormFile() 或 ctx.UploadFormFiles() 解析;必须设置 enctype="multipart/form-data" 且 input name 与参数一致;超大文件需提前调用 app.Adapt(iris.LimitRequestBodySize(N)) 解除 4MB 默认限制,并在 handler 内流式处理以避免 OOM 和 fd 泄露。

如何在 Iris 路由中接收 multipart/form-data 文件上传
Iris 默认支持标准 multipart/form-data 上传,但必须显式调用 ctx.FormFile() 或 ctx.UploadFormFiles() 才能解析——它不会自动解包文件到内存或磁盘。不手动调用,ctx.Request().MultipartReader() 会被跳过,后续再读就失效。
常见错误现象:FormFile: no such file 或空 *multipart.FileHeader,本质是没触发解析,或前端 缺少 name 属性。
- 确保 HTML 表单含
enctype="multipart/form-data",且的name与ctx.FormFile("xxx")中的字符串完全一致 - 路由 handler 必须是同步执行的;若在 goroutine 中调用
FormFile,会因请求体已被释放而失败 - 单个文件上传用
ctx.FormFile("file");多文件用ctx.UploadFormFiles("./uploads")(自动创建目录并保存)
为什么上传大 Excel 文件会直接返回 413 错误
因为 Iris 默认限制请求体大小为 4MB,而带公式的 Excel 或嵌入图片的文件轻松超限。这不是路由或中间件能拦截的问题,HTTP 层在进入路由前就已拒绝请求。
错误信息:413 Request Entity Too Large
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
- 必须在
app.Run()前调用app.Adapt(iris.LimitRequestBodySize(N)),例如32 (32MB) - 不能在中间件里动态修改,也不能在
app.ConfigureHost()里设;该配置作用于整个 HTTP server 实例 - 注意:改完后仍需检查反向代理(如 Nginx)是否也设了
client_max_body_size,否则请求会在代理层就被截断
如何安全保存上传的 Excel 文件并避免阻塞
直接用 ctx.UploadFormFiles("./uploads") 看似方便,但它会把整个文件读进内存再写盘,对 >50MB 的 Excel 有 OOM 风险。生产环境应流式处理。
- 用
ctx.FormFile("data")获取*multipart.FileHeader,再调用fh.Open()得到io.ReadCloser - 立即传给
excelize.OpenReader()或encoding/csv.NewReader()流式解析,避免全量加载 - 保存时用
os.Create()+io.Copy(),而非fh.Save(),可控制缓冲区大小并及时 close - 务必 defer
rc.Close()和f.Close(),否则 fd 泄露会导致“too many open files”
上传路由要不要加中间件?哪些逻辑必须放在 handler 里
上传相关的校验和解析逻辑不能抽到中间件里。Iris 的中间件运行时机在路由匹配后、handler 执行前,但 ctx.FormFile() 依赖请求体未被消费,而中间件若调用了 ctx.PostValue() 或 ctx.Request().ParseMultipartForm(),会导致后续 handler 无法再读文件。
- 文件名白名单校验(如只允许
.xlsx)、大小预检(用fh.Size)、MIME 类型检查(fh.Header.Get("Content-Type"))可以放中间件 - 实际打开文件、解析内容、写入数据库等操作,必须在路由 handler 内完成
- 不要在中间件里调用任何会触发
ParseMultipartForm的方法,包括ctx.FormValues()、ctx.FormValue()(除非你确定不需要文件)
最容易被忽略的是:上传路由的超时设置。Excel 解析可能耗时数秒,而 Iris 默认的 WriteTimeout 是 30 秒,若解析卡在某张巨表上,连接会被静默关闭。建议在 ConfigureHost 中显式加大 WriteTimeout,并配合 context.WithTimeout 在 handler 内做更细粒度的控制。










