Go multipart.Reader.NextPart 怎样逐段读取表单字段和上传文件

处理 multipart 上传时，multipart.Reader.NextPart 的核心用法是：先从请求头解析 boundary，再在循环中逐个取出 Part；遇到 io.EOF 表示所有分段已经读完，其它错误才是请求解析失败。普通字段可以读取为受限的小文本，文件字段则应该直接把流复制到目标文件，避免把整个上传内容一次性放进内存。

官方地址：https://pkg.go.dev/mime/multipart#Reader.NextPart

如果你需要边接收边处理 multipart 请求体，优先用 NextPart；通过 FormName() 和 FileName() 判断分段类型，并把“正常结束”和“解析失败”分开处理。

先把 boundary 和请求体接起来

multipart.NewReader 需要两个输入：请求体这个 io.Reader，以及 Content-Type 中的 boundary。不要手工截取字符串，应该用 mime.ParseMediaType 读取媒体类型参数。这样既能处理带引号的参数，也能在请求头格式错误时尽早返回。

// parseMultipartReader 从 Content-Type 和请求体创建 multipart.Reader。
// 它只负责解析边界，不读取具体 Part，便于后续按流处理。
func parseMultipartReader(contentType string, body io.Reader) (*multipart.Reader, error) {
    mediaType, params, err := mime.ParseMediaType(contentType)
    if err != nil {
        return nil, fmt.Errorf("解析 Content-Type 失败: %w", err) // 保留原始错误，便于定位请求头问题
    }
    if mediaType != "multipart/form-data" {
        return nil, fmt.Errorf("不支持的媒体类型: %s", mediaType) // 不把普通请求误当成 multipart
    }
    boundary := params["boundary"]
    if boundary == "" {
        return nil, errors.New("Content-Type 缺少 boundary") // 没有边界就无法分割 Part
    }
    return multipart.NewReader(body, boundary), nil
}

如果你的接口还接受 multipart/mixed，可以把媒体类型判断改成按 strings.HasPrefix(mediaType, "multipart/") 处理，但仍要确认 boundary 存在。这里的重点是让边界解析失败在进入循环前暴露出来。

用 NextPart 逐段取出内容

NextPart 返回下一个 *multipart.Part 和错误。读完当前 Part 后再取下一个；没有更多分段时返回 io.EOF。因此，io.EOF 不是上传失败，而是循环的正常出口。

// walkParts 逐段消费 multipart 内容，并把结束与解析错误分开。
// handlePart 必须读完当前 Part，否则下一个边界可能无法正确识别。
func walkParts(mr *multipart.Reader, handlePart func(*multipart.Part) error) error {
    for {
        part, err := mr.NextPart()
        if err == io.EOF {
            return nil // 所有 Part 已经读完，这是正常结束
        }
        if err != nil {
            return fmt.Errorf("读取 multipart Part 失败: %w", err) // 其它错误表示输入或传输异常
        }
        if err := handlePart(part); err != nil {
            return err // 业务处理失败也要停止，避免继续消费未知状态
        }
        if err := part.Close(); err != nil {
            return fmt.Errorf("关闭 Part 失败: %w", err) // 显式处理资源关闭错误
        }
    }
}

判断顺序很重要：先判断 io.EOF，再处理其它错误。读取 Part 的代码也要把内容消费完；对文件分段可以用 io.Copy，对小字段才适合使用受限读取。

按 FormName 和 FileName 分流

FormName() 返回 form-data 的 name 参数；FileName() 非空时通常表示这是上传文件。标准库会对返回的文件名取平台相关的 filepath.Base，但服务端仍然应该把它当作不可信输入，重新选择自己的保存目录和文件名。

// saveParts 演示普通字段与文件字段的不同处理方式。
// 文件内容通过 io.Copy 流式落盘；普通字段使用上限，避免异常请求耗尽内存。
func saveParts(mr *multipart.Reader, uploadDir string) (map[string]string, error) {
    fields := make(map[string]string)
    for {
        part, err := mr.NextPart()
        if err == io.EOF {
            return fields, nil // 读到末尾，返回已经收集的普通字段
        }
        if err != nil {
            return nil, fmt.Errorf("读取分段失败: %w", err)
        }

        formName := part.FormName()
        fileName := part.FileName()
        switch {
        case fileName != "":
            safeName := filepath.Base(fileName) // 只保留末级名称，避免把路径带入保存位置
            dst, err := os.Create(filepath.Join(uploadDir, safeName))
            if err != nil {
                _ = part.Close() // 主错误优先返回，但仍尽力关闭当前 Part
                return nil, fmt.Errorf("创建上传文件失败: %w", err)
            }
            _, copyErr := io.Copy(dst, part) // 按流复制，不把整个文件读入内存
            closeErr := dst.Close()          // 先关闭文件，再决定返回哪个错误
            partErr := part.Close()
            if copyErr != nil {
                return nil, fmt.Errorf("保存上传文件失败: %w", copyErr)
            }
            if closeErr != nil {
                return nil, fmt.Errorf("关闭上传文件失败: %w", closeErr)
            }
            if partErr != nil {
                return nil, fmt.Errorf("关闭文件 Part 失败: %w", partErr)
            }
        case formName != "":
            limited := io.LimitReader(part, 1

示例里的文件名只是演示分流，生产代码还应考虑同名覆盖、扩展名策略、目录权限、配额和临时文件原子替换。若字段内容可能超过上限，应该显式记录“字段过大”，而不是把截断后的文本当作完整值。

哪些边界最容易误判

• 空文件名不等于空文件。有些客户端可能发送没有 filename 的字段；以 FileName() 是否为空区分文件分支时，要结合业务字段名和 Header 判断。
• 当前 Part 没读完就跳到下一个。Part.Read 的数据边界由 multipart 解析器维护，处理函数应消费当前分段，或明确关闭它后再继续。
• 把用户文件名当作路径。保存时使用服务端目录和安全文件名，不能直接拼接客户端提交的完整路径。
• 把 EOF 记成异常。只有 NextPart 返回的 io.EOF 表示正常完成；复制文件时遇到其它读取错误仍要失败。
• 忘记请求体本身的上限。逐段读取不代表自动拥有业务配额，HTTP 层仍应配合请求大小限制、字段大小限制和磁盘配额。

NextPart、NextRawPart 和 ReadForm 怎么选

如果接口的重点是大文件上传、即时校验或边接收边写盘，NextPart 更容易把资源边界放在每个分段附近；如果只是普通的小型表单，ReadForm 的整体结构更方便。

值班式排查清单

1. 先记录 Content-Type 是否包含预期的 multipart 媒体类型和 boundary。
2. 确认每个 Part 都能读完，或在提前放弃时正确关闭。
3. 确认普通字段有大小上限，文件复制有磁盘配额和错误处理。
4. 确认文件名经过安全处理，不把客户端路径写入服务端目录。
5. 把 io.EOF 统计为正常结束，把解析、复制和关闭错误分别记录。

这样处理后，NextPart 的职责就很清晰：它只负责按 multipart 边界提供下一个 Part，业务代码负责识别、消费、限流和持久化。把这几层分开，上传异常会比“一次 ReadForm 后再猜字段”更容易定位。

相关问题

NextPart 返回 io.EOF 是不是上传失败？不是。它表示没有更多 Part；只有同时出现其它错误，或业务处理阶段失败，才需要按失败记录。

为什么大文件不建议对 Part 直接 io.ReadAll？因为读取结果会一次性占用内存，文件大小一旦脱离预期就可能拖垮进程。优先用 io.Copy 写入受控目标。

什么时候要用 NextRawPart？只有在需要保留原始 Content-Transfer-Encoding 语义时才考虑它；普通表单处理通常使用 NextPart 更直接。