Go url.URL 的 ForceQuery 怎样保留空查询问号

在 Go 里，https://example.com/items? 和 https://example.com/items 的查询参数都为空，但它们保留了不同的原始写法。直接看 RawQuery 很容易把这两个 URL 当成同一种状态。

解决办法是把 url.URL.ForceQuery 当作“原始 URL 是否出现过问号”的独立标记：RawQuery 为空时，将 ForceQuery 设为 true，URL.String() 才会保留末尾的 ?。

官方地址：https://pkg.go.dev/net/url#URL

先看懂 ForceQuery 的三种状态

URL 结构体把编码后的查询内容放在 RawQuery，把“原始地址是否有问号”放在 ForceQuery。两者组合后，才能还原查询部分的三种常见状态。

最小配方：解析后保留结尾问号

如果输入来自请求行、代理配置或签名原文，优先让 url.Parse 识别原始字符串，而不是先拆掉问号再拼接。解析结果会保留空查询的状态，重新输出时即可得到原来的形式。

package main

import (
	"fmt"
	"log"
	"net/url"
)

func main() {
	// 这三个输入只在查询部分的写法上不同。
	inputs := []string{
		"https://example.com/items",
		"https://example.com/items?",
		"https://example.com/items?page=2",
	}

	for _, raw := range inputs {
		u, err := url.Parse(raw)
		if err != nil {
			// 解析失败时停止，避免把不完整 URL 当成签名或请求目标。
			log.Fatal(err)
		}
		// RawQuery 表示查询内容，ForceQuery 表示原文是否出现过问号。
		fmt.Printf("raw=%q query=%q force=%v out=%q\\n", raw, u.RawQuery, u.ForceQuery, u.String())
	}
}

关键点是：空查询时 RawQuery == "" 是正常现象，不能据此判断原始字符串没有 ?。要保留这个差别，应读取 ForceQuery。

修改查询参数时，先决定是否还要空查询

业务代码经常需要先读出参数、修改值，再通过 Values.Encode 写回 RawQuery。一旦写入了参数，问号会由非空的 RawQuery 自然产生；如果删除完参数仍要保留问号，则需要显式保留 ForceQuery。

package main

import (
	"fmt"
	"log"
	"net/url"
)

func rewrite(raw string, keepEmptyQuery bool) (string, error) {
	u, err := url.Parse(raw)
	if err != nil {
		return "", err
	}

	// 先保存原始状态，再把查询解析成可修改的 Values。
	wantedEmptyQuery := keepEmptyQuery && u.ForceQuery
	values := u.Query()
	values.Del("page")
	u.RawQuery = values.Encode()
	// 删除参数后 RawQuery 可能为空，此时由策略决定是否保留问号。
	u.ForceQuery = wantedEmptyQuery && u.RawQuery == ""
	return u.String(), nil
}

func main() {
	result, err := rewrite("https://example.com/items?page=2", true)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result)
}

这个配方把“删除参数”和“是否保留空查询”拆成两个决策。不要无条件把 ForceQuery 设为 true，否则原本没有查询的 URL 也会被改写成带问号的形式。

关键字段与输出方法怎么选

URL.Query() 适合读取参数，它返回解码后的 url.Values；Values.Encode() 再把参数编码回查询文本。RawQuery 适合保存编码后的查询部分，不能把它当成包含开头问号的完整字符串。

package main

import (
	"fmt"
	"log"
	"net/url"
)

func main() {
	u, err := url.Parse("https://example.com/items?")
	if err != nil {
		log.Fatal(err)
	}

	// Query 只关心参数集合，因此空查询和无查询都会表现为空。
	fmt.Printf("values=%v rawQuery=%q forceQuery=%v\\n", u.Query(), u.RawQuery, u.ForceQuery)
	// String 保留完整 URL 的查询标记，RequestURI 只返回请求目标部分。
	fmt.Printf("string=%q requestURI=%q\\n", u.String(), u.RequestURI())
}

容易踩坑的边界

不要用 Query 是否为空判断原始问号

u.Query() 的职责是解析参数，不负责记录原始分隔符。https://example.com/items? 与 https://example.com/items 都可能得到空的 Values，需要 ForceQuery 才能区分。

RawQuery 不包含问号

手动赋值时应写 u.RawQuery = "page=2"，不要写成 "?page=2"。开头的问号由 String 或 RequestURI 根据字段状态生成。

签名和缓存键要先约定规范化规则

如果系统把 URL 文本作为签名原文或缓存键，空查询是否等同于无查询必须先定规则。需要保留输入原貌时保留 ForceQuery；需要规范化时可以显式清理它，但要让所有调用方使用同一规则。

完整复查清单

1. 需要区分 /items 和 /items? 时，读取并维护 ForceQuery。
2. 修改参数后使用 Values.Encode() 更新 RawQuery，不要手写未编码的查询文本。
3. 只需要参数集合时使用 Query()；需要完整地址或请求目标时分别使用 String() 或 RequestURI()。
4. 涉及签名、缓存和代理转发时，先确定空查询的规范化策略，再决定是否保留末尾问号。

常见问题

ForceQuery 为 true 但 RawQuery 非空，会多出两个问号吗？

不会。非空的 RawQuery 本身已经触发查询输出，ForceQuery 主要解决 RawQuery 为空但原始 URL 有问号的情况。

把 ForceQuery 设为 true 就等于添加了一个空参数吗？

不等于。它只保留 URL 语法中的问号，不会在 url.Values 中生成键，也不会让 Query() 返回一个参数。

为什么只保存 RawQuery 还原不出原始 URL？

因为 RawQuery 不记录开头的问号。若输入可能有空查询，必须同时保存 ForceQuery，或者保存经过约定的完整 URL 文本。