服务端阅读 05月27日 15:17
Gin 框架中如何实现文件的上传与下载?
在实际开发中，文件上传下载是 Web 服务最常见的功能之一——用户头像、报表导出、附件发送都离不开它。Gin 框架在这方面提供了简洁的 API，但也藏着一些容易踩的坑。下面从上传到下载，把关键实现和注意事项讲清楚。单文件上传Gin 封装了 c.FormFile 和 c.SaveUploadedFile，单文件上传只需要几行代码：func uploadFile(c *gin.Context) { file, err := c.FormFile("file") if err != nil { c.JSON(400, gin.H{"error": "获取上传文件失败"}) return } dst := "./uploads/" + file.Filename if err := c.SaveUploadedFile(file, dst); err != nil { c.JSON(500, gin.H{"error": "文件保存失败"}) return } c.JSON(200, gin.H{ "message": "上传成功", "filename": file.Filename, "size": file.Size, })}路由注册时，记得给表单内存设个上限，避免大文件把内存吃光：router.MaxMultipartMemory = 8 << 20 // 8 MiBrouter.POST("/upload", uploadFile)这里有个细节容易忽略：MaxMultipartMemory 控制的是内存缓冲区大小，超过这个值的文件会自动写入临时目录，不会直接撑爆内存。多文件上传需要同时上传多个文件时，用 c.MultipartForm() 拿到整个表单：func uploadMultipleFiles(c *gin.Context) { form, err := c.MultipartForm() if err != nil { c.JSON(400, gin.H{"error": "解析表单失败"}) return } files := form.File["files"] var uploaded []string for _, file := range files { dst := "./uploads/" + file.Filename if err := c.SaveUploadedFile(file, dst); err != nil { c.JSON(500, gin.H{"error": "文件保存失败: " + file.Filename}) return } uploaded = append(uploaded, file.Filename) } c.JSON(200, gin.H{ "message": "全部上传成功", "files": uploaded, })}注意循环中一旦某个文件保存失败就立即返回，避免部分成功的模糊状态。如果你的场景需要"尽可能多成功"，可以改成收集错误列表，最后统一返回。文件大小与类型校验上传接口不做校验等于裸奔，最基本的两道关：大小和类型。大小限制可以用 http.MaxBytesReader 包一层：func uploadWithLimit(c *gin.Context) { c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 10<<20) // 10MB file, err := c.FormFile("file") if err != nil { c.JSON(400, gin.H{"error": "文件过大或读取失败"}) return } // 继续处理...}MaxBytesReader 的好处是超过限制会立即中断读取，不会等整个文件传完才拒绝。类型校验不能只看扩展名，要用 http.DetectContentType 读文件头判断真实 MIME 类型：func uploadWithValidation(c *gin.Context) { file, err := c.FormFile("file") if err != nil { c.JSON(400, gin.H{"error": "获取文件失败"}) return } opened, err := file.Open() if err != nil { c.JSON(500, gin.H{"error": "无法读取文件"}) return } defer opened.Close() buf := make([]byte, 512) opened.Read(buf) opened.Seek(0, io.SeekStart) // 重置读指针，后续 SaveUploadedFile 还能正常读 contentType := http.DetectContentType(buf) allowed := map[string]bool{ "image/jpeg": true, "image/png": true, "image/gif": true, } if !allowed[contentType] { c.JSON(400, gin.H{"error": "不支持的文件类型: " + contentType}) return } dst := "./uploads/" + file.Filename c.SaveUploadedFile(file, dst) c.JSON(200, gin.H{"message": "上传成功"})}Seek(0, io.SeekStart) 这步别漏了，不然 DetectContentType 消耗了前 512 字节后，SaveUploadedFile 存下来的文件头部会损坏。路径遍历防护上面代码直接用 file.Filename 拼路径，这在生产环境很危险——攻击者可以构造类似 ../../etc/passwd 的文件名，把文件写到任意位置。修复方法很简单：// 只取文件名部分，去掉目录前缀dst := "./uploads/" + filepath.Base(file.Filename)或者更进一步，用 UUID 生成全新文件名，彻底杜绝冲突和路径遍历：ext := filepath.Ext(file.Filename)newName := uuid.New().String() + extdst := "./uploads/" + newName简单文件下载Gin 提供了 c.File 和 c.FileAttachment，基本下载用它们就够了：// 直接返回文件，浏览器会按原文件名显示func downloadFile(c *gin.Context) { filename := c.Param("filename") filepath := "./uploads/" + filepath.Base(filename) // 同样要做路径清洗 c.File(filepath)}// 强制浏览器弹出下载框，并指定下载文件名func downloadWithCustomName(c *gin.Context) { filepath := "./uploads/report.pdf" c.FileAttachment(filepath, "月度报表.pdf")}流式下载大文件小文件直接 c.File 没问题，但遇到几百 MB 甚至上 GB 的文件，必须用流式传输，避免一次性加载到内存：func downloadStream(c *gin.Context) { filename := c.Param("filename") path := "./uploads/" + filepath.Base(filename) file, err := os.Open(path) if err != nil { c.JSON(404, gin.H{"error": "文件不存在"}) return } defer file.Close() info, _ := file.Stat() c.Header("Content-Disposition", "attachment; filename="+filename) c.Header("Content-Type", "application/octet-stream") c.Header("Content-Length", strconv.FormatInt(info.Size(), 10)) io.Copy(c.Writer, file)}io.Copy 会分块读取写入，内存占用可控。如果想要更精细的控制，也可以用 http.ServeContent，它还支持 Last-Modified 协商和 Range 请求。断点续传下载对于大文件下载场景（比如 App 更新包），断点续传能大幅提升用户体验。核心是处理 Range 请求头：func downloadWithResume(c *gin.Context) { filename := c.Param("filename") path := "./uploads/" + filepath.Base(filename) file, err := os.Open(path) if err != nil { c.JSON(404, gin.H{"error": "文件不存在"}) return } defer file.Close() info, _ := file.Stat() rangeHeader := c.GetHeader("Range") if rangeHeader != "" { // 解析 Range: bytes=start-end ranges := strings.Split(rangeHeader, "=")[1] parts := strings.Split(ranges, "-") start, _ := strconv.ParseInt(parts[0], 10, 64) file.Seek(start, 0) remaining := info.Size() - start c.Header("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, info.Size()-1, info.Size())) c.Header("Content-Length", strconv.FormatInt(remaining, 10)) c.Header("Accept-Ranges", "bytes") c.Status(http.StatusPartialContent) io.CopyN(c.Writer, file, remaining) return } c.Header("Accept-Ranges", "bytes") http.ServeContent(c.Writer, c.Request, filename, info.ModTime(), file)}这段代码只处理了单段 Range 的简单情况。生产环境如果需要完整支持多段 Range，建议直接用 http.ServeContent，它已经内置了完整的 Range 解析逻辑。生产环境的几个建议存储方案：本地文件系统只适合开发和测试。上了生产，文件应该存到对象存储（OSS、S3），数据库只保存文件地址。这样应用服务器无状态，扩容和迁移都更方便。并发控制：上传接口容易成为瓶颈。可以用令牌桶或信号量限制同时处理的上传数量，防止大并发把带宽和磁盘 IO 吃满。安全清单：始终用 filepath.Base() 清洗文件名，防止路径遍历校验文件真实 MIME 类型，不要信任扩展名上传目录不要有执行权限下载接口加鉴权，不要让任意用户能遍历文件性能优化：大文件用流式处理，别整个读到内存静态资源走 CDN，减少应用服务器压力下载时设置合理的 Content-Length，让浏览器能显示进度条考虑对文本类资源启用 gzip 压缩以上就是 Gin 框架中文件上传下载的核心实现和实战要点。从单文件到断点续传，从基本校验到生产加固，把这些环节都考虑到，你的文件服务才经得起真实流量的考验。