Go net/textproto 出错时怎么排查非法字段

用 net/textproto 的 ReadMIMEHeader 读取文本协议头部时，如果看到 malformed MIME header line，通常不是 MIMEHeader map 本身坏了，而是输入行没有通过“字段名、冒号、字段值”的边界检查。排查时先保留出错原文，再区分缺少冒号、字段名含非法字符、字段值含控制字节，以及首行错误缩进。

为什么会出现“malformed MIME header line”

ReadMIMEHeader 逐行读取可能带折行的头部，直到遇到空行。普通字段至少要能拆成 字段名: 字段值；如果一行没有冒号，源码会报 malformed MIME header: missing colon。有冒号也不代表一定合法：字段名会经过 token 字符检查，字段值还要经过字节检查。

首行还有一个容易漏掉的边界：它不能以空格或制表符开头。后续行以空格或制表符开头，才可能被当作上一字段的延续。把整段数据先 TrimSpace 再解析，反而可能掩盖协议错误，甚至改变字段值的含义。

先把非法字段拆成四种情况

不要只盯着错误字符串中的“非法字段”。可以按下面的清单定位：

字段名的合法字符集合来自 HTTP token 规则，常见的字母、数字、连字符和下划线都可以；空格、冒号和多数控制字符不能当作普通字段名字符。需要注意一个兼容性细节：源码允许“冒号前有空格”的旧式输入，但不会对它做规范化。若你在做严格协议网关，仍应在适配层明确拒绝这类输入，而不是依赖自动整理。

用最小诊断代码定位原始输入

复现时不要先把每一行拆成 map。让 ReadMIMEHeader 接收原始字节，并在错误路径把行内容按可见转义和十六进制各打印一次，这样中文、制表符、NUL 等问题不会在日志里“消失”。下面的输入把 @ 放进字段名，专门演示字段名校验边界。

package main

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

func main() {
	// 保留协议适配层收到的原始头部，末尾空行表示头部结束。
	raw := "Trace-Id: abc123\nBad@Name: value\n\n"
	reader := textproto.NewReader(bufio.NewReader(strings.NewReader(raw)))

	header, err := reader.ReadMIMEHeader()
	if err != nil {
		// %q 展示转义字符，% x 展示不可见字节，便于区分空格和控制字节。
		fmt.Printf("parse failed: %v\nraw bytes: %q\nhex: % x\n", err, raw, []byte(raw))
		return
	}
	fmt.Printf("parsed headers: %#v\n", header)
}

这段代码的重点不是“把坏字段过滤掉”，而是保留输入证据。实际服务中还应给原始行设置长度上限，避免把整段敏感请求内容写进日志；排查结束后，再把同一个最小样例加入协议适配层的回归测试。

规范化只能处理大小写，不能替代校验

CanonicalMIMEHeaderKey 会把 content-type 规范成 Content-Type，也会处理连字符后的首字母。它的职责是统一合法键的写法，不是把 Bad@Name、带控制字节的字符串变成可发送的字段。

因此修复顺序应放在生成头部的一侧：先保证字段名来自固定白名单或经过 token 检查，再写入字段值；读取侧只负责报告错误和停止使用不完整结果。若错误来自第三方服务，优先记录原始行、连接方向和协议上下文，再针对该服务做窄范围兼容，不要全局删除字符。

相关问题

字段名大小写不同会触发错误吗？

不会。合法字段名的大小写会被 MIMEHeader 的访问方法按规范形式处理；大小写不一致通常不是“非法字段”原因。

为什么 map 里已经有字段，函数仍然返回 error？

前面的行可能已经被读入，后面的某一行才失败。调用方应以 error 为准，不要把部分 map 当成完整头部继续执行业务逻辑。

能不能直接用 strings.TrimSpace 修复？

不建议。它会同时改变字段值两端的空白，正确做法是定位产生非法字节的上游边界，只清理协议明确允许忽略的空白。