mime/multipart Reader.NextPart 如何区分文件字段和普通字段

在 Go 中，mime/multipart.Reader.NextPart 会按顺序返回 multipart 消息里的每个 *multipart.Part。区分普通字段和文件字段时，最稳妥的判断是：先读取 FormName() 取得表单字段名，再看 FileName() 是否为空。非空通常表示该 Part 的 Content-Disposition 带有文件名，应按文件内容处理；为空则按普通表单字段处理。

需要注意，NextPart 只负责移动到下一个 Part，并不会替你决定业务字段，也不会把整个文件一次性读入内存。当前 Part 的正文要通过 Read 消费，循环结束时的 io.EOF 是正常结束信号，其它错误才需要返回或记录。

一、先理解 NextPart 返回的是什么

multipart.Reader 是一个顺序迭代器。每调用一次 NextPart，就得到一个带有头部和正文读取能力的 *multipart.Part。Part 的头部可以通过 Header 查看，正文则像普通 io.Reader 一样读取。

如果请求来自 net/http，可以先从 Content-Type 中解析 boundary，再创建 Reader。下面的示例把“创建 Reader”单独放出来，便于看清 boundary 的来源；示例只关注解析，不涉及上传鉴权。

package main

import (
    "fmt"
    "io"
    "mime"
    "mime/multipart"
    "net/http"
)

func readMultipart(r *http.Request) error {
    // 解析 Content-Type，boundary 决定每个 Part 的分隔线。
    mediaType, params, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
    if err != nil {
        return fmt.Errorf("解析 Content-Type 失败: %w", err)
    }
    if mediaType != "multipart/form-data" {
        return fmt.Errorf("不支持的媒体类型: %s", mediaType)
    }

    boundary := params["boundary"]
    if boundary == "" {
        return fmt.Errorf("缺少 multipart boundary")
    }

    mr := multipart.NewReader(r.Body, boundary)
    for {
        part, err := mr.NextPart()
        if err == io.EOF {
            // 所有 Part 都已读完，EOF 在这里表示正常结束。
            return nil
        }
        if err != nil {
            return fmt.Errorf("读取下一个 Part 失败: %w", err)
        }
        if err := handlePart(part); err != nil {
            return err
        }
    }
}

生产代码中如果函数接管了请求体生命周期，还应由调用方负责关闭 r.Body。上例的关键点是不要把 io.EOF 当成异常，也不要在拿到 Part 后立刻调用下一次 NextPart 而跳过当前正文。

二、FormName 和 FileName 分别表示什么

Part.FormName() 返回 Content-Disposition 为 form-data 时的 name 参数；例如 HTML 表单中的 description 或 attachment。Part.FileName() 返回文件名参数；当它非空时，当前 Part 通常就是文件字段。

两者不要混为一谈：FormName 是“这个值在表单里的字段名”，FileName 是“上传对象携带的文件名”。一个文件 Part 可能同时有 FormName() == "attachment" 和 FileName() == "report.pdf"。

三、用 FileName 区分文件字段和普通字段

下面的处理函数给出一个最小可用模式：普通字段限制读取大小后转成字符串；文件字段则直接把当前 Part 复制到一个 Writer。这样不会因为判断类型而额外读取一次，也不会把整个文件默认放进内存。

package main

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

func handlePart(part *multipart.Part) error {
    fieldName := part.FormName()
    fileName := part.FileName()

    if fileName == "" {
        // 普通字段使用上限，避免异常大的字段占用过多内存。
        value, err := io.ReadAll(io.LimitReader(part, 1

这里的 io.LimitReader 只是普通字段的示例边界，不代表所有业务都应使用固定的 1 MiB。文件字段应结合业务允许的大小、目标存储和清理策略设计；如果只是把文件复制到磁盘，也可以把 bytes.Buffer 换成已打开的目标文件。

四、循环中如何正确处理 EOF 和读取错误

标准循环只需要三种分支：

• err == nil：拿到有效 Part，先处理当前 Part，再继续下一次迭代。
• errors.Is(err, io.EOF)：没有更多 Part，按正常结束处理。
• 其它错误：multipart 格式损坏、底层读取失败或头部解析失败，应保留原错误上下文。

NextPart 读取下一个 Part 时会推进底层解析器；因此当前 Part 的数据需要在进入下一轮前消费完。若只读取了一部分就调用 NextPart，解析器会关闭当前 Part 并推进到下一个边界，业务上可能丢失尚未处理的数据。

如果要支持 quoted-printable 的透明解码，应使用 NextPart；如果明确需要保留原始传输编码，可以了解 NextRawPart 的差异。两者都以 io.EOF 作为没有更多 Part 的信号。

五、几个容易写错的判断

不要只根据字段名猜类型。字段名叫 file 不代表它真的带文件名，真正的判断仍应查看 FileName()，再决定是否按文件流处理。

不要把 FileName 当成安全路径。它是请求元数据，保存文件时应由业务生成目标名，并结合大小、扩展名和内容类型做必要的业务约束；文章这里不讨论上传鉴权或安全策略实现。

不要把 NextPart 与 ReadForm 混成同一种模式。ReadForm 会把表单解析成内存和临时文件结构；NextPart 更适合需要按顺序流式处理的场景。选择哪个 API，取决于你是要随机访问已经解析好的表单，还是逐段消费请求体。

总结

使用 mime/multipart.Reader.NextPart 时，可以记住这条规则：FormName 负责定位表单字段，FileName 非空负责识别带文件名的文件字段，正文通过当前 Part 的 Read 或 io.Copy 消费，循环遇到 io.EOF 正常结束。这样既能区分普通字段和文件字段，也能保持流式读取的边界。

相关问题

NextPart 返回 io.EOF 是错误吗？

不是。它表示 multipart 消息已经没有更多 Part；只有其它错误才应按失败处理。

FileName 为空但仍然是文件怎么办？

这类输入不能按“带文件名的文件字段”可靠识别。应结合协议约定、字段白名单和业务格式做明确处理，不要仅凭字段名擅自当作文件保存。

什么时候用 ReadForm 而不是 NextPart？

需要把整个表单整理成字段和文件集合、后续按字段访问时可以考虑 ReadForm；需要顺序消费、控制流式复制和单段资源边界时，NextPart 更直接。