Go multipart NextPart 为什么会自动解码 quoted-printable

Go 的 multipart.Reader.NextPart 会把 Content-Transfer-Encoding: quoted-printable 当成一个特殊情况：返回的 Part.Header 里不再保留这个字段，读取 Part 正文时则通过 mime/quotedprintable.Reader 透明解码。它是标准库明确约定的行为，不是上游把正文改坏了。

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

如果业务要做原始消息归档、传输签名校验、字节级哈希或不改写转发，应改用 NextRawPart。它不会隐藏头字段，也不会自动处理 quoted-printable。

我遇到的现象：正文和抓到的原始消息不一样

我第一次碰到这个问题，是在解析一段旧系统产生的 MIME 消息。抓到的 part 正文里明明有 =20，代码读出来却变成了普通空格；再检查 Part.Header，连 Content-Transfer-Encoding 也找不到了。最开始我怀疑中间代理改写了请求，后来把输入缩成下面这段才确定，变化发生在 NextPart 之后。

package main

import (
    "fmt"
    "io"
    "mime/multipart"
    "strings"
)

func main() {
    const body = "--demo\r\n" +
        "Content-Disposition: form-data; name=\"note\"\r\n" +
        "Content-Transfer-Encoding: quoted-printable\r\n\r\n" +
        "Alice=20Smith\r\n" +
        "--demo--\r\n"

    mr := multipart.NewReader(strings.NewReader(body), "demo")
    part, err := mr.NextPart()
    if err != nil {
        panic(err) // 示例中直接终止，业务代码应返回并记录上下文
    }
    defer part.Close() // 及时结束当前 part 的读取

    data, err := io.ReadAll(part)
    if err != nil {
        panic(err)
    }

    // NextPart 隐藏传输编码头，并通过 Read 暴露解码后的正文
    fmt.Printf("header=%q body=%q\n",
        part.Header.Get("Content-Transfer-Encoding"), data)
}

这段代码里，头字段查询结果是空字符串，正文则是 Alice Smith\r\n，而不是输入中的 Alice=20Smith\r\n。因此，不能用 NextPart 的返回值反推线上原始字节。

解码发生在 Part.Read 背后的 reader 包装层

标准库源码里的关键点很少。新建 Part 后，内部 r 默认指向读取原始 part body 的 partReader。当调用的是 NextPart，并且头字段值用不区分大小写的方式匹配到 quoted-printable 时，代码会做两件事：

1. 从 Part.Header 删除 Content-Transfer-Encoding；
2. 用 quotedprintable.NewReader 包装原始 partReader，再把包装后的 reader 赋给 Part.r。

Part.Read 自己没有第二套解码逻辑，它只是调用内部 p.r.Read。所以更准确的说法是：NextPart 在构造 part 时配置透明解码器，字节转换在调用方真正读取正文时发生。只取到 Part 而不读取 body，并不会提前把整段正文解码到内存。

另外，这个特殊分支只针对 quoted-printable。若头字段是 base64 或其他值，NextPart 不会因为同一个机制自动解码；需要调用方按协议和业务要求处理。

要保留原始线上字节就用 NextRawPart

NextRawPart 从 Go 1.14 起提供，文档直接说明它不像 NextPart 那样特殊处理 quoted-printable。把前面的示例改成这个接口，头字段和编码正文都会保留：

package main

import (
    "fmt"
    "io"
    "mime/multipart"
    "strings"
)

func main() {
    const body = "--demo\r\n" +
        "Content-Disposition: form-data; name=\"note\"\r\n" +
        "Content-Transfer-Encoding: quoted-printable\r\n\r\n" +
        "Alice=20Smith\r\n" +
        "--demo--\r\n"

    mr := multipart.NewReader(strings.NewReader(body), "demo")
    part, err := mr.NextRawPart()
    if err != nil {
        panic(err) // 真实服务应把解析错误返回给调用方
    }
    defer part.Close()

    raw, err := io.ReadAll(part)
    if err != nil {
        panic(err)
    }

    // 原始接口保留头字段，正文也仍是 quoted-printable 表示
    fmt.Printf("header=%q body=%q\n",
        part.Header.Get("Content-Transfer-Encoding"), raw)
}

