Go / 系统课时

处理表单与文件上传

处理表单与文件上传

文件上传的难点不在于“拿到一个文件”,而在于同时控制请求总大小、解析阶段的内存占用、临时文件生命周期以及最终落盘的安全边界。下面用一个可运行的上传接口,把字段读取、multipart 解析、类型检查和清理流程串起来。

学习目标

  • 使用 MaxBytesReader 与 ParseMultipartForm 分别限制请求总大小和内存使用
  • 安全读取表单字段与文件,校验文件名和内容类型后再落盘
  • 理解 multipart 文件在内存与临时文件之间的分配,以及清理责任

先区分两个大小限制

ParseMultipartForm(maxMemory) 的 maxMemory 不是“整个上传请求最多多大”。它主要限制文件 part 保存在内存中的总量,超出的文件数据会写入系统临时文件;非文件字段和 multipart 元数据还会额外占用内存。

真正限制请求体总大小,应在解析之前用 http.MaxBytesReader 包装 r.Body。这样无论客户端提交一个大文件、多个文件还是大量表单字段,只要读取超过上限就会失败,避免在完成校验前消耗过多服务器资源。

multipart 上传的限流、解析与落盘流程

实现一个受限上传接口

下面示例接受 title 和 file 两个字段。请求体最多 10 MiB,multipart 解析最多把 2 MiB 的文件数据留在内存;示例只接受 PNG、JPEG 和纯文本。服务器不使用客户端文件名作为存储路径,而是通过 os.CreateTemp 生成自己的落盘名称。

go
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))
}

预期输出

text
<TIME> listening on :8080

日志前的日期与时间格式会随运行环境变化,因此这里用 <TIME> 表示动态值。

发送请求并检查结果

不需要准备本地文件,可以让 curl 从标准输入构造一个名为 notes.txt 的上传文件。printf 输出 13 字节,其中包含末尾换行。

bash
printf 'hello upload\n' | curl -sS -F 'title=notes' -F 'file=@-;filename=notes.txt;type=text/plain' http://localhost:8080/upload

预期结果

json
{"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 流式处理,并继续保留总请求大小限制、类型校验和失败清理策略。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理表单与文件上传

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通