Go mime.FormatMediaType 怎么安全生成带参数的 Content-Type

在 Go 中，只要需要拼出带参数的 Content-Type 或 Content-Disposition，就不建议把参数直接接在字符串后面。mime.FormatMediaType 会把媒体类型和参数 map 按 MIME 规则序列化，自动处理参数名小写、参数顺序、引号和必要的百分号编码；如果输入本身违反格式规则，则返回空字符串。

最小用法是传入基础媒体类型和参数 map，再检查返回值是否为空。不要把空字符串当成一个可发送的 Header 值，也不要用手写字符串替代库的转义逻辑。

为什么不要手写 Content-Type 参数

简单的 text/plain; charset=utf-8 看起来没有问题，但参数值一旦包含空格、双引号、反斜杠或非 ASCII 字符，手写拼接就要自己决定何时加引号、如何转义和怎样编码。遗漏一个边界字符，生成的字符串就可能无法被另一个 MIME 解析器正确读取。

FormatMediaType 会先检查媒体类型和参数名是否是合法 token，再根据值的形态选择不加引号、双引号字符串或 RFC 2231 风格的扩展参数。它还会把参数名统一为小写，并按参数名排序，让同一组输入得到稳定输出。

用 mime.FormatMediaType 生成基础字符串

基础场景只需要准备类型和参数。下面的示例没有发送 HTTP 请求，只演示如何得到一个可以继续交给 Header 层的字符串。

package main

import (
	"fmt"
	"mime"
)

func main() {
	// 参数名可以来自业务配置，FormatMediaType 会统一规范化它们。
	params := map[string]string{
		"Charset": "utf-8",
		"boundary": "batch_7f3a",
	}

	// 函数负责序列化，不负责发送请求；空字符串表示输入违反媒体类型规则。
	result := mime.FormatMediaType("Multipart/Form-Data", params)
	if result == "" {
		panic("invalid media type or parameter")
	}

	fmt.Println(result)
}

multipart/form-data; boundary=batch_7f3a; charset=utf-8

参数 map 的遍历顺序不会影响结果，因为函数会按参数名排序。这样既避免了业务代码手工拼接分号，也让日志、缓存键或测试快照中的结果更加稳定。

空格、引号和中文参数值怎么处理

值是普通 token 时可以直接输出；值含空格时需要 quoted-string；值含中文等非 ASCII 内容时，标准库会使用带 * 的扩展参数并进行 UTF-8 百分号编码。调用方只需要传入原始字符串，不要提前手工加双引号或编码。

package main

import (
	"fmt"
	"mime"
)

func main() {
	params := map[string]string{
		// 空格会触发带双引号的参数值，而不是让调用方手动加引号。
		"note": "monthly report",
		// 非 ASCII 文件名会走扩展参数编码，保留原始中文即可。
		"filename": "月度报告.csv",
		// 引号和反斜杠由库负责转义，避免出现未闭合的参数值。
		"remark": `a "quoted" path\\name`,
	}

	formatted := mime.FormatMediaType("text/csv", params)
	if formatted == "" {
		panic("invalid media parameter")
	}
	fmt.Println(formatted)
}

这里的重点不是记住某个具体输出顺序，而是把输入保持为业务语义。若代码先自行加引号，再交给 FormatMediaType，双引号可能被再次转义，解析回来的值也会多出不需要的字符。

哪些输入会让结果变成空字符串

返回空字符串通常不是“没有参数”的意思，而是输入触碰了规范边界。例如媒体类型缺少合法的类型 token，参数名含控制字符，或类型和子类型中出现不允许的字符。调用方应在构造 Header 前立即判断。

package main

import (
	"fmt"
	"mime"
)

func formatContentType(mediaType string, params map[string]string) (string, error) {
	// 统一在边界函数检查空结果，避免把无效值继续传给 Header。
	formatted := mime.FormatMediaType(mediaType, params)
	if formatted == "" {
		return "", fmt.Errorf("invalid media type %q", mediaType)
	}
	return formatted, nil
}

func main() {
	value, err := formatContentType("text/plain", map[string]string{"charset": "utf-8"})
	if err != nil {
		// 生产代码可将错误交给调用方或记录上下文，不要静默使用空值。
		panic(err)
	}

	// ParseMediaType 适合做结构化回读，确认类型和参数是否能被解析。
	mediaType, params, err := mime.ParseMediaType(value)
	if err != nil {
		panic(err)
	}
	fmt.Println(mediaType, params["charset"])
}

ParseMediaType 与格式化函数是互补关系：前者把字符串拆成媒体类型和参数，后者把结构重新序列化。它们不能替代业务层的协议检查，但适合放在构造函数和单元测试中，及时发现空值、重复参数或不符合预期的输出。

常见误区与速查

最后记住边界：本文只讨论媒体类型字符串的生成与解析，不负责 HTTP 请求发送、multipart body 构造或服务端业务校验。把格式化封装在一个小函数里，并对空结果做显式处理，通常就能消除大多数手写参数拼接问题。

相关问题

FormatMediaType 会保留参数名大小写吗？不会，文档约定类型名和参数名会写成小写，参数值本身按输入语义处理。

为什么返回值里出现参数名后缀 *？这通常表示值需要按扩展参数规则表达，例如包含非 ASCII 字符；不要把它当成业务字段名错误。

可以用它生成完整的 multipart 请求体吗？不可以。它只负责媒体类型及参数的序列化，正文边界、Part 头和请求发送仍应交给对应的 HTTP 或 multipart API。