Go multipart.Writer 怎么使用指定 boundary

Go 的 multipart.NewWriter 默认会生成随机 boundary。确实需要固定值时，应在创建任何字段或文件 part 之前调用 SetBoundary，之后用 FormDataContentType() 生成请求头。最小写法如下：

var body bytes.Buffer
mw := multipart.NewWriter(&body)

// 必须在 WriteField、CreateFormFile 或 CreatePart 之前设置
if err := mw.SetBoundary("GoBoundary2026"); err != nil {
    return err
}

普通上传请求通常不需要指定 boundary，保留随机值最省心。固定 boundary 主要用于协议兼容、可重复测试样例、请求签名或外部系统明确给出分隔符的场景。

官方文档：https://pkg.go.dev/mime/multipart

项目目标：构造一个固定 boundary 的上传请求

这个小项目把一个文本字段和一个内存文件写入 multipart/form-data，再生成可直接交给 http.Client 的请求。指定值使用 GoBoundary2026，调用方无需手写正文分隔线。

标准库对自定义 boundary 有三个直接约束：不能为空、最长 70 字节、只能包含允许的 ASCII 字符。传入值不要带开头的两个连字符，multipart.Writer 会在正文中自动写入 --boundary 分隔线。

环境准备：只使用标准库

示例不依赖第三方包。创建一个普通 Go 模块即可：

# 创建独立示例模块
mkdir multipart-boundary-demo
cd multipart-boundary-demo
go mod init example.com/multipart-boundary-demo

真正接入项目时，把下面的构造函数放进 HTTP 客户端或上传服务包中。函数返回请求和错误，便于调用方统一处理超时、重试和响应状态。

核心代码：先设置 boundary 再创建字段

package upload

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

func NewUploadRequest(url string, boundary string, filename string, data []byte) (*http.Request, error) {
    var body bytes.Buffer
    writer := multipart.NewWriter(&body)

    // boundary 必须在创建任何 part 之前设置
    if err := writer.SetBoundary(boundary); err != nil {
        return nil, fmt.Errorf("设置 multipart boundary: %w", err)
    }

    // 写入普通表单字段
    if err := writer.WriteField("category", "document"); err != nil {
        return nil, fmt.Errorf("写入 category 字段: %w", err)
    }

    // 创建文件 part，随后把内存中的文件内容写进去
    filePart, err := writer.CreateFormFile("file", filename)
    if err != nil {
        return nil, fmt.Errorf("创建文件字段: %w", err)
    }
    if _, err := filePart.Write(data); err != nil {
        return nil, fmt.Errorf("写入文件内容: %w", err)
    }

    // Close 会写入 multipart 正文末尾的 closing boundary
    if err := writer.Close(); err != nil {
        return nil, fmt.Errorf("结束 multipart 正文: %w", err)
    }

    req, err := http.NewRequest(http.MethodPost, url, &body)
    if err != nil {
        return nil, fmt.Errorf("创建 HTTP 请求: %w", err)
    }

    // 让标准库把同一个 boundary 填入 Content-Type
    req.Header.Set("Content-Type", writer.FormDataContentType())
    return req, nil
}

调用顺序是最关键的边界。SetBoundary 不是对已经写出的正文做替换；Writer 一旦开始创建 part，分隔线已经参与编码，此时再改 boundary 会返回错误。

请求头必须和正文使用同一个 boundary

接收端根据 Content-Type 的 boundary 参数拆分正文。如果请求头写的是 A，而正文分隔线使用 B，服务端通常会把请求判定为格式错误或读取不到字段。

req, err := NewUploadRequest(
    "https://upload.example.test/files",
    "GoBoundary2026",
    "report.txt",
    []byte("example content"),
)
if err != nil {
    return err // 将构造错误交给上层记录
}

// 不要手写 Content-Type；构造函数已使用 FormDataContentType 设置
resp, err := client.Do(req)
if err != nil {
    return fmt.Errorf("发送上传请求: %w", err)
}
defer resp.Body.Close() // 及时释放连接资源

writer.Boundary() 可以读取当前 boundary；writer.FormDataContentType() 则返回完整的 multipart/form-data; boundary=...。后者会在需要时正确引用参数，因此应直接用于请求头。

集成大文件上传时改用流式写入

bytes.Buffer 会把整个请求体放在内存里，适合小文件和测试。大文件可把底层输出换成 io.Pipe，在写协程中建立同样的 multipart.Writer 并先调用 SetBoundary。固定 boundary 的规则不变，但写入错误要通过 CloseWithError 传给读取端。

pr, pw := io.Pipe()
writer := multipart.NewWriter(pw)

// 在启动 part 写入前固定 boundary
if err := writer.SetBoundary("GoBoundary2026"); err != nil {
    pw.CloseWithError(err)
    return err
}

go func() {
    defer pw.Close() // 所有 part 完成后关闭管道写端

    part, err := writer.CreateFormFile("file", filename)
    if err != nil {
        pw.CloseWithError(err)
        return
    }
    if _, err := io.Copy(part, src); err != nil {
        pw.CloseWithError(err)
        return
    }
    if err := writer.Close(); err != nil {
        pw.CloseWithError(err) // 传递末尾 boundary 写入失败
    }
}()

流式版本中，请求头仍然取自同一个 writer.FormDataContentType()。还应由调用方设置 Context 超时，避免远端长期不读导致写协程阻塞。

验收：检查三类最常见错误

单元测试可以读取请求的 Content-Type，用 mime.ParseMediaType 取得 boundary，再用 multipart.NewReader 解析正文。这样检查的是协议结构，而不是依赖整段原始文本的脆弱字符串比较。

常见问题

自定义 boundary 需要包含两个短横线吗？

不需要。传给 SetBoundary 的是参数值本身，Writer 会在正文分隔行前自动添加两个短横线。

为什么 SetBoundary 必须在 CreateFormFile 之前？

创建第一个 part 时 Writer 就会写出使用当前 boundary 的分隔线。之后修改会让已写正文与后续内容不一致，因此标准库拒绝该操作。

可以直接写 Content-Type 而不调用 FormDataContentType 吗？

技术上可以，但容易漏引号或写错 boundary。直接使用 FormDataContentType() 能保证请求头与 Writer 当前配置一致。

固定 boundary 会让上传更安全吗？

不会。boundary 只负责分隔 MIME part，不是密钥、签名或授权机制。认证、完整性校验和传输安全仍要由 HTTPS、凭据和协议签名负责。