Go net/url解析带分号查询串并保留错误信息的处理方法

接口偶尔收到 page=2;sort=desc&tag=go，如果直接调用 u.Query()，日志里只剩一部分参数，真正的分号错误却消失了。处理这类输入的关键不是把分号一律替换成 &，而是先保留原始错误，再根据上游协议决定是否兼容。

ParseQuery为什么要保留Values和error

net/url 的查询解析约定是用 & 分隔 key=value。未编码的分号会让对应片段被判为无效，但 ParseQuery 仍会返回一个非空的 Values，里面保留已经成功解析的参数，同时返回第一个错误。这正适合网关或接口层做“部分结果 + 原始原因”的记录。

package main

import (
    "fmt"
    "net/url"
)

// parseQuery 保留有效参数和解析错误，避免入口把坏数据静默吞掉。
func parseQuery(raw string) (url.Values, error) {
    values, err := url.ParseQuery(raw)
    if err != nil {
        // 上层可以把 raw 做脱敏后写日志，把 values 用于诊断或兼容判断。
        return values, fmt.Errorf("query parse failed: %w", err)
    }
    return values, nil
}

// 调用方应区分“有部分参数”和“整串有效”，不能只看map是否为空。
// values, err := parseQuery("page=2;sort=desc&tag=go")

这里不要用 u.Query() 替代上面的函数。官方文档明确说明，URL.Query() 会静默丢弃格式错误的参数对；当你需要记录请求异常、返回明确的 400，或统计上游错误率时，静默行为会让定位少掉关键证据。

先分清未编码分号和%3B值内字符

两个输入看起来都包含分号，语义却不同：

因此，简单的 strings.ReplaceAll(raw, ";", "&") 有边界风险：它会把旧协议分隔符和业务值混在一起，也会让错误输入看起来像合法输入。更稳妥的做法是先记录原文和错误，再确认这个接口的历史协议是否真的把分号定义成参数分隔符。

旧接口必须兼容分号时的安全拆分

如果旧系统的契约明确规定 & 和未编码 ; 都是分隔符，可以只在兼容适配层拆成参数段，然后对每个键和值分别调用 url.QueryUnescape。这样 %3B 在解码前不会被误切开，还能保留哪个片段失败。

package querycompat

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

// ParseLegacyQuery 只服务于已有分号分隔协议，不应成为所有接口的默认解析器。
func ParseLegacyQuery(raw string) (url.Values, error) {
    values := url.Values{}
    var firstErr error
    // 仅按原始的&和;切段，%3B仍是编码文本，不会被这一步拆开。
    parts := strings.FieldsFunc(raw, func(r rune) bool { return r == '&' || r == ';' })
    for _, part := range parts {
        pair := strings.SplitN(part, "=", 2)
        key, err := url.QueryUnescape(pair[0])
        if err != nil {
            if firstErr == nil { firstErr = fmt.Errorf("decode key %q: %w", part, err) }
            continue
        }
        value := ""
        if len(pair) == 2 {
            value, err = url.QueryUnescape(pair[1])
            if err != nil {
                if firstErr == nil { firstErr = fmt.Errorf("decode value %q: %w", part, err) }
                continue
            }
        }
        values.Add(key, value)
    }
    return values, firstErr
}

这个兼容函数仍然有一个不能回避的事实：未编码分号既可能是分隔符，也可能是旧客户端写入的普通数据。若协议没有定义清楚，服务端无法从字符串本身可靠推断意图。生产环境应优先推动上游使用 url.Values.Encode() 生成标准查询串；兼容层只记录命中次数，并设置退出计划。

上线前的错误处理清单

• 入口需要严格校验时：调用 ParseQuery，遇到错误记录脱敏原文并返回可识别的客户端错误。
• 需要兼容旧协议时：把兼容逻辑隔离在适配层，保留段级错误，不要全局替换分号。
• 需要取多个同名参数时：读取 Values[key]，不要误用只返回第一个值的 Get。
• 构造新查询串时：使用 url.Values 的 Set/Add/Encode，让分号等数据字符被正确编码。

常见问题

为什么ParseQuery返回了参数还要判定error

因为它会保留已经识别的有效参数，错误表示查询串并非整体可靠。是否继续使用部分结果必须由接口契约决定。

把分号替换成&是不是最快的修复

只有在明确的旧协议下才可作为适配策略；直接全局替换无法区分分隔符和业务值，建议使用按段解码并保留错误的兼容函数。

什么时候可以直接调用URL.Query

只在格式错误可以被明确忽略、且调用方不需要诊断信息时使用。鉴权、计费、审计和网关入口应优先显式处理错误。