Go multipart.Part.FormName 为什么读不到 attachment 的 name 参数

multipart.Part.FormName() 不是通用的 name 参数读取器。它只在该分段的 Content-Disposition 类型为 form-data 时返回 name；对于 attachment，即使头部含有 name 参数，也会返回空字符串。要读取附件头的普通参数，应显式调用 mime.ParseMediaType，再按业务协议解释参数。

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

参数解析文档：https://pkg.go.dev/mime#ParseMediaType

先区分表单字段与通用分段元数据

问题常出现在把“HTTP 表单上传处理”改成“通用 MIME 导入”的时候。原先代码用 FormName 找表单字段，后来接收的分段变成 attachment，开发者在 Header 中明明看到 name，却发现原来的方法返回空值。这两个观察并不矛盾：参数存在是头部的语法事实，能不能把它称为表单字段则取决于分段类型与接口约定。

例如 form-data; name="record" 表示名为 record 的表单字段；attachment; name="record" 中的 name 则需要由接收系统自己的协议说明。不要仅凭参数拼写相同，就让附件进入原有的表单字段分发逻辑。此处讨论的是单个 Part 的 Content-Disposition，外层消息的 Content-Type 是另一个头部。

显式解析 Content-Disposition 并保留错误

若任务是分析不同类型分段的元数据，可以把类型、name 值和“是否存在”分别返回。下面代码是可放入项目的辅助包，入参是已经取得的 Part；它不读取分段正文，也不负责外层消息的边界解析。

package disposition

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

// NameInfo 区分参数缺失和参数存在但为空，避免只靠空字符串判断。
type NameInfo struct {
    Kind string
    Name string
    Present bool
}

func ReadName(p *multipart.Part) (NameInfo, error) {
    if p == nil { return NameInfo{}, fmt.Errorf("分段为空") }
    raw := p.Header.Get("Content-Disposition")
    if raw == "" { return NameInfo{}, fmt.Errorf("缺少 Content-Disposition") }
    kind, params, err := mime.ParseMediaType(raw)
    // 参数语法错误时不能继续把部分解析结果当作完整元数据。
    if err != nil { return NameInfo{}, fmt.Errorf("解析分段描述: %w", err) }
    name, present := params["name"]
    return NameInfo{Kind: kind, Name: name, Present: present}, nil
}

func RequireFormField(p *multipart.Part) (string, error) {
    info, err := ReadName(p)
    if err != nil { return "", err }
    // 这里只接收表单字段，不把附件的同名参数自动映射成表单字段。
    if info.Kind != "form-data" {
        return "", fmt.Errorf("不接受分段类型 %q", info.Kind)
    }
    if !info.Present || info.Name == "" {
        return "", fmt.Errorf("表单字段缺少非空 name")
    }
    return info.Name, nil
}

ReadName 用于通用元数据解析，RequireFormField 则明确实现“只接受表单字段”的约束。前者能读到 attachment 的 name，不代表后者也应该接受它。ParseMediaType 会规范化类型和参数名的大小写，参数值保留自身大小写，因此不要对完整头部先做 ToLower，否则可能改变业务标识。

FormName 返回的只有字符串，无法通过返回值区分类型不适用、缺少 name 或 name 为空等情况。需要错误诊断时，使用带 error 的解析函数能保留问题所在；检查 err 后再使用解析结果，不要把错误降级为一个默认字段名。

按接口契约决定接受还是拒绝

对于只服务浏览器表单的接口，应修正发送端，使它按照接口要求发送 form-data，并继续拒绝不符合约定的分段。对于邮件导入或自定义 multipart 消息，应用层应保存解析出的 kind，再决定 attachment 元数据可以进入哪些业务分支；是否赋予 name 特殊意义，由自己的协议确定。

兼容逻辑最好集中在单一入口，避免一部分调用方使用 FormName，另一部分调用方直接取 map，却把两者视作完全相同的字段来源。记录诊断信息时可记录归一化的类型与错误类别，业务 name 的记录应遵循项目的数据处理约定。

避免用字符串切割或改头掩盖问题

不要通过 Split(";") 或字符串查找截取 name。引号中的分号、转义和参数语法会让这类实现产生歧义，使用标准解析器比自己猜测分隔符更明确。也不要把 attachment 字符串替换成 form-data 只为让 FormName 返回非空，那会抹掉来源类型，造成接收策略与原始消息不一致。

另一个容易混淆的点是 name 与 filename：前者不能自动作为后者的替代，更不能因为头部中存在某个参数就认定它属于表单字段。本文的适配层只返回 name 元数据，不承担存储命名、路径选择或文件内容判断。

相关问题与落地清单

attachment 的 name 为空，是正文还没读取吗？不是。这里的方法读取分段头的语义，读取正文不会把 attachment 变成 form-data。先确认取的是当前 Part 的头部，再确认接口接受的分段类型。

name="Record" 会变成小写吗？ParseMediaType 规范化的是类型和参数名，参数值的大小写仍被保留。业务比较是否忽略大小写，应由字段协议决定。

能直接修改 Part.Header 后继续调用 FormName 吗？不建议把这种写法作为适配方案。应在原始头部上独立解析并保存类型，再由自己的处理函数做映射，避免依赖便利方法的内部状态与调用时机。

落地时先明确接收的是表单还是通用消息，再决定使用便利方法还是通用参数解析；错误、参数缺失和业务拒绝分别处理。这样既能解释 attachment 中 name 看得见却读不到的现象，也能让后续兼容逻辑保持可控。