Go multipart.Reader.NextPart 读取上传内容时怎样区分文件与普通字段

用 Go 解析 multipart/form-data 时，multipart.Reader.NextPart 每次返回一个 *multipart.Part。判断它是普通字段还是文件部件，最可靠的入口不是猜字段名，而是读取 part.FileName()：返回非空字符串通常表示请求头带有文件名；为空时再按普通字段处理。part.FormName() 用来取得字段名，遍历结束只判断 io.EOF。

核心写法是：NextPart 取部件，FormName 取字段名，FileName 区分文件，读取当前 Part 后再请求下一个部件。普通字段可以读入内存，文件内容则应交给受控的流式目标。

本文围绕标准库接口说明判断和读取边界，不展开 Web 框架封装，也不把“识别为文件”误解成“可以直接使用客户端传来的文件名落盘”。

FileName 和 FormName 怎样区分文件与普通字段

Part 的头部来自 multipart 部件。表单普通字段通常只有 name，文件部件通常同时带有 name 和 filename。标准库把这两个参数分别暴露成 FormName() 与 FileName()。

下面的函数把当前部件读成内存中的结果，适合演示和小字段。真实上传接口如果允许较大文件，应替换为有大小限制的流式目标；不要因为 FileName() 非空就直接拼接路径。

package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
)

type PartMeta struct {
    FieldName string
    FileName  string
    IsFile    bool
    Data      []byte
}

func readMultipart(body io.Reader, boundary string) ([]PartMeta, error) {
    reader := multipart.NewReader(body, boundary)
    var parts []PartMeta

    for {
        part, err := reader.NextPart()
        if err == io.EOF {
            // 没有更多部件时，正常结束遍历。
            return parts, nil
        }
        if err != nil {
            // 语法错误或输入中断不能伪装成正常结束。
            return nil, fmt.Errorf("读取 multipart 部件失败: %w", err)
        }

        filename := part.FileName()
        var payload bytes.Buffer
        if _, err := io.Copy(&payload, part); err != nil {
            // Copy 读取的是当前部件的 body，不应忽略中途错误。
            return nil, fmt.Errorf("读取字段 %q 失败: %w", part.FormName(), err)
        }

        parts = append(parts, PartMeta{
            FieldName: part.FormName(),
            FileName:  filename,
            IsFile:    filename != "",
            Data:      payload.Bytes(),
        })
    }
}

这里的关键判断只有一条：filename != ""。它判断的是部件头中是否存在文件名参数，不是判断文件内容是否为空；一个空文件仍然可能是文件部件。另一方面，FormName() 为空时，说明当前部件不一定是标准的 form-data 字段，不能强行当作普通表单项。

读取 Part 内容时怎样保持边界

Part 实现了 io.Reader。读取它时，数据边界由 multipart 解析器维护：读到当前部件结束后，读取会结束，下一次调用 NextPart() 才会取得下一个部件。不要把整个原始请求体交给一次 io.ReadAll 再自行切分，否则会重新承担边界解析、头部解析和异常处理。

• 小字段：可以使用 io.ReadAll(part)，但要在业务层设置总体大小上限。
• 文件内容：使用 io.Copy(dst, part) 连接到受控目标，避免一次性复制全部内容。
• 读取失败：保留错误并停止当前请求，不把部分数据当成完整文件。

如果只想保存文件部件，可以把分支写得更明确。下面仍然使用内存缓冲只是为了让示例短小；生产代码应把 bytes.Buffer 换成带配额的目标。

func collectFiles(body io.Reader, boundary string) (map[string][]byte, error) {
    reader := multipart.NewReader(body, boundary)
    files := make(map[string][]byte)

    for {
        part, err := reader.NextPart()
        if err == io.EOF {
            // io.EOF 只表示部件序列正常结束。
            return files, nil
        }
        if err != nil {
            return nil, fmt.Errorf("解析上传部件失败: %w", err)
        }

        if part.FileName() == "" {
            // 普通字段可以按需读取；这里跳过其内容后继续遍历。
            continue
        }

        content, err := io.ReadAll(part)
        if err != nil {
            // 只接受完整读取，避免保存半截文件。
            return nil, fmt.Errorf("读取文件 %q 失败: %w", part.FileName(), err)
        }
        files[part.FormName()] = content
    }
}

跳过普通字段时，下一次 NextPart 会继续推进解析器；文件部件则应先完整读取或复制到目标，再请求下一个部件。部件的读取顺序也是请求体中的顺序，不能对 Reader 做 Seek。

NextPart 结束时为什么只判断 io.EOF

NextPart() 返回两个结果：部件和错误。没有更多部件时返回 io.EOF，这是正常结束；边界缺失、头部不完整或底层读取失败则属于其他错误。用“只要有错误就当成结束”的写法，会把坏请求误报成上传成功。

for {
    part, err := reader.NextPart()
    if errors.Is(err, io.EOF) {
        // 只有这个分支代表 multipart 序列已经结束。
        break
    }
    if err != nil {
        // 其他错误要返回，便于调用方区分坏请求和正常结束。
        return fmt.Errorf("读取下一个部件失败: %w", err)
    }

    // 先消费当前部件，再进入下一轮。
    if _, err := io.Copy(io.Discard, part); err != nil {
        return fmt.Errorf("消费部件 %q 失败: %w", part.FormName(), err)
    }
}

还有一个容易忽略的选择：NextPart 对 Content-Transfer-Encoding: quoted-printable 有特殊处理，读取 body 时会透明解码；NextRawPart 则不做这层处理。只有需要保留原始传输编码时，才考虑后者，否则优先使用题目中的 NextPart。

常见误区与速查

• 不要用字段名是否叫 file 判断类型，文件与普通字段都可能使用任意字段名。
• 不要把空的 FileName() 等同于空内容；空文件仍然有文件部件语义。
• 不要忽略 io.Copy 或 io.ReadAll 的错误；部分数据不能直接当成完整结果。
• 不要把客户端文件名直接拼进本地路径；文件落盘需要独立的大小、路径和权限策略。

可以把判断逻辑压缩成一句速记：FormName 解决“这是哪个字段”，FileName 解决“它是否带文件部件语义”，Part 负责当前内容，NextPart 负责继续迭代，io.EOF 负责表示正常结束。

相关问题

普通字段不读取，直接调用 NextPart 会不会错过边界？ 不会。解析器会在推进到下一个部件时处理当前部件的剩余内容，但如果当前部件已经开始读取，仍应保持顺序，不要并发使用同一个 multipart.Reader。

什么时候应该用 ReadForm？ 如果希望一次得到 Form.Value 和 Form.File，并接受标准库的内存与临时文件管理，可以考虑 ReadForm；需要逐部件控制读取、大小限制或错误路径时，使用 NextPart 更直接。