Go / 系统课时
处理表单与文件上传
处理表单与文件上传
文件上传的难点不在于“拿到一个文件”,而在于同时控制请求总大小、解析阶段的内存占用、临时文件生命周期以及最终落盘的安全边界。下面用一个可运行的上传接口,把字段读取、multipart 解析、类型检查和清理流程串起来。
学习目标
- 使用
MaxBytesReader与ParseMultipartForm分别限制请求总大小和内存使用 - 安全读取表单字段与文件,校验文件名和内容类型后再落盘
- 理解 multipart 文件在内存与临时文件之间的分配,以及清理责任
先区分两个大小限制
ParseMultipartForm(maxMemory) 的 maxMemory 不是“整个上传请求最多多大”。它主要限制文件 part 保存在内存中的总量,超出的文件数据会写入系统临时文件;非文件字段和 multipart 元数据还会额外占用内存。
真正限制请求体总大小,应在解析之前用 http.MaxBytesReader 包装 r.Body。这样无论客户端提交一个大文件、多个文件还是大量表单字段,只要读取超过上限就会失败,避免在完成校验前消耗过多服务器资源。

实现一个受限上传接口
下面示例接受 title 和 file 两个字段。请求体最多 10 MiB,multipart 解析最多把 2 MiB 的文件数据留在内存;示例只接受 PNG、JPEG 和纯文本。服务器不使用客户端文件名作为存储路径,而是通过 os.CreateTemp 生成自己的落盘名称。
package main
import (
"encoding/json"
"errors"
"io"
"log"
"net/http"
"os"
"path"
"strings"
)
const (
maxBody int64 = 10 << 20
maxMemory int64 = 2 << 20
)
type uploadResponse struct {
Title string `json:"title"`
Name string `json:"name"`
Type string `json:"type"`
Size int64 `json:"size"`
}
func upload(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
// 总大小必须在解析 multipart 之前限制。
r.Body = http.MaxBytesReader(w, r.Body, maxBody)
if err := r.ParseMultipartForm(maxMemory); err != nil {
var sizeErr *http.MaxBytesError
if errors.As(err, &sizeErr) {
http.Error(w, "request body too large", http.StatusRequestEntityTooLarge)
return
}
http.Error(w, "invalid multipart form", http.StatusBadRequest)
return
}
if r.MultipartForm != nil {
// 清理由解析器创建的临时文件,不影响后面主动保存的目标文件。
defer r.MultipartForm.RemoveAll()
}
title := ""
if values := r.MultipartForm.Value["title"]; len(values) > 0 {
title = values[0]
}
file, header, err := r.FormFile("file")
if err != nil {
http.Error(w, "missing file field", http.StatusBadRequest)
return
}
defer file.Close()
// 兼容客户端文件名里的 / 与 \,但绝不把它直接拼进服务器路径。
safeName := path.Base(strings.ReplaceAll(header.Filename, "\\", "/"))
if safeName == "." || safeName == ".." || safeName == "/" || safeName == "" {
http.Error(w, "invalid filename", http.StatusBadRequest)
return
}
head := make([]byte, 512)
n, err := file.Read(head)
if err != nil && err != io.EOF {
http.Error(w, "cannot inspect file", http.StatusBadRequest)
return
}
contentType := http.DetectContentType(head[:n])
if contentType != "image/png" &&
contentType != "image/jpeg" &&
contentType != "text/plain; charset=utf-8" {
http.Error(w, "unsupported file type", http.StatusUnsupportedMediaType)
return
}
if _, err := file.Seek(0, io.SeekStart); err != nil {
http.Error(w, "cannot rewind file", http.StatusInternalServerError)
return
}
if err := os.MkdirAll("uploads", 0o750); err != nil {
http.Error(w, "cannot prepare upload directory", http.StatusInternalServerError)
return
}
dst, err := os.CreateTemp("uploads", "upload-*")
if err != nil {
http.Error(w, "cannot create destination", http.StatusInternalServerError)
return
}
written, copyErr := io.Copy(dst, file)
closeErr := dst.Close()
if copyErr != nil || closeErr != nil {
_ = os.Remove(dst.Name())
http.Error(w, "cannot save file", http.StatusInternalServerError)
return
}
// 这里只返回上传结果,因此直接把响应媒体类型固定为 JSON。
w.Header()["Content-Type"] = []string{"application/json"}
_ = json.NewEncoder(w).Encode(uploadResponse{
Title: title,
Name: safeName,
Type: contentType,
Size: written,
})
}
func main() {
http.HandleFunc("/upload", upload)
log.Println("listening on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}预期输出
<TIME> listening on :8080日志前的日期与时间格式会随运行环境变化,因此这里用 <TIME> 表示动态值。
发送请求并检查结果
不需要准备本地文件,可以让 curl 从标准输入构造一个名为 notes.txt 的上传文件。printf 输出 13 字节,其中包含末尾换行。
printf 'hello upload\n' | curl -sS -F 'title=notes' -F 'file=@-;filename=notes.txt;type=text/plain' http://localhost:8080/upload预期结果
{"title":"notes","name":"notes.txt","type":"text/plain; charset=utf-8","size":13}如果请求体超过 10 MiB,接口返回 413 Request Entity Too Large;如果文件内容类型不在允许集合中,则返回 415 Unsupported Media Type。判断类型时使用文件内容探测结果,而不是直接相信客户端上传的 Content-Type 或扩展名。
临时文件与清理边界
ParseMultipartForm 会完整解析 multipart 表单。文件数据在内存阈值内时可能留在内存,超过阈值的部分会进入系统临时文件;FileHeader.Open 对这两种存储方式提供统一读取接口,所以业务代码不应依赖其底层一定是 *os.File。
r.MultipartForm.RemoveAll() 只负责删除 multipart 解析产生的临时文件。示例中 os.CreateTemp("uploads", ...) 创建的是应用主动保存的目标文件,不会被 RemoveAll 删除。生产代码还应根据业务状态决定何时删除已保存文件,例如数据库事务失败、病毒扫描失败或对象存储上传失败时回滚。
当文件可能达到数百 MiB 或更大时,ParseMultipartForm 的“先完整解析再处理”并不理想。此时应考虑 MultipartReader 逐 part 流式处理,并继续保留总请求大小限制、类型校验和失败清理策略。