Go multipart.Writer 怎么固定边界便于接口签名

如果 Go 客户端把 multipart/form-data 请求体直接拿去做 HMAC 签名，最容易忽略的变量是 boundary。multipart.NewWriter 默认会生成随机边界，同样的字段可能因此得到不同的原始字节。解决办法是：创建 Writer 后立刻调用 SetBoundary，随后按固定顺序写入字段，调用 Close 补齐尾部边界，最后再对完整 body 签名。

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

签名为什么会因为 boundary 变化而失效

multipart 报文会在每个字段前后写入类似 --boundary 的分隔线，末尾还会追加结束标记。默认随机 boundary 每次不同，哪怕字段值完全一样，body 的哈希也会变化。接口签名验证的是字节序列，不会因为“解析后字段相同”就把两个请求视为相同。

排查时先把不稳定来源分成四类：boundary 是否变化；字段和文件的写入顺序是否变化；请求头里的 Content-Type 是否引用了同一个 boundary；签名是否发生在 Close 之前。只改 boundary 而忽略最后一项，仍然会少签名一段尾部边界。

SetBoundary 的调用位置和参数边界

SetBoundary 要紧跟在 NewWriter 后面。只要调用过 CreateFormField、CreateFormFile、CreatePart 或间接写入字段，就不应再修改边界。边界必须是非空字符串，最长 70 个字节，并且只能使用该 API 接受的 ASCII 字符集合；不要把中文、空格或未处理的用户输入直接拼进去。

package signer

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "fmt"
    "mime/multipart"
)

const fixedBoundary = "----17golang-signature-v1"

func buildBody(userID, note string, fileBytes []byte) ([]byte, string, error) {
    var buf bytes.Buffer
    writer := multipart.NewWriter(&buf)

    // 必须在创建任何 part 之前固定分隔符，并处理非法边界错误。
    if err := writer.SetBoundary(fixedBoundary); err != nil {
        return nil, "", fmt.Errorf("设置 multipart boundary: %w", err)
    }

    // 字段写入顺序属于序列化协议的一部分，后续调用保持不变。
    if err := writer.WriteField("user_id", userID); err != nil {
        return nil, "", fmt.Errorf("写入 user_id: %w", err)
    }
    if err := writer.WriteField("note", note); err != nil {
        return nil, "", fmt.Errorf("写入 note: %w", err)
    }

    part, err := writer.CreateFormFile("file", "payload.bin")
    if err != nil {
        return nil, "", fmt.Errorf("创建文件 part: %w", err)
    }
    // 文件字节必须在签名前完整写入，不能只签名元数据。
    if _, err := part.Write(fileBytes); err != nil {
        return nil, "", fmt.Errorf("写入文件 part: %w", err)
    }

    // Close 会追加最终边界；签名必须使用 Close 之后的完整 body。
    if err := writer.Close(); err != nil {
        return nil, "", fmt.Errorf("完成 multipart body: %w", err)
    }
    return buf.Bytes(), writer.FormDataContentType(), nil
}

func sign(secret, contentType string, body []byte) []byte {
    mac := hmac.New(sha256.New, []byte(secret))
    // Content-Type 中的 boundary 与 body 必须属于同一次构造结果。
    _, _ = mac.Write([]byte(contentType + "\n"))
    _, _ = mac.Write(body)
    return mac.Sum(nil)
}

示例把 Content-Type 和最终 body 一起交给签名函数。真实接口若规定签名串还包含时间戳、路径或 nonce，应按服务端协议固定拼接顺序；不要为了“让签名稳定”删掉服务端要求的字段。

字段顺序、Close 和 Content-Type 要一起固定

固定 boundary 后，第二个常见误区是把 multipart 当成无序 Map。Go 的 Writer 会按调用顺序生成 part，因此 user_id 和 note 的先后变化也会改变 body。建议把构造过程收拢到一个函数，不让不同业务分支自行写入相同字段。

不要手写 Content-Type: multipart/form-data 而省略 boundary，也不要从固定常量重新拼一个可能不一致的头。FormDataContentType 会引用当前 Writer 的边界，配合同一个 body 返回给 HTTP 客户端即可。

出现签名不一致时按原始字节定位

先记录本地构造出的 boundary、Content-Type、body 长度和 body 哈希，不要把密钥写入日志。然后和服务端约定的样本逐项比较：如果第一处差异就在开头，多半是 boundary 或头部；如果差异出现在字段之间，检查顺序、字段名和编码；如果前面都一致而末尾不同，优先检查是否漏掉 Close。

还要区分“请求体稳定”和“请求可重放”。固定 boundary 可能让同一业务数据得到相同摘要，但生产签名通常仍应加入时间戳、一次性 nonce 或服务端保存的幂等键。签名协议若要求每次请求时间不同，就不应为了追求全请求字节相同而删除这些防护字段。

常见问题

SetBoundary 能在 WriteField 之后调用吗？

不能。它应在创建任何 part 之前调用；把调用放在第一个字段之后，通常会得到错误，且即使边界未变也说明构造顺序不可靠。

只固定 boundary 就能保证签名一致吗？

不能。字段顺序、文件名、字段值编码、Content-Type、Close 是否执行以及签名串拼接规则都必须一致。

为什么签名 body 不能在 Close 前读取？

因为 Close 负责写入 multipart 的最终结束边界。提前读取会漏掉尾部字节，服务端拿完整请求体验签时自然不一致。

结论

Go multipart 接口签名的稳定做法是把 Writer 当成一个小型序列化协议：先固定合法 boundary，再按固定顺序写入所有 part，使用同一个 Writer 生成 Content-Type，Close 后对完整 body 计算签名。这样解决的是可重复编码问题；时间戳、nonce、幂等和防重放仍要按接口协议单独设计。