Go net/http.AllowQuerySemicolons 怎样兼容旧查询参数分隔符

如果旧客户端仍把查询参数写成 ?tag=go;page=2，Go 1.17 之后不能再假设它会自动得到两个参数。需要兼容这类请求时，可以把 http.AllowQuerySemicolons 放在业务 Handler 外层，并且保证它发生在 Request.ParseForm 之前。这个包装器只处理 URL 查询中的未转义分号，把它转换为和号后交给下层 Handler；已经写成 %3B 的分号不会被当作分隔符。

这是一层有边界的迁移兼容方案。它恢复旧的拆分习惯，却不会替你解决网关、签名校验和应用解析规则不一致的问题。下面从最小写法开始，再看重复键、空值和是否应该长期保留兼容层。

Go 1.17 后为什么需要显式兼容

现代查询串通常用 & 分隔参数，例如 ?tag=go&page=2。旧系统有时会把分号也当作分隔符：?tag=go;page=2。Go 官方文档把 AllowQuerySemicolons 定义为一个 Handler 包装器，它会把 URL 查询里未转义的分号转换为和号，再调用传入的 Handler，用来恢复 Go 1.17 以前同时按分号和和号拆分的行为。

要注意三个边界：

• 只针对查询串里的未转义分号，不是把所有正文中的分号都改写。
• 应在 ParseForm 之前包住 Handler；如果业务已经解析完，再包就晚了。
• 官方文档提醒，这种行为可能和代理不一致，差异在签名、鉴权或过滤链路中需要单独评估。

在 ParseForm 之前包住 Handler

最小结构是让业务 Handler 只负责读取参数，把兼容职责放在入口组合处。这样后续 Handler 不需要到处判断是否包含分号。

package main

import (
    "fmt"
    "net/http"
)

func queryHandler(w http.ResponseWriter, r *http.Request) {
    // 兼容层必须位于本 Handler 外侧；这里才开始解析表单参数。
    if err := r.ParseForm(); err != nil {
        http.Error(w, "query parse failed", http.StatusBadRequest)
        return
    }

    // Form 使用 url.Values，重复键会保留为多个值，不要只取一个字符串。
    fmt.Fprintf(w, "tag=%q page=%q\\n", r.Form["tag"], r.Form["page"])
}

func main() {
    // AllowQuerySemicolons 将兼容范围限制在这个入口，不改变其它 Handler。
    handler := http.AllowQuerySemicolons(http.HandlerFunc(queryHandler))
    _ = http.ListenAndServe(":8080", handler)
}

在这个结构里，入口收到 ?tag=go;page=2 时，业务 Handler 看到的是可以按旧规则拆分的查询内容。错误处理仍然由 ParseForm 负责；生产代码还应根据项目需要记录请求标识和解析失败原因。

重复键、空值和编码分号怎么读

兼容分隔符只解决“怎样切开查询串”，不会改变 url.Values 的多值模型。下面这个例子同时包含重复键、空值和编码后的分号，适合用来明确业务契约。

func readFilters(r *http.Request) (tags []string, page string, literal string, err error) {
    // 先让 net/http 完成查询串与表单的统一解析。
    if err = r.ParseForm(); err != nil {
        return nil, "", "", err
    }

    // Get 只返回第一个值；需要保留重复参数时直接读取切片。
    tags = append([]string(nil), r.Form["tag"]...)
    page = r.Form.Get("page")

    // %3B 是编码后的分号，业务值应保留为字面量而不是再次拆分。
    literal = r.Form.Get("note")
    return tags, page, literal, nil
}

// 例如：?tag=go;tag=http&page=¬e=a%3Bb
// 兼容层只把第一个未转义分号当成分隔符；note 的编码分号仍属于值。

这里有两个容易混淆的点。第一，Get 适合明确只接受一个值的字段，标签、筛选器等重复字段应保留切片并由业务决定是否去重。第二，空值和缺失值可能在业务上不同：page= 表示出现了字段但值为空，而完全没有 page 则是另一种状态，必要时可用切片是否存在来区分。

不要把兼容层放在 ParseForm 之后

下面这种写法看起来只是顺序不同，实际已经失去兼容意义：业务 Handler 先调用 ParseForm，外层才尝试使用 AllowQuerySemicolons。解析动作已经发生，后续包装无法让此前的错误或缺失字段自动恢复。

func wrongHandler(w http.ResponseWriter, r *http.Request) {
    // 错误示例：解析已经发生，兼容包装没有机会影响这次 ParseForm。
    _ = r.ParseForm()
    fmt.Fprintln(w, r.Form.Get("page"))
}

func buildHandler() http.Handler {
    // 正确方向：先组合兼容层，再把最终 Handler 交给服务器。
    return http.AllowQuerySemicolons(http.HandlerFunc(queryHandler))
}

如果项目使用中间件链，原则也一样：把兼容层放到所有会读取 URL.Query()、ParseForm 或基于查询参数做鉴权的中间件之前。这样同一条链路尽量只产生一种应用侧解释。

评估代理和安全风险

官方文档特别提醒：分号兼容行为可能与很多代理不一致。风险不在于“分号一定危险”，而在于同一个原始查询串被链路上的不同组件拆成了不同的键值集合。

• 网关按 & 拆分，应用按兼容层把分号也拆分，签名覆盖的字段集合可能不同。
• WAF、缓存键、路由规则和应用 Handler 采用不同解析规则时，可能出现缓存命中与业务判断不一致。
• 旧客户端如果不可控，可以把兼容层限定在特定路由或版本入口，不要默认包住所有请求。
• 如果客户端、代理和服务端都可升级，优先统一使用未编码的 &，再移除兼容层。

什么时候保留，什么时候删除

可以用下面的判断表收敛方案：

常见问题

编码后的 %3B 会不会被 AllowQuerySemicolons 当成分隔符？

不会。它针对的是查询串中的未转义分号；编码后的分号在解码后才作为参数值的一部分出现。

可以在 Handler 内部临时调用 AllowQuerySemicolons 吗？

不建议。它返回的是新的 Handler，正确用法是在服务器注册或中间件组合处包住业务 Handler，并让它先于参数解析发生。

只调用 URL.Query 也需要兼容层吗？

如果业务明确依赖分号作为参数分隔符，就应该在读取前统一处理；但更重要的是先确认代理和签名层是否也支持同样的语义。

长期方案是什么？

把客户端请求统一迁移到 &，同时让网关、签名校验、缓存键和应用都采用一致的解析规则。兼容层适合迁移期，不应成为没人知道的永久约定。

总结

http.AllowQuerySemicolons 的核心用法只有一句话：在会读取查询参数的 Handler 之前包住它。真正需要谨慎的是边界：未转义分号和编码分号不同，重复键要保留多值，ParseForm 的顺序不能错，代理与应用的拆分规则必须统一。能控制客户端时尽快迁移到标准的 &，不能控制时把兼容范围限定在清晰的入口。