Go http.Request.FormFile 怎样区分表单字段缺失与上传失败

在 Go 的文件上传接口里，最容易混淆的不是“怎么取文件”，而是 FormFile 返回错误后到底发生了什么：是请求里根本没有这个字段，还是 multipart 请求解析失败，或者文件已经找到但后续读取失败？这几种情况的处理动作并不一样。

判断字段缺失时优先使用 errors.Is(err, http.ErrMissingFile)；其它错误保留为解析或请求格式问题。只有 err == nil 后，才把返回的 multipart.File 当作可读资源，并及时关闭它。

FormFile 返回的三个对象分别代表什么

Request.FormFile(key) 返回文件、文件头和错误三个值。官方文档说明，它会在需要时调用 ParseMultipartForm 与 ParseForm，因此调用点看起来很小，背后仍然包含请求体解析。

拿到返回值后，建议先判断错误，再使用文件句柄和元数据。这样可以避免在字段不存在时继续访问 header.Filename，也能把“找不到字段”和“请求坏了”分开记录。

package upload

import (
    "errors"
    "fmt"
    "net/http"
)

func inspectUpload(r *http.Request) error {
    // FormFile 会按 key 查找第一个文件部件，并在必要时触发表单解析。
    file, header, err := r.FormFile("document")
    if err != nil {
        // ErrMissingFile 表示指定字段没有对应的文件部件。
        if errors.Is(err, http.ErrMissingFile) {
            return fmt.Errorf("上传字段 document 缺失: %w", err)
        }
        // 其它错误要保留，便于区分请求格式或 multipart 解析失败。
        return fmt.Errorf("解析上传请求失败: %w", err)
    }
    // 成功拿到文件后负责释放句柄，避免临时文件或底层资源长期占用。
    defer file.Close()
    if header == nil {
        return fmt.Errorf("上传字段 document 没有文件头")
    }
    fmt.Printf("收到文件 %q，大小 %d 字节\n", header.Filename, header.Size)
    return nil
}

字段缺失和解析失败不要用同一条分支

字段缺失通常是客户端没有提交名为 document 的文件部件，或者表单字段名写错。它属于可预期的输入问题，可以返回明确的参数提示。

如果 Content-Type 不是可解析的 multipart/form-data，边界字符串损坏，或请求体本身读取失败，返回值就不应被包装成“缺少文件”。这类错误说明请求结构或传输过程有问题，记录原始错误更有利于排查。

判断时不要只写 err.Error() == "http: no such file"。错误文本是给人看的字符串，使用 errors.Is 才能兼容错误包装，并保持判断与标准库哨兵错误的语义一致。

拿到文件后，读取错误是另一层问题

FormFile 成功只说明标准库已经找到一个文件部件并返回了可读文件对象，不代表文件内容已经读完，更不代表业务校验已经通过。读取过程中仍可能出现底层错误，所以应该把读取错误单独处理。

package upload

import (
    "errors"
    "fmt"
    "io"
    "net/http"
)

func readUpload(r *http.Request) ([]byte, error) {
    // 只有成功返回后才会进入文件读取分支。
    file, header, err := r.FormFile("document")
    if err != nil {
        if errors.Is(err, http.ErrMissingFile) {
            return nil, fmt.Errorf("缺少 document 文件字段: %w", err)
        }
        return nil, fmt.Errorf("multipart 请求解析失败: %w", err)
    }
    // 无论后续读取成功还是失败，都要释放 multipart.File。
    defer file.Close()
    if header == nil {
        return nil, fmt.Errorf("文件头为空")
    }
    // ReadAll 的错误表示读取阶段失败，不能改写成字段缺失。
    data, err := io.ReadAll(file)
    if err != nil {
        return nil, fmt.Errorf("读取 %q 的内容失败: %w", header.Filename, err)
    }
    return data, nil
}

生产接口通常不应该无条件把整个文件读进内存。上面的示例只为了说明错误边界；实际保存文件时可以改成流式复制，并在复制返回错误时保留源错误。若 Close 也需要被审计，可以使用命名返回值，在没有更早错误时把关闭错误带回调用方。

先限制请求体，再使用 FileHeader 做业务判断

FileHeader.Size 适合做已解析文件部件的业务判断，例如拒绝超过 20 MiB 的文件。但它不应代替请求体限制。HTTP 服务端可以在进入解析前用 http.MaxBytesReader 限制整个请求体，超过上限时读取会返回 *http.MaxBytesError。

func uploadHandler(w http.ResponseWriter, r *http.Request) {
    // 先限制整个请求体，避免 multipart 解析面对无界输入。
    r.Body = http.MaxBytesReader(w, r.Body, 20 20

这里的两个 20 MiB 不是必须相同：请求体上限要覆盖 multipart 边界、字段和其它开销，文件业务上限则只针对文件部件。不要把示例数字当成所有业务的安全默认值，应根据实际协议和存储策略调整。

几个容易误判的边界

• 字段名不一致：前端使用 file，服务端读取 document 时，通常应归类为 http.ErrMissingFile，先检查双方约定的 key。
• 空文件不是字段缺失：文件字段存在但大小为零时，仍可能有 FileHeader。是否允许空文件是业务规则，不要拿缺失错误代替。
• 只看文件名不等于校验文件：FileHeader.Filename 是客户端提供的元数据，保存前仍需做路径、类型和内容策略处理。
• FormFile 与 MultipartReader 的取舍：需要标准表单解析和第一个文件时，FormFile 更直接；需要真正按流处理 multipart 请求体时，应考虑 Request.MultipartReader。

结论：把错误分成三层，排查会更快

可以把 FormFile 的处理记成三层：第一层是字段查找，缺失时识别 http.ErrMissingFile；第二层是 multipart 请求解析，保留其它错误；第三层是文件内容读取与资源释放，单独处理读取错误并关闭文件。这样日志、HTTP 状态码和前端提示都能保持一致，也不会把真正的上传失败伪装成参数缺失。

相关问题

FormFile 会自动调用 ParseMultipartForm 吗？

会。官方文档说明 FormFile 在需要时会调用 ParseMultipartForm 和 ParseForm；如果你要控制解析策略或改用流式读取，应显式选择对应 API。

为什么不建议只比较 error.Error()？

错误文本不是稳定接口，而且错误可能被包装。使用 errors.Is 判断 http.ErrMissingFile，其它错误通过 %w 保留原始原因。

拿到 multipart.File 后一定要 Close 吗？

应当。即使当前文件内容落在内存中，也应保持统一的资源生命周期写法；当内容落到临时文件或底层实现变化时，及时 Close 能避免资源泄漏。