此时头字段仍是 quoted-printable，正文仍包含 =20。这正是签名校验、审计留存和透明代理通常需要的视图。

想保留原文又读取文本，可以手动控制解码

有些服务既要保存原始 body，又要得到业务文本。这时我更喜欢先用 NextRawPart 读取并保存原始字节，再根据保留下来的头字段决定是否解码。这样处理顺序可见，错误也能带上明确上下文。

func decodePart(part *multipart.Part) ([]byte, error) {
    // 先保留传输编码，避免 NextPart 隐藏后无法判断原始表示
    encoding := part.Header.Get("Content-Transfer-Encoding")

    var r io.Reader = part
    if strings.EqualFold(encoding, "quoted-printable") {
        r = quotedprintable.NewReader(part) // 仅在确认编码后包装解码器
    }

    data, err := io.ReadAll(r)
    if err != nil {
        return nil, fmt.Errorf("read multipart body: %w", err)
    }
    return data, nil
}

这个函数适合“先选 NextRawPart，再按业务策略处理”的场景。若还要同时存档原始字节，不能在同一个一次性 reader 上先解码再回头读取；应在读取时写入受限缓冲或归档目标，并控制最大尺寸。对于不可信输入，避免无上限地 io.ReadAll。

为什么 HTTP 表单里很少遇到它

mime/multipart 是通用 MIME multipart 解析器，不只服务浏览器上传。quoted-printable 来自需要适配 7-bit 传输的 MIME 历史场景，因此标准库保留了便利兼容行为。

对现代 HTTP 的 multipart/form-data，RFC 7578 第 4.7 节已经把 Content-Transfer-Encoding 的这种使用列为不推荐：支持二进制的 HTTP 场景里，发送方不应再生成该头字段。也就是说，普通浏览器表单通常不会触发这条分支；邮件、多用途 MIME、旧网关或兼容系统更可能遇到。

规范地址：https://www.rfc-editor.org/rfc/rfc7578.html

接收端仍可能需要兼容旧数据，所以 Go 没有简单删除该行为。排查时要先确认输入究竟是现代 form-data，还是借用了 multipart 结构的通用 MIME 消息。

反向复查时看这几项

• 正文中的 =20、=3D 或软换行是否在读取后发生变化；
• Content-Transfer-Encoding 是否在 Part.Header 中消失；
• 当前代码调用的是 NextPart 还是 NextRawPart；
• 业务比较的是解码内容，还是网络上传输的原始字节；
• 哈希、签名和审计记录是否在任何解码之前生成；
• 读取不可信正文时是否设置尺寸上限并正确处理错误。

如果换成 NextRawPart 后，头字段和编码正文都恢复，原因就已经定位。若依然不同，再检查上游 reader、代理、邮件库或业务中间层是否还做了额外转换。

常见问题

NextPart 会在返回 Part 前把完整正文解码吗？

不会。它在构造 Part 时配置解码 reader，实际转换随着 Part.Read 发生，仍保持流式读取。

头字段值大小写不同还能触发吗？

可以。标准库用 strings.EqualFold 比较值，因此 Quoted-Printable 等大小写变体也会匹配。

NextPart 会自动解码 base64 吗？

不会。这个特殊处理只针对 quoted-printable。其他传输编码需要调用方明确处理。

为什么自动解码后还要删除头字段？

因为返回给调用方的正文视图已经不是该头字段描述的编码表示。隐藏它可以避免调用方再次解码；需要原始语义时应使用 NextRawPart。

NextPart 的自动解码不是隐蔽副作用，而是文档化的 MIME 兼容设计。只消费逻辑正文时，它省去一层样板代码；需要保留线上表示时，NextRawPart 才是更安全的选择。先弄清业务要比较“内容”还是“字节”，接口就不会选错。