Go multipart.Reader读取文件部件元数据的解析步骤

处理 Go 的 multipart 上传请求时，读取文件部件元数据的关键不是先把整个文件读进内存，而是先解析 Content-Type 里的 boundary，再交给 multipart.NewReader。随后每次调用 NextPart() 得到一个 *multipart.Part，字段名看 FormName()，文件名看 FileName()，其他元数据从 Part.Header 读取；循环返回 io.EOF 就是正常结束。

先把 Content-Type 的 boundary 交给 Reader

multipart.NewReader 接收两个参数：底层输入和 MIME boundary。HTTP 请求通常把它放在 Content-Type: multipart/form-data; boundary=... 中，稳妥做法是用 mime.ParseMediaType 解析，而不是用字符串切割。这样能同时处理参数转义和媒体类型错误。

package main

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

func readPartMetadata(body io.Reader, contentType string) error {
    // 先解析媒体类型参数，避免手工切割 boundary 造成转义和格式错误。
    mediaType, params, err := mime.ParseMediaType(contentType)
    if err != nil {
        return fmt.Errorf("解析 Content-Type 失败: %w", err)
    }
    // 这里只接受 multipart 媒体类型，并明确拒绝空 boundary。
    boundary := params["boundary"]
    if !strings.HasPrefix(mediaType, "multipart/") || boundary == "" {
        return fmt.Errorf("缺少有效 multipart boundary")
    }

    reader := multipart.NewReader(body, boundary)
    for {
        part, err := reader.NextPart()
        if err == io.EOF {
            return nil // 所有部件的头信息都已读取完毕。
        }
        if err != nil {
            return fmt.Errorf("读取 multipart 部件失败: %w", err)
        }

        // FormName 取字段名，FileName 只在部件带文件名参数时返回值。
        fmt.Printf("field=%q filename=%q content-type=%q\\n",
            part.FormName(), part.FileName(), part.Header.Get("Content-Type"))
        // 只看元数据时不读取正文；下一次 NextPart 会继续推进解析边界。
    }
}

如果代码位于 HTTP handler 中，body 可以传入 request.Body。真实服务还应在进入解析器前设置请求体上限，并把请求标识、字段名和解析错误写入日志，避免把异常请求当成业务数据继续保存。

NextPart 返回什么，哪些字段值得读取

Reader 本质上是 multipart body 的顺序迭代器，不支持回退或随机定位。每次 NextPart 返回一个部件对象，Part.Header 是规范化后的头字段，FormName() 读取 Content-Disposition 中的表单字段名，FileName() 读取文件名参数。

一个常见误区是把文件大小也当作固定元数据。部件可能没有可靠的 Content-Length；如果业务必须限制或统计实际字节数，应在读取正文时使用 io.LimitedReader、计数器或流式落盘，并把大小限制放在 HTTP 层和业务层两处。

线上排查时先区分结束、格式错和超限

值班时可以把错误分成三类：循环拿到 io.EOF 是正常收尾；mime: unexpected content after media subtype 一类错误通常发生在请求头格式不合法；边界缺失、边界不匹配或部件头损坏，则会在 NextPart 读取阶段暴露。不要把所有错误都记录成“没有文件”，否则后续无法判断是客户端漏传还是服务端解析失败。

相关问题

为什么不能直接从 Content-Type 字符串截取 boundary？

因为媒体类型参数可能包含引号、转义或额外参数。使用 mime.ParseMediaType 能把媒体类型和参数分开，并由标准库处理格式细节。

只读取元数据时需要把 Part 全部读完吗？

不需要把正文复制到内存；但解析器仍要继续推进到下一个部件。调用下一次 NextPart 时，标准库会跨过当前部件未消费的内容。

FileName 为空是不是上传失败？

不一定。它只说明当前部件没有可返回的文件名参数，也可能是普通字段或客户端构造的非文件部件；应结合 FormName 和 Content-Disposition 判断。

什么时候应该改用 ReadForm？

需要一次性取得表单字段与文件头集合时可以考虑 ReadForm，但它有内存、临时文件和部件数量边界。只做流式元数据扫描时，NextPart 更容易控制读取范围。

把 boundary、Part 和头字段的职责分开后，multipart 元数据解析就很清楚：请求头负责告诉 Reader 如何分段，Reader 负责顺序返回 Part，业务代码只读取当前部件的必要字段，并对 EOF、格式错误和超限分别记录。