Go url.URL 怎样保留结尾的空查询标记

Go 的 net/url 在处理以问号结尾、但没有任何参数的 URL 时，容易出现一个看似奇怪的现象：输入是 https://api.example.com/items?，重新调用 String() 后却变成了 https://api.example.com/items。要保留这个结尾问号，关键是设置 URL.ForceQuery；RawQuery 只保存问号后面的查询内容，空字符串本身不能表达“原来确实有一个问号”。

官方文档：https://pkg.go.dev/net/url#URL

下面只讨论空查询标记的解析和序列化，不展开查询参数编码。先把三个结果分开：没有问号、只有问号、问号后有实际内容。

先观察结尾问号为什么会消失

如果只读取 RawQuery，前两种输入都会得到空字符串。因此，重新构造 URL 时只写入 RawQuery，就丢失了“存在问号”的信息。可以用一个小函数把这三种输入放在同一张结果表里：

func describe(raw string) error {
	// Parse 保留 URL 的结构字段，而不是把整段文本当作普通字符串。
	u, err := url.Parse(raw)
	if err != nil {
		return fmt.Errorf("解析 URL 失败: %w", err)
	}

	// RawQuery 只表示问号后的内容，ForceQuery 才表示空问号是否存在。
	fmt.Printf("raw=%q query=%q force=%t out=%q\n",
		raw, u.RawQuery, u.ForceQuery, u.String())
	return nil
}

对 https://api.example.com/items? 而言，RawQuery 是空字符串，但 ForceQuery 为 true。String() 会根据这两个字段共同决定是否追加问号，所以不能用“RawQuery == ""”推断 URL 没有查询部分。

用 ForceQuery 保留空查询语义

解析已有 URL 时，标准库会在原文以单个问号结尾的情况下设置 ForceQuery。手工构造 URL 时，则需要显式设置它：

func keepEmptyQuery() (string, error) {
	// RawQuery 为空，表示没有键值；ForceQuery 表示仍要输出结尾问号。
	u := &url.URL{
		Scheme:     "https",
		Host:       "api.example.com",
		Path:       "/items",
		RawQuery:   "",
		ForceQuery: true,
	}

	// String 负责按 URL 规则序列化，结果保留 /items?。
	return u.String(), nil
}

如果 URL 后面已经有真实参数，例如 RawQuery: "limit=10"，就不需要依赖 ForceQuery 来显示问号；查询内容本身会触发问号输出。为了避免语义混乱，构造代码时应先判断业务对象是否真的需要“空查询”这一状态。

修改 URL 时不要把两个状态混在一起

常见问题是先解析一个带问号的地址，再把 RawQuery 清空，最后忘记决定是否保留问号。可以把这个决定写成明确的策略：

func setQueryState(raw string, keepMark bool) (string, error) {
	// 先解析原地址，避免手工切字符串时误伤路径中的转义内容。
	u, err := url.Parse(raw)
	if err != nil {
		return "", fmt.Errorf("解析 URL 失败: %w", err)
	}

	// 清空参数后，是否保留问号由调用方显式决定。
	u.RawQuery = ""
	u.ForceQuery = keepMark
	return u.String(), nil
}

这里的 keepMark=false 得到没有查询部分的 URL，keepMark=true 得到以问号结尾的 URL。若输入本身含有参数，清空参数后也要重新选择这个标志，不能期待 RawQuery 自动记住旧状态。

几个容易误判的边界

• 空查询不等于空值参数：/items? 没有键名；/items?flag= 则有一个名为 flag 的参数，只是值为空。
• 不要用字符串后缀代替字段：业务代码需要修改 URL 时，应通过 RawQuery 和 ForceQuery 表达意图，再统一调用 String()。
• 保留问号是协议语义选择：如果下游把“是否带查询分隔符”用于签名、缓存键或路由判断，就应把它当作显式状态记录。

排查这类问题时，最有效的顺序是同时打印 RawQuery、ForceQuery 和 String()，不要只看最终字符串。这样能立刻判断是解析时没有识别空查询，还是后续修改字段时主动清除了标记。

常见问题

为什么 RawQuery 为空时 String 还可以输出问号？

因为 ForceQuery 单独记录了原始 URL 是否包含查询标记。它为真且 RawQuery 为空时，String() 会输出结尾问号。

设置了 ForceQuery 但 RawQuery 有内容，会不会输出两个问号？

不会。问号只由序列化逻辑统一添加一次；有实际 RawQuery 时，ForceQuery 通常不需要设置。

一句话总结：RawQuery 表示“问号后是什么”，ForceQuery 表示“空查询时问号是否仍存在”；两者一起使用，才能稳定保留 URL 的结尾语义。