Go multipart.Writer.SetBoundary 怎样固定上传请求的边界串

我在对接一个要求固定 multipart 边界的上传接口时，最先踩到的坑不是文件内容，而是请求头和请求体使用了不同的边界串。Go 的 mime/multipart 默认会为 Writer 生成随机 boundary；如果对方协议、签名样例或调试工具要求边界稳定，可以在创建任何 part 之前调用 SetBoundary。

官方地址：https://pkg.go.dev/mime/multipart#Writer.SetBoundary

这篇只解决四件事：什么时候设置 boundary、什么样的 boundary 合法、如何让 Content-Type 与请求体保持一致，以及为什么最后必须调用 Close。

为什么要把默认 boundary 换成固定值

multipart.NewWriter 会创建一个带随机边界的 Writer。随机值对普通上传通常没有问题，但在下面几种场景里，显式值更容易排查：

• 协议文档给出了固定的 multipart 示例，联调时需要复现同一格式；
• 请求签名或测试夹具需要让请求体的分隔符稳定；
• 需要把边界写入日志或抓包摘要，但不想每次运行都变化。

这里的“固定”只代表本次构造请求时使用确定的字符串，并不意味着应该把一个常量永久用于所有业务请求。边界值仍然要避免与字段内容或文件内容意外冲突；如果协议没有特殊要求，让库自动生成通常更省心。

SetBoundary 必须放在创建 part 之前

官方文档对调用时机有明确限制：SetBoundary 必须在创建任何 part 之前调用。CreateFormField、CreateFormFile、CreatePart 和 WriteField 都会进入 part 写入过程，所以不要先写字段再修改边界。

package main

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

func buildBody() (*bytes.Buffer, string, error) {
    body := new(bytes.Buffer)
    writer := multipart.NewWriter(body)

    // 先设置边界，再创建任何字段或文件 part。
    if err := writer.SetBoundary("go-upload-boundary-20261025"); err != nil {
        return nil, "", fmt.Errorf("设置 multipart 边界失败: %w", err)
    }

    // WriteField 会创建字段 part；此时 Writer 已经锁定了边界。
    if err := writer.WriteField("project", "demo"); err != nil {
        return nil, "", fmt.Errorf("写入字段失败: %w", err)
    }

    // Close 写出最后的结束边界，不能省略。
    if err := writer.Close(); err != nil {
        return nil, "", fmt.Errorf("完成 multipart 消息失败: %w", err)
    }
    return body, writer.FormDataContentType(), nil
}

这段代码的关键不是边界字符串本身，而是顺序：创建 Writer、设置边界、写入 part、关闭 Writer。若把 SetBoundary 放到 WriteField 之后，调用会返回错误，应该保留这个错误并停止构造，而不是继续发送半成品。

边界字符串有哪些限制

SetBoundary 返回 error，因为参数不是任意字符串。它必须非空，长度最多为 70 字节，并且只能使用 multipart 允许的 ASCII 字符集合。中文字符即使看起来只有几个字，也可能占用多个字节，不适合作为边界。

// 这些候选值用于展示参数边界，不代表要在生产环境硬编码同一个值。
valid := "go-upload-boundary-20261025"
empty := ""
tooLong := "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

fmt.Println(valid)   // 合法示例：短、可读、只含 ASCII 字符
fmt.Println(empty)   // 非法示例：空字符串会返回错误
fmt.Println(tooLong) // 非法示例：超过 70 字节会返回错误

工程上可以把 boundary 当成一个需要校验的协议参数，而不是把校验责任推给服务端。尤其是边界来自配置文件或外部协议时，先调用 SetBoundary 检查返回值，能在请求发出前发现问题。

Content-Type 要从同一个 Writer 取得

请求头中的 Content-Type 必须带上和请求体完全相同的 boundary。最稳妥的写法是直接使用 writer.FormDataContentType()，不要手动再拼一份字符串。

func newUploadRequest() (*http.Request, error) {
    body := new(bytes.Buffer)
    writer := multipart.NewWriter(body)

    // 固定边界只为复现协议格式；请求头稍后从同一 Writer 读取。
    if err := writer.SetBoundary("go-upload-boundary-20261025"); err != nil {
        return nil, err
    }
    if err := writer.WriteField("name", "report.txt"); err != nil {
        return nil, err
    }
    if err := writer.Close(); err != nil {
        return nil, err
    }

    // FormDataContentType 会把当前 Writer 的 boundary 放入 Content-Type。
    req, err := http.NewRequest(http.MethodPost, "https://upload.example.test/files", body)
    if err != nil {
        return nil, err
    }
    req.Header.Set("Content-Type", writer.FormDataContentType())
    return req, nil
}

上面的地址只是代码中的占位地址，示例没有声称存在对应线上服务。真实项目中应替换为自己的接口地址，并在发送前确认 body 已经完成关闭。若服务端提示 boundary 不匹配，优先检查是否手写了不同的 Content-Type，以及是否在读取 body 前遗漏了 Close。

固定边界和默认边界怎么选

最后记住这条组合关系

固定 multipart 边界时，可以把代码压缩成一句判断：同一个 Writer 决定边界，SetBoundary 先于所有 part，FormDataContentType 写入请求头，Close 写出末尾边界。

如果没有外部协议要求，默认随机值就是合理选择；只有在复现、签名、测试或兼容旧接口时，才值得显式设置。边界固定并不会替你完成文件关闭、请求超时或服务端校验，这些仍然属于上传流程的其他责任。

常见追问

SetBoundary 调用成功后还能再次调用吗？

应把它当作创建 part 前的一次性配置。实际代码里先确定边界，再开始写字段和文件；如果已经产生 part，重新创建 Writer 更清晰。

为什么 Content-Type 不能只写 multipart/form-data？

服务端需要从 Content-Type 参数中知道 body 使用的 boundary。只写媒体类型而不带边界，通常无法正确拆分各个 part。

Close 之后还能继续写字段吗？

不能把关闭后的 Writer 当成可继续追加的消息。Close 的职责是写出尾部边界，完成 body 后再把 buffer 交给 HTTP 请求。