Gin框架文件上传与下载功能实现：断点续传、大文件分片处理的核心代码

一、为什么需要文件上传下载的进阶功能

在现代Web开发中，文件上传下载是最基础的功能之一。但如果只是简单实现，用户上传大文件时可能会遇到网络中断、服务器超时等问题，导致体验极差。这时候，断点续传和分片处理就显得尤为重要。

断点续传允许用户在上传或下载过程中断后，从中断的位置继续传输，而不是重新开始。分片处理则是将大文件切割成小块，逐个上传或下载，既减轻了服务器压力，又提高了传输的可靠性。

Gin框架作为Golang生态中最受欢迎的Web框架之一，提供了简洁高效的API来实现这些功能。下面我们就来看看如何用Gin实现这些进阶功能。

二、Gin框架基础文件上传与下载

在深入断点续传和分片处理之前，我们先回顾一下Gin如何处理普通的文件上传和下载。

基础文件上传

package main

import (
	"github.com/gin-gonic/gin"
	"log"
	"net/http"
)

func main() {
	r := gin.Default()

	// 设置文件上传路由
	r.POST("/upload", func(c *gin.Context) {
		// 获取上传的文件
		file, err := c.FormFile("file")
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// 保存文件到指定路径
		if err := c.SaveUploadedFile(file, "./uploads/"+file.Filename); err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
			return
		}

		c.JSON(http.StatusOK, gin.H{"message": "文件上传成功", "filename": file.Filename})
	})

	log.Fatal(r.Run(":8080"))
}

基础文件下载

// 添加文件下载路由
r.GET("/download/:filename", func(c *gin.Context) {
	filename := c.Param("filename")
	// 设置响应头，告诉浏览器这是一个文件下载
	c.Header("Content-Disposition", "attachment; filename="+filename)
	c.Header("Content-Type", "application/octet-stream")
	// 返回文件内容
	c.File("./uploads/" + filename)
})

这两个例子展示了Gin处理文件上传和下载的最基本方式。但这种方式在处理大文件时会遇到性能瓶颈，接下来我们看看如何优化。

三、实现断点续传

断点续传的核心在于记录已传输的字节位置，并在中断后从中断点继续传输。HTTP协议本身支持通过Range头部实现这一功能。

服务端支持断点续传

// 支持断点续传的文件下载
r.GET("/download/resume/:filename", func(c *gin.Context) {
	filename := c.Param("filename")
	filePath := "./uploads/" + filename

	// 打开文件
	file, err := os.Open(filePath)
	if err != nil {
		c.JSON(http.StatusNotFound, gin.H{"error": "文件不存在"})
		return
	}
	defer file.Close()

	fileInfo, err := file.Stat()
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": "无法获取文件信息"})
		return
	}

	// 处理Range头部
	rangeHeader := c.GetHeader("Range")
	if rangeHeader != "" {
		// 解析Range头部，格式为"bytes=0-1023"
		parts := strings.Split(rangeHeader, "=")
		if len(parts) != 2 || parts[0] != "bytes" {
			c.JSON(http.StatusBadRequest, gin.H{"error": "无效的Range头部"})
			return
		}

		rangeStr := parts[1]
		ranges := strings.Split(rangeStr, "-")
		start, err := strconv.ParseInt(ranges[0], 10, 64)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": "无效的Range值"})
			return
		}

		var end int64
		if ranges[1] != "" {
			end, err = strconv.ParseInt(ranges[1], 10, 64)
			if err != nil {
				c.JSON(http.StatusBadRequest, gin.H{"error": "无效的Range值"})
				return
			}
		} else {
			end = fileInfo.Size() - 1
		}

		// 设置Content-Range头部
		c.Header("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, end, fileInfo.Size()))
		c.Status(http.StatusPartialContent)

		// 跳转到指定位置
		_, err = file.Seek(start, 0)
		if err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "文件读取失败"})
			return
		}

		// 返回部分内容
		io.CopyN(c.Writer, file, end-start+1)
		return
	}

	// 普通下载
	c.Header("Content-Disposition", "attachment; filename="+filename)
	c.Header("Content-Type", "application/octet-stream")
	http.ServeContent(c.Writer, c.Request, filename, fileInfo.ModTime(), file)
})

客户端实现断点续传

客户端需要记录已下载的字节数，并在请求时添加Range头部：

