Go语言第二十一章(Gin上传文件)

Gin 上传文件

上传走的是 multipart/form-data:浏览器把文件拆成一段一段放进请求正文,服务端按表单字段名把文件取出来,再写到磁盘。

本篇按动手顺序来:

  1. 单文件上传
  2. 校验大小和后缀
  3. 多文件上传

上一篇的 DefaultPostForm 只能读普通表单字段,读不到文件。文件用 FormFile 或 MultipartForm。


1. 单文件上传

前端字段名是什么,服务端就按什么取。下面约定字段名是 file:

html 复制代码
<form action="/upload" method="post" enctype="multipart/form-data">
  <input type="file" name="file">
  <button type="submit">上传</button>
</form>

enctype="multipart/form-data" 必须写上,否则正文里没有文件。

go 复制代码
router.POST("/upload", func(ctx *gin.Context) {
	file, err := ctx.FormFile("file")
	if err != nil {
		ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	// etc/static/1.png → 1.png,只留文件名
	dst := filepath.Join("./files/", filepath.Base(file.Filename))
	if err := ctx.SaveUploadedFile(file, dst); err != nil {
		ctx.String(http.StatusInternalServerError, "保存失败")
		return
	}
	ctx.String(http.StatusOK, "上传成功")
})
API 作用
ctx.FormFile("file") 按字段名取出一个 文件。返回的是 *multipart.FileHeader,里面有原始文件名和大小
file.Filename 客户端带来的文件名,可能带目录,例如 etc/static/1.png
filepath.Base(file.Filename) 只留最后一段:etc/static/1.png → 1.png
filepath.Join("./files/", 文件名) 拼出落盘路径 files/1.png。分隔符按当前系统处理
ctx.SaveUploadedFile(file, dst) 把文件写到 dst。父目录不存在时会自己建

Base 要加上。客户端可以带上 ../ 或一整段路径,直接拿 file.Filename 去拼接,文件会写到 ./files/ 外面。Base 丢掉目录,只留下 1.png 这种名字,再和 ./files/ 拼在一起。

SaveUploadedFile 的错误要判断。保存失败时如果继续往下写「上传成功」,前端看到的结果是错的。

用 curl 试(-F 会自动带上 multipart/form-data):

bash 复制代码
curl -F "file=@1.png" http://localhost:8080/upload

file= 对应 FormFile("file"),@1.png 表示把本地文件 1.png 传上去。成功后项目下会出现 files/1.png。


2. 校验大小和后缀

文件取出来之后、写盘之前做两道检查:太大的丢掉,后缀不在白名单里的丢掉。

大小:5 << 20 就是 5MB

<< 是左移。二进制往左挪 n 位,数值乘上 2 的 n 次方。内存里文件大小的单位是字节,所以用位移写出 KB、MB、GB:

写法 等于 含义
1 << 10 1024 字节 1KB
1 << 20 1024 × 1024 字节 1MB
1 << 30 1024 × 1024 × 1024 字节 1GB
5 << 20 5 × 1MB 5MB

左移的位数决定单位:10 是 KB,20 是 MB,30 是 GB。前面的数字是「几个」这种单位。5 << 20 就是 5 个 MB。

go 复制代码
const MaxSize = 5 << 20 // 5MB

if file.Size > MaxSize {
	ctx.String(http.StatusRequestEntityTooLarge, "文件过大")
	return
}

file.Size 是字节数。超过 5MB 回 413 (StatusRequestEntityTooLarge),然后 return,后面的保存不再执行。

后缀:只允许 png 和 jpg

用 map 当白名单,查找是 O(1),不在里面的键读出来是 false:

go 复制代码
var allowExt = map[string]bool{
	".png": true,
	".jpg": true,
}

ext := strings.ToLower(filepath.Ext(file.Filename))
if !allowExt[ext] {
	ctx.String(http.StatusBadRequest, "该后缀暂时不支持")
	return
}

filepath.Ext 带点,"1.png" 得到 ".png",所以白名单里要写成 ".png",不能写成 "png"。

后缀大小写不固定,Windows 上经常是 .PNG、.JPG。Ext 不会帮你转小写,比较前用 strings.ToLower,否则合法图片会被拒。

两道检查都放在 SaveUploadedFile 前面:

go 复制代码
router.POST("/upload", func(ctx *gin.Context) {
	file, err := ctx.FormFile("file")
	if err != nil {
		ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	if file.Size > MaxSize {
		ctx.String(http.StatusRequestEntityTooLarge, "文件过大")
		return
	}
	ext := strings.ToLower(filepath.Ext(file.Filename))
	if !allowExt[ext] {
		ctx.String(http.StatusBadRequest, "该后缀暂时不支持")
		return
	}

	dst := filepath.Join("./files/", filepath.Base(file.Filename))
	if err := ctx.SaveUploadedFile(file, dst); err != nil {
		ctx.String(http.StatusInternalServerError, "保存失败")
		return
	}
	ctx.String(http.StatusOK, "上传成功")
})
请求 结果
1.png,小于 5MB files/1.png,响应「上传成功」
6MB 的 png 413,「文件过大」,磁盘上没有这个文件
1.gif 400,「该后缀暂时不支持」
photo.JPG 转小写后是 .jpg,允许保存

3. 多文件上传

一次选好几个文件时,FormFile 只会拿到该字段的第一个。整包解析用 MultipartForm,再按字段名取出文件切片。

前端字段名改成 files,并加上 multiple:

html 复制代码
<input type="file" name="files" multiple>
go 复制代码
form, err := ctx.MultipartForm()
if err != nil {
	ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
	return
}

files := form.File["files"]

form.File 的类型是 map[string][]*multipart.FileHeader。键是字段名 "files",值是这个字段上的全部文件。字段名和前端 name 不一致时,取出来是 nil,循环一次都不会进。

大小、后缀和单文件是同一套判断,放进循环里,每个文件单独看。有一个不合格就 return,不再保存后面的:

go 复制代码
router.POST("/upload", func(ctx *gin.Context) {
	form, err := ctx.MultipartForm()
	if err != nil {
		ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	files := form.File["files"]
	if len(files) == 0 {
		ctx.String(http.StatusBadRequest, "没有文件")
		return
	}

	for _, file := range files {
		if file.Size > MaxSize {
			ctx.String(http.StatusRequestEntityTooLarge, "文件过大")
			return
		}
		ext := strings.ToLower(filepath.Ext(file.Filename))
		if !allowExt[ext] {
			ctx.String(http.StatusBadRequest, "该后缀暂时不支持")
			return
		}

		dst := filepath.Join("./files/", filepath.Base(file.Filename))
		if err := ctx.SaveUploadedFile(file, dst); err != nil {
			ctx.String(http.StatusInternalServerError, "保存失败")
			return
		}
	}
	ctx.String(http.StatusOK, "上传成功")
})

循环结束后再回复「上传成功」。写在循环里面的话,第一个文件保存完就会结束响应。

两个文件一起传:

bash 复制代码
curl -F "files=@1.png" -F "files=@2.jpg" http://localhost:8080/upload

两次 -F 的字段名都是 files,对应 form.File["files"]。

合在一起

go 复制代码
package main

import (
	"net/http"
	"path/filepath"
	"strings"

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

// 1 << 10 是 1KB,1 << 20 是 1MB,1 << 30 是 1GB
const MaxSize = 5 << 20 // 5MB

var allowExt = map[string]bool{
	".png": true,
	".jpg": true,
}

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

	router.POST("/upload", func(ctx *gin.Context) {
		form, err := ctx.MultipartForm()
		if err != nil {
			ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		files := form.File["files"]
		if len(files) == 0 {
			ctx.String(http.StatusBadRequest, "没有文件")
			return
		}

		for _, file := range files {
			if file.Size > MaxSize {
				ctx.String(http.StatusRequestEntityTooLarge, "文件过大")
				return
			}
			ext := strings.ToLower(filepath.Ext(file.Filename))
			if !allowExt[ext] {
				ctx.String(http.StatusBadRequest, "该后缀暂时不支持")
				return
			}

			dst := filepath.Join("./files/", filepath.Base(file.Filename))
			if err := ctx.SaveUploadedFile(file, dst); err != nil {
				ctx.String(http.StatusInternalServerError, "保存失败")
				return
			}
		}
		ctx.String(http.StatusOK, "上传成功")
	})

	if err := router.Run(); err != nil {
		panic(err)
	}
}

只传一个文件时,用同一个接口即可,字段名仍然是 files:

bash 复制代码
curl -F "files=@1.png" http://localhost:8080/upload

单文件那节的 FormFile("file") 适合确定只有一个文件的接口;多个文件用 MultipartForm。


小结

主题 记住什么
单文件 ctx.FormFile("file"),字段名和前端 name 一致
落盘 filepath.Join("./files/", filepath.Base(file.Filename)),Base 去掉客户端带来的目录
保存 ctx.SaveUploadedFile(file, dst),错误要 return
大小 5 << 20 是 5MB。10 / 20 / 30 分别对应 KB / MB / GB。超限回 413
后缀 filepath.Ext 的结果带点,白名单写成 ".png"。比较前 strings.ToLower
多文件 ctx.MultipartForm(),用 form.File["files"] 取出切片,循环里做同一套校验再保存
相关推荐
JavaGuide2 小时前
Cloudflare 开源的这套神级安全审计 Skill 太好用了!
前端·后端
学长毕设3 小时前
基于SpringBoot社区快递驿站物流配送系统-附源码
java·spring boot·后端
Resean02233 小时前
Spring 源码分析(七)AOP 原理(上):代理的创建
java·后端·spring
Tangq一定可以的3 小时前
Spring AI Advisor 详解 - 给大模型调用加上“切面“,日志/过滤/记忆一键搞定
java·后端·spring
小巫编程室4 小时前
我造了一个 Java 能力包:让 AI 直接调用你的业务代码
java·前端·后端
十有八七4 小时前
手搓 Agent(五):学会翻书——RAG,先查资料再回答
前端·人工智能·后端
Swot4 小时前
产品 RAG 知识库与 AI 顾问 设计与实现
前端·后端
深入云栈4 小时前
Netty 4.2.x 源码深度解析 (二十四):池化内存分配 —— PoolArena、PoolChunk 与 PoolSubpage
java·后端·架构
ServBay5 小时前
PHP 8.6 最新发布:语法更新、实用函数与升级要点
后端·php