Go url.ParseQuery 遇到分号参数为什么报错

调用 url.ParseQuery 解析 a=1;b=2&c=3 时，返回错误并不代表整个查询字符串都坏了。Go 1.17 起，查询参数默认只用 & 分隔；未进行 URL 编码的分号会让所在参数段被判为无效，同时其他合法参数仍可能进入返回的 url.Values。

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

升级范围：Go url.ParseQuery 现在只认 & 分隔

Go 1.17及之后的版本默认不再兼容分号作为查询参数的分隔符，完全遵循最新的RFC规范，你可以提前把查询串里的非必要分号转义，或者手动替换为&符号就能正常解析。

旧代码常把分号和 & 混用。Go 1.17 的兼容性说明明确了变化：非 URL 编码分号不再作为查询设置分隔符，ParseQuery 会返回剩余有效设置和一个错误。当前 net/url 文档也把查询定义为由 & 分隔的 key=value 列表。

为什么非编码分号会让参数整段失效

ParseQuery 先按 & 划分设置，再检查每个设置是否含有非编码分号。命中后，这个设置不会继续拆成两个参数，而是记录 invalid semicolon separator in query 并跳过。因此，下面的结果不能只看错误字符串：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // 分号未编码，所在设置会被跳过；c=3 仍是独立的合法设置。
    values, err := url.ParseQuery("a=1;b=2&c=3")
    fmt.Printf("values=%v\n", values)
    fmt.Printf("err=%v\n", err)
}

values=map[c:[3]]
err=invalid semicolon separator in query

这也是排查中最容易漏掉的边界：如果业务只判断 err == nil，会把问题当成一次完整失败；如果业务只使用 values，又可能悄悄丢掉包含分号的过滤条件。

把分号作为数据编码而不是分隔符

如果分号属于值，例如筛选表达式、标签串或自定义字段，发送端应做 URL 编码。使用 url.Values 组织参数比手拼字符串更稳妥，它会把值中的分号编码为 %3B，解析端再还原为普通字符：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    params := url.Values{}
    // Set 接收原始业务值，Encode 负责处理分号等保留字符。
    params.Set("filter", "a;b")
    params.Set("page", "1")
    raw := params.Encode()

    // 解析后检查错误，确认编码链路没有被中间层改写。
    decoded, err := url.ParseQuery(raw)
    fmt.Println(raw)
    fmt.Println(decoded.Get("filter"), err)
}

filter=a%3Bb&page=1
a;b 

若上游协议明文规定“分号就是旧式分隔符”，兼容转换必须放在协议适配层，并先区分分隔符与值中的分号。HTTP 服务还可以了解 net/http.AllowQuerySemicolons 这个兼容包装，但它改变了解析约定，缓存键、签名和网关若采用不同规则，就会出现同一 URL 被理解成不同参数的问题。

迁移检查清单：不要只修复报错表面

• 搜索手拼查询字符串的代码，优先改为 url.Values。
• 为未编码分号、编码分号、普通多值参数和空值分别写回归用例。
• 解析后同时记录 Values 与 error，明确部分结果是否允许进入业务。
• 检查网关、缓存键、签名校验和下游服务是否使用同一种分隔规则。

常见问题

把分号改成 %3B 就一定正确吗？

只有当分号本来属于参数名或参数值时才正确。若它是旧协议的字段分隔符，应在适配层按协议解析，不能无条件替换。

ParseQuery 返回 error 后还能用 Values 吗？

可以读取其中的合法项，但是否继续业务要由接口契约决定。含分号的设置可能已被跳过，不能把部分结果当成完整请求。

URL.Query 和 ParseQuery 有什么区别？

URL.Query 会调用查询解析并静默丢弃格式错误的设置；需要知道解析失败原因时，直接使用 ParseQuery 并处理错误。