// 模拟客户端断点续传下载
func downloadWithResume(url, filename string) error {
	// 检查本地已下载的部分
	file, err := os.OpenFile(filename, os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		return err
	}
	defer file.Close()

	fileInfo, err := file.Stat()
	if err != nil {
		return err
	}

	start := fileInfo.Size()

	// 创建带Range头部的请求
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return err
	}
	req.Header.Set("Range", fmt.Sprintf("bytes=%d-", start))

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	// 如果是206 Partial Content，说明服务器支持断点续传
	if resp.StatusCode == http.StatusPartialContent {
		// 跳转到文件末尾继续写入
		_, err = file.Seek(0, io.SeekEnd)
		if err != nil {
			return err
		}
	}

	_, err = io.Copy(file, resp.Body)
	return err
}

四、大文件分片处理

对于超大文件（如几个GB的视频文件），直接上传可能会导致内存溢出或超时。分片处理将大文件切割成小块，逐个上传，最后在服务器端合并。

前端分片上传

前端可以使用File API将文件分片：

// 前端JavaScript示例（仅展示逻辑）
function uploadFileInChunks(file) {
  const chunkSize = 5 * 1024 * 1024; // 5MB每片
  const totalChunks = Math.ceil(file.size / chunkSize);
  
  for (let i = 0; i < totalChunks; i++) {
    const start = i * chunkSize;
    const end = Math.min(start + chunkSize, file.size);
    const chunk = file.slice(start, end);
    
    // 上传分片
    uploadChunk(chunk, i, totalChunks, file.name);
  }
}

服务端处理分片上传

// 处理分片上传
r.POST("/upload/chunk", func(c *gin.Context) {
	// 获取分片信息
	chunkNumber, err := strconv.Atoi(c.PostForm("chunkNumber"))
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的分片编号"})
		return
	}

	totalChunks, err := strconv.Atoi(c.PostForm("totalChunks"))
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的总分片数"})
		return
	}

	fileName := c.PostForm("fileName")
	if fileName == "" {
		c.JSON(http.StatusBadRequest, gin.H{"error": "文件名不能为空"})
		return
	}

	// 获取分片文件
	file, err := c.FormFile("chunk")
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	// 创建临时目录
	if err := os.MkdirAll("./uploads/temp", 0755); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": "无法创建临时目录"})
		return
	}

	// 保存分片
	chunkPath := fmt.Sprintf("./uploads/temp/%s_%d", fileName, chunkNumber)
	if err := c.SaveUploadedFile(file, chunkPath); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": "分片保存失败"})
		return
	}

	// 如果是最后一个分片，合并文件
	if chunkNumber == totalChunks-1 {
		if err := mergeChunks(fileName, totalChunks); err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "文件合并失败"})
			return
		}
		c.JSON(http.StatusOK, gin.H{"message": "文件上传完成"})
	} else {
		c.JSON(http.StatusOK, gin.H{"message": "分片上传成功"})
	}
})

// 合并分片
func mergeChunks(fileName string, totalChunks int) error {
	// 创建最终文件
	finalPath := "./uploads/" + fileName
	finalFile, err := os.Create(finalPath)
	if err != nil {
		return err
	}
	defer finalFile.Close()

	// 逐个读取分片并写入最终文件
	for i := 0; i < totalChunks; i++ {
		chunkPath := fmt.Sprintf("./uploads/temp/%s_%d", fileName, i)
		chunkFile, err := os.Open(chunkPath)
		if err != nil {
			return err
		}

		if _, err := io.Copy(finalFile, chunkFile); err != nil {
			chunkFile.Close()
			return err
		}

		chunkFile.Close()
		// 删除已合并的分片
		os.Remove(chunkPath)
	}

	return nil
}

五、应用场景与技术考量

应用场景

1. 视频网站：用户上传大视频文件时，需要断点续传和分片处理确保上传成功
2. 云存储服务：如网盘应用，需要支持大文件可靠传输
3. 企业文档管理系统：员工上传大型设计文件或数据集

技术优缺点

优点：

• 提高大文件传输的可靠性
• 减少网络中断的影响
• 降低服务器内存压力

缺点：

• 实现复杂度较高
• 需要额外的存储空间处理分片
• 客户端和服务端都需要特殊处理

注意事项

1. 安全性：验证文件类型，防止恶意文件上传
2. 清理机制：定期清理未完成的分片文件
3. 并发控制：处理同时上传多个分片的情况

六、总结

通过Gin框架实现文件上传下载的进阶功能，可以显著提升用户体验和系统可靠性。断点续传解决了网络不稳定的问题，分片处理则让大文件传输成为可能。虽然实现起来有一定复杂度，但对于需要处理大文件的Web应用来说，这些功能是必不可少的。