Go textproto.Reader.ReadMIMEHeader 怎样处理折行邮件头

处理邮件、SMTP 或其他文本协议时，头部不一定是一行一个字段。textproto.Reader.ReadMIMEHeader 会读取一组以空行结束的 Key: Value 行；如果下一行以空格或制表符开头，它会被当作上一字段的折行内容，并入同一个值。真正需要留意的是：同名字段不会被覆盖，而是按输入顺序保存在 []string 中。

本文只围绕 net/textproto 的 MIME 头读取：如何读取折行、怎样保留重复字段、哪些输入会返回协议错误，以及生产代码如何给底层读取设置大小边界。

先看懂 ReadMIMEHeader 的输入边界

一个 MIME 头由若干个 Key: Value 字段组成，遇到空行就结束。续行必须以空格或制表符开头，例如 Long-Key: first 的下一行如果是缩进文本，就会被拼到同一个值里，中间保留一个空格。头部结束后的正文不会被当作新的字段。

字段名会按 CanonicalMIMEHeaderKey 的规则整理，值则按出现顺序放在 MIMEHeader 的切片中。也就是说，重复的 Set-Cookie、Received 或自定义字段不能只用一个字符串变量接收，否则会丢掉后面的值。

用 MIMEHeader 读取折行和重复字段

调用方式很直接：把输入包装成 bufio.Reader，再交给 textproto.NewReader。下面的示例使用内存字符串表示一段协议头，重点是观察返回值的结构，不把示例输出当成运行截图。

package main

import (
    "bufio"
    "fmt"
    "strings"
    "net/textproto"
)

func main() {
    input := "X-Trace: first\r\n" +
        "X-Trace: second\r\n" +
        "Long-Note: hello\r\n" +
        "    world\r\n" +
        "\r\n"

    // NewReader 只负责把缓冲读取器交给 textproto；头部总量边界要由上层设置。
    reader := textproto.NewReader(bufio.NewReader(strings.NewReader(input)))
    header, err := reader.ReadMIMEHeader()
    if err != nil {
        // 解析失败时不要继续使用不完整的头部结果。
        panic(err)
    }

    // Get 适合只关心第一个值，Values 才能保留同名字段的完整顺序。
    fmt.Println("第一个 X-Trace:", header.Get("X-Trace"))
    fmt.Println("全部 X-Trace:", header.Values("X-Trace"))
    fmt.Println("折行后的 Long-Note:", header.Get("Long-Note"))
}

这个例子里的 X-Trace 会对应两个值，Long-Note 会得到合并后的文本。实际业务中，如果字段允许重复，优先使用 Values；只有协议明确规定最多取一个值时，才使用 Get。

哪些格式问题会返回协议错误

排查时先把错误分成“输入不符合头部语法”和“底层读取结束”两类。MIME 头的第一行不能以空格或制表符开头，因为它没有可归属的上一字段；普通字段行需要包含冒号，字段名还必须满足允许的头部字符规则。遇到非法字节时，解析也会返回协议错误。

func readHeader(input string) (textproto.MIMEHeader, error) {
    // 让调用方传入完整的头部文本，空行表示头部结束。
    reader := textproto.NewReader(bufio.NewReader(strings.NewReader(input)))
    header, err := reader.ReadMIMEHeader()
    if err != nil {
        // 上层应记录 err，并把输入归类为协议格式错误或读取失败。
        return nil, err
    }
    return header, nil
}

// 下面这些输入都不应被当作正常字段：
// "  orphan continuation\r\n\r\n"：首行没有可续接的字段。
// "MissingColon\r\n\r\n"：字段行缺少冒号。
// "Name: value\r\n"：没有空行时，结束位置取决于底层读取是否返回 EOF。

不要只检查 header 是否非空就认为解析成功。发生格式错误时，返回的映射可能已经收集了前面的部分字段；只有 err == nil 才表示这一段头部完整结束。对外部输入还要区分“对端正常提供了空头部”和“连接在空行前意外结束”。

生产代码要给底层读取设置边界

ReadMIMEHeader 的公开方法面向通用文本协议，调用方应在创建 bufio.Reader 前考虑输入是否来自不可信连接。官方文档建议用 io.LimitReader 或类似方式限制响应大小，避免对端持续发送超大头部。这个限制属于传输层资源策略，不是把折行规则改成另一套。

func readBoundedHeader(src io.Reader, maxBytes int64) (textproto.MIMEHeader, error) {
    // 限制整个头部输入的可读范围，具体上限应由协议和业务容量决定。
    limited := io.LimitReader(src, maxBytes)
    reader := textproto.NewReader(bufio.NewReader(limited))

    // ReadMIMEHeader 仍按空行、折行和冒号规则解析内容。
    header, err := reader.ReadMIMEHeader()
    if err != nil {
        // 达到上限或输入提前结束时，把错误交给调用方统一处理。
        return nil, err
    }
    return header, nil
}

这里的边界要和具体协议配套：如果业务只需要 HTTP 请求头，通常直接使用 net/http 的服务器栈；如果处理 MIME multipart，也应遵循对应包对头部数量和内存的限制。直接调用 ReadMIMEHeader 更适合自定义文本协议、测试输入或已经明确控制了上游读取范围的场景。

小结

ReadMIMEHeader 把空行前的 MIME 头解析成 MIMEHeader：空格或制表符开头的行属于上一字段的折行，同名字段按顺序保留，Get 取第一个值而 Values 取全部值。首行缩进、缺少冒号和非法头字节属于协议格式错误；外部输入则应在底层 Reader 上设置大小上限，并在 err == nil 后再使用完整结果。

相关问题

折行字段会生成一个新的 MIMEHeader 键吗？不会，只要该行以空格或制表符开头，它会并入上一字段的值。

同名字段用 Get 还是 Values？需要保留全部值时用 Values；Get 只返回第一个值。

为什么首行不能以空格开头？因为折行必须依附于前一字段，首行没有可依附的字段。

ReadMIMEHeader 会自动限制头部大小吗？通用公开方法不替你决定业务上限；应在底层 Reader 上用 io.LimitReader 或类似策略设置边界。