编辑“︁Gin文件下载”︁（章节）

= Gin文件下载 =

== 介绍 ==  
在Web开发中，文件下载是一个常见的功能需求。Gin框架提供了简单且高效的方式来实现文件下载，支持从服务器向客户端发送静态文件或动态生成的文件。本章将详细介绍如何在Gin中实现文件下载功能，包括基本用法、高级配置以及实际应用场景。

== 基础用法 ==  
Gin通过`c.File()`和`c.FileAttachment()`方法实现文件下载。以下是两种方法的区别：  
* `c.File(filepath string)`：直接发送文件内容，浏览器会根据文件类型决定是下载还是直接显示（如PDF或图片）。  
* `c.FileAttachment(filepath, filename string)`：强制浏览器下载文件，并允许指定下载时的文件名。

=== 示例1：直接发送文件 ===  
以下代码展示如何发送服务器上的静态文件：  
<syntaxhighlight lang="go">  
package main  

import (  
    "github.com/gin-gonic/gin"  
)  

func main() {  
    r := gin.Default()  
    r.GET("/download", func(c *gin.Context) {  
        filePath := "/path/to/your/file.pdf"  
        c.File(filePath)  
    })  
    r.Run(":8080")  
}  
</syntaxhighlight>  

**输入**：访问 `http://localhost:8080/download`  
**输出**：浏览器直接显示或下载`file.pdf`（取决于文件类型和浏览器设置）。

=== 示例2：强制下载并重命名文件 ===  
若需强制下载并自定义文件名，使用`c.FileAttachment()`：  
<syntaxhighlight lang="go">  
r.GET("/download-attachment", func(c *gin.Context) {  
    filePath := "/path/to/your/file.pdf"  
    c.FileAttachment(filePath, "custom-name.pdf")  
})  
</syntaxhighlight>  

**输入**：访问 `http://localhost:8080/download-attachment`  
**输出**：浏览器下载文件并保存为`custom-name.pdf`。

== 高级配置 ==  
=== 动态生成文件下载 ===  
Gin支持将动态生成的内容（如CSV或JSON）作为文件下载。以下示例生成CSV文件并发送：  
<syntaxhighlight lang="go">  
r.GET("/download-csv", func(c *gin.Context) {  
    data := [][]string{  
        {"Name", "Age", "City"},  
        {"Alice", "24", "New York"},  
        {"Bob", "30", "London"},  
    }  

    c.Header("Content-Type", "text/csv")  
    c.Header("Content-Disposition", "attachment; filename=data.csv")  
    writer := csv.NewWriter(c.Writer)  
    for _, row := range data {  
        writer.Write(row)  
    }  
    writer.Flush()  
})  
</syntaxhighlight>  

**输入**：访问 `http://localhost:8080/download-csv`  
**输出**：下载名为`data.csv`的文件，内容为动态生成的CSV数据。

=== 大文件分块下载 ===  
对于大文件，可通过分块传输（Chunked Transfer Encoding）优化内存使用：  
<syntaxhighlight lang="go">  
r.GET("/download-large", func(c *gin.Context) {  
    filePath := "/path/to/large-file.zip"  
    file, err := os.Open(filePath)  
    if err != nil {  
        c.AbortWithStatusJSON(500, gin.H{"error": "File not found"})  
        return  
    }  
    defer file.Close()  

    fi, _ := file.Stat()  
    c.Header("Content-Disposition", "attachment; filename=large-file.zip")  
    http.ServeContent(c.Writer, c.Request, "large-file.zip", fi.ModTime(), file)  
})  
</syntaxhighlight>  

**说明**：`http.ServeContent`会自动处理`Range`请求头，支持断点续传。

== 实际应用场景 ==  
1. **报表导出**：用户请求将数据库查询结果导出为Excel或CSV。  
2. **资源分发**：提供软件安装包或文档下载。  
3. **权限控制**：结合中间件验证用户权限后再允许下载。

=== 案例：带权限验证的文件下载 ===  
<syntaxhighlight lang="go">  
func AuthMiddleware() gin.HandlerFunc {  
    return func(c *gin.Context) {  
        token := c.GetHeader("Authorization")  
        if token != "valid-token" {  
            c.AbortWithStatus(401)  
            return  
        }  
        c.Next()  
    }  
}  

r.GET("/secure-download", AuthMiddleware(), func(c *gin.Context) {  
    c.FileAttachment("/path/to/secure-file.txt", "document.txt")  
})  
</syntaxhighlight>  

**流程说明**：  
<mermaid>  
sequenceDiagram  
    Client->>Server: GET /secure-download (无token)  
    Server-->>Client: 401 Unauthorized  
    Client->>Server: GET /secure-download (带有效token)  
    Server-->>Client: 发送document.txt  
</mermaid>  

== 常见问题 ==  
* **Q**: 文件路径错误导致下载失败？  
  **A**: 使用绝对路径或验证路径是否存在：  
  <syntaxhighlight lang="go">  
  if _, err := os.Stat(filePath); os.IsNotExist(err) {  
      c.AbortWithStatus(404)  
  }  
  </syntaxhighlight>  

* **Q**: 如何限制下载速度？  
  **A**: 通过`io.Copy`与`time.Sleep`实现限流（需自行封装）。

== 总结 ==  
Gin框架通过简洁的API支持灵活的文件下载功能，适用于静态文件、动态内容和大型文件分发。结合中间件可实现权限控制等高级需求。开发者应根据场景选择`c.File`、`c.FileAttachment`或`http.ServeContent`。

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin响应处理]]