Go multipart.Writer 怎么生成带文件字段的 HTTP 请求体

上传接口需要“文件 + 表单字段”时，Go 的标准库已经给出了完整路径：用 bytes.Buffer 保存请求体，用 multipart.NewWriter 管理边界，用 WriteField 写普通字段，用 CreateFormFile 创建文件字段，最后把 Writer.FormDataContentType() 放进请求头。关键不在于拼接一段看似正确的字符串，而在于让边界、文件资源和 HTTP 请求保持一致。

先划清请求体与文件资源的边界

一个可维护的上传函数通常有三层对象：请求体容器、multipart 编码器和本地文件句柄。multipart.NewWriter 会生成随机 boundary，并把后续字段写到传入的 io.Writer；它并不负责打开文件，也不替你发送 HTTP 请求。这个边界划清后，排错会简单很多：文件打不开属于资源问题，字段创建失败属于编码问题，HTTP 返回错误才属于传输问题。

把普通字段和文件字段写进同一个 Writer

下面的函数只演示请求体的构造，文件名来自调用方传入的展示名，真实项目应先做路径和大小限制。普通字段可以直接调用 WriteField；文件字段则先调用 CreateFormFile("file", "report.csv")，再将 os.File 复制到返回的 writer。每次创建 part 或复制内容都应检查错误，避免把一个不完整的请求体继续交给客户端。

package upload

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

func newUploadRequest(url, path, title string) (*http.Request, error) {
    var body bytes.Buffer
    writer := multipart.NewWriter(&body)

    // 先写普通字段；字段值不会自动替换文件内容。
    if err := writer.WriteField("title", title); err != nil {
        return nil, fmt.Errorf("写 title 字段: %w", err)
    }

    file, err := os.Open(path)
    if err != nil {
        return nil, fmt.Errorf("打开上传文件: %w", err)
    }
    defer file.Close() // 请求构造结束后释放本地文件描述符。

    // CreateFormFile 创建一个带 name 和 filename 的文件 part。
    part, err := writer.CreateFormFile("file", "report.csv")
    if err != nil {
        return nil, fmt.Errorf("创建文件字段: %w", err)
    }
    if _, err := io.Copy(part, file); err != nil {
        return nil, fmt.Errorf("复制文件内容: %w", err)
    }

    // Close 写入结束边界，必须在读取 body 和创建请求前完成。
    if err := writer.Close(); err != nil {
        return nil, fmt.Errorf("关闭 multipart.Writer: %w", err)
    }

    req, err := http.NewRequest(http.MethodPost, url, &body)
    if err != nil {
        return nil, fmt.Errorf("创建 HTTP 请求: %w", err)
    }
    // 让 Writer 提供包含 boundary 的完整 Content-Type。
    req.Header.Set("Content-Type", writer.FormDataContentType())
    return req, nil
}

这里有一个容易忽略的细节：Close 不是关闭本地文件的替代品，它负责完成 multipart 消息；file.Close 负责释放文件资源。两者分别对应不同的生命周期。FormDataContentType 返回的值包含当前 boundary，服务端才能把普通字段和文件字段拆成独立 part。

关闭 Writer 后再绑定 HTTP 的 boundary

如果请求头写成 multipart/form-data，却没有 boundary=...，服务端通常无法解析请求体。反过来，body 已经由某个 Writer 生成，头部却来自另一个 boundary，也会产生同样的问题。正确做法是从同一个 Writer 读取 Content-Type，并在关闭 Writer 后创建请求。

按资产、攻击路径和审计点复查

上传功能的风险不只在 HTTP 语法。最先保护的是本地文件和远端接收接口：path 不应直接来自未限制的用户输入，文件名也不应拿来拼接服务端路径。可在进入这段函数前完成路径白名单、扩展名和大小检查；如果要强制上限，可在复制阶段使用受限 reader，并在超过上限时主动返回错误。

审计日志只记录请求 ID、字段名、文件大小、目标接口和错误阶段，不记录文件内容、Authorization 或完整 multipart body。排错时按“打开文件 → 创建 part → 复制内容 → 关闭 Writer → 创建请求 → 发送请求”的错误标签定位，这些标签比单独记录“上传失败”更有价值。

相关问题

为什么不能自己写 multipart/form-data 的 Content-Type？

因为 boundary 是 body 分隔 part 的关键参数。除非你同时完全控制 boundary 和每个分隔符，否则应直接使用当前 Writer 的 FormDataContentType。

WriteField 和 CreateFormField 有什么区别？

WriteField 创建字段后立即写入字符串；CreateFormField 返回 writer，适合需要分段写入的场景。文件字段则使用 CreateFormFile。

文件很大时还适合 bytes.Buffer 吗？

小文件和中等请求使用 Buffer 简单直观；大文件应评估流式 body、Content-Length、重试和超时策略，避免把整份文件长期留在内存中。无论采用哪种 body，都要保留同一个 boundary 的 Content-Type。

官方参考：mime/multipart、net/http.NewRequest、io.Copy。