Go multipart.SetBoundary 为什么必须在创建 Part 前调用

在 Go 中手动控制 multipart/form-data 的分隔符，关键不是把 SetBoundary 放在“创建 Writer 之后”这么简单，而是必须早于第一个 Part。因为 Part 一旦创建，Writer 就已经开始组织正文边界；这时再替换分隔符，容易得到错误返回，或者让调用方误以为请求头已经同步。

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

一、先看 boundary 与 Part 的关系

multipart 正文由多个 Part 组成，Part 之间靠 boundary 分隔。multipart.NewWriter 会先生成一个随机 boundary；Boundary() 可以读取它，FormDataContentType() 则会把它带入 Content-Type 参数。正文和请求头必须引用同一个值，服务端才能找到每个字段的起止位置。

SetBoundary 不是给某个字段设置属性，而是修改整个 Writer 的边界配置。文档明确要求它在创建任何 Part 前调用，因此下面这些方法都算“开始使用边界”：CreateFormField、CreateFormFile、CreatePart 和间接调用它们的 WriteField。

二、把 SetBoundary 放在第一个 Part 前

可靠顺序是：创建 Writer，立即设置边界，检查错误，然后再创建字段或文件 Part。下面的示例还保留了 Close，因为它负责写入 multipart 正文的结束边界。

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

// 自定义边界必须在任何 Part 创建前设置，并检查参数错误。
if err := writer.SetBoundary("----upload-boundary-20260928"); err != nil {
    return err
}

// WriteField 会间接创建一个字段 Part，因此它也必须位于 SetBoundary 之后。
if err := writer.WriteField("project", "demo"); err != nil {
    return err
}

filePart, err := writer.CreateFormFile("archive", "demo.zip")
if err != nil {
    return err
}
// 示例只展示组装顺序；真实场景应把文件内容写入 filePart 并检查写入错误。
if _, err := io.Copy(filePart, file); err != nil {
    return err
}

// Close 写入结束边界，必须在读取 body 或发起请求前完成。
if err := writer.Close(); err != nil {
    return err
}

这里的重点是“第一个 Part 前”，而不是“第一个字段前”。如果先调用 WriteField，再调用 SetBoundary，已经错过了安全时机；如果 SetBoundary 返回错误，也不要继续发送半成品正文。

三、让请求头与正文使用同一个 boundary

不要从自定义字符串再次拼接请求头。Writer 已经知道最终边界，直接使用 FormDataContentType 最稳妥；它会生成类似 multipart/form-data; boundary=... 的值，并与后续写入正文的分隔符保持一致。

req, err := http.NewRequest(http.MethodPost, endpoint, &body)
if err != nil {
    return err
}

// 请求头从同一个 Writer 读取 boundary，避免头部和正文各用一套值。
req.Header.Set("Content-Type", writer.FormDataContentType())

resp, err := http.DefaultClient.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close() // 及时释放响应体连接。
if resp.StatusCode = 300 {
    return fmt.Errorf("upload failed: %s", resp.Status)
}

如果服务端提示缺少字段、找不到文件或正文解析失败，先打印或记录请求头中的 boundary 长度，再确认正文确实由同一个 Writer 写出。最常见的错误不是服务端字段名，而是头、体使用了不同边界。

四、用参数和调用顺序排查失败

排查时可以按“位置—参数—头体一致性—关闭结果”四层收敛。不要先修改服务端解析器，也不要把随机生成的 boundary 和自定义 boundary 混用；先保证 Writer 的生命周期只有一个清晰来源。

相关问题

不调用 SetBoundary 可以吗？

可以。NewWriter 会生成随机边界，普通上传场景直接使用它更省心，仍需用 FormDataContentType 设置请求头。

为什么 boundary 不能超过 70 字节？

这是 multipart Writer 对边界格式的约束。业务标识应保持短小，长度判断按字节而不是中文字符数进行。

SetBoundary 成功后还需要调用 Close 吗？

需要。SetBoundary 只修改分隔符，Close 才负责写入正文结束边界；两者解决的是不同问题。