url.Values 读取重复查询参数的保序处理方案

Go 的 url.Values 可以保存同一查询键的多个值。读取重复参数时，用 values["tag"] 取得完整切片；Get("tag") 只返回首项。由 ParseQuery 解析得到的同键值按输入出现顺序追加，但 Values 本身是 map，不能保留不同键之间的全局交错位置。

因此，“保序”先分成两个目标：只关心 tag 的值顺序时，读取切片即可；需要还原整串参数顺序时，在 RawQuery 阶段另外保存参数对序列。若还要求原始编码字节完全不变，应直接保留原串，不能期待 ParseQuery 再 Encode 自动还原。

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

先定位丢的是值，还是参数对的位置

设请求查询串是 tag=graph&lang=zh&tag=queue&tag=&tag=graph。同一个 tag 的语义序列是 graph、queue、空字符串、graph；lang 位于前两个 tag 之间。下面三种现象看起来都像“顺序不对”，原因却不同。

不要通过对整个 map 做 range 来推断原始参数的位置。即使某次看到的次序符合预期，也没有保存全局顺序的数据模型。先明确业务究竟关心哪一层，后面的改动才不会把正常的键排序误当成解析错误。

读取整组切片，先处理解析错误

Values 的类型是 map[string][]string。官方 Get 文档说明它读取首项，Add 追加，Set 替换已有值。ParseQuery 的官方实现顺次读取字段并追加到该键切片；Encode 对键排序，然后遍历各值切片。这些细节可在 https://go.dev/src/net/url/url.go 查看。

下面是独立的完整示例。它返回完整值序列，并额外返回 present 区分键不存在与键存在但值为空。示例刻意保留重复值，没有擅自去重。

package main

import (
    "fmt"
    "net/url"
)

func repeated(raw, key string) ([]string, bool, error) {
    values, err := url.ParseQuery(raw)
    if err != nil {
        // 本例采用整串拒绝策略，不能把残缺解析结果继续当作完整请求。
        return nil, false, fmt.Errorf("查询参数解析失败: %w", err)
    }
    items, present := values[key]
    // 复制后交给业务层，避免后续修改影响 Values 内部切片。
    result := append([]string(nil), items...)
    return result, present, nil
}

func main() {
    // 使用交错参数，显式展示同键重复值与空值。
    raw := "tag=graph&lang=zh&tag=queue&tag=&tag=graph"
    tags, present, err := repeated(raw, "tag")
    if err != nil {
        fmt.Println(err)
        return
    }
    // %q 使空字符串也可见，不通过 Get 丢弃其他值。
    fmt.Printf("存在=%t，tag=%q\n", present, tags)
}

如果缺少 tag，present 为 false；若输入包含 tag=，键存在且切片含一个空字符串。tag 没有等号也会按空值解释，因此只靠 Values 无法区分 tag 与 tag= 的原始写法。不要用 Get 的空字符串返回值同时代表“缺失”和“显式空值”。

ParseQuery 遇到非法转义等错误时可能同时返回部分合法参数与错误。本例把错误视作整串失败，避免只读到合法片段后误以为请求完整。处理 HTTP 请求时，可对 r.URL.RawQuery 显式调用 ParseQuery；URL.Query() 不向调用者返回解析错误，不适合作为需要拒绝畸形输入的唯一入口。官方说明：https://pkg.go.dev/net/url#ParseQuery、https://pkg.go.dev/net/url#URL.Query。

传入 ParseQuery 的应是查询部分，不包括开头问号，不是整条 URL。上游若已将加号或百分号转义解码过一次，也不要再把解码结果当原始查询串重复解析。

需要全局顺序时另存参数对序列

当业务把不同字段的位置也当成含义时，我会在接收 RawQuery 时建立 Pair 序列，每项有 Raw 原片段、Key 解码键、Value 解码值 和 HasEquals 标记。原始查询串和序列承担不同用途：前者用于字节保留，后者用于按位置读取、过滤或解释字段。

下面是可放进已有 Go 包的函数片段，需要导入 fmt、net/url、strings。它为示例自行设置输入预算，采用整串拒绝策略；不是标准库所有版本行为的替代实现，也不是通用 URL 校验器。

// Pair 表示一个非空原始字段，保留顺序、编码形式和等号信息。
type Pair struct {
    Raw       string
    Key       string
    Value     string
    HasEquals bool
}

// parseOrdered 的上限与整串拒绝策略是本例的业务约定，非标准库默认值。
// 需要导入 fmt、net/url、strings；不接受带前导问号的完整 URL。
func parseOrdered(raw string) ([]Pair, error) {
    if len(raw) > 16 256 {
        return nil, fmt.Errorf("查询字段超过本例的 256 项上限")
    }
    var pairs []Pair
    for pos, field := range strings.Split(raw, "&") {
        if field == "" {
            // 与常规解析一致，忽略空字段；原始字节仍在 raw 中。
            continue
        }
        if strings.Contains(field, ";") {
            return nil, fmt.Errorf("第 %d 个字段含未编码分号", pos+1)
        }
        keyRaw, valueRaw, hasEquals := strings.Cut(field, "=")
        key, err := url.QueryUnescape(keyRaw)
        if err != nil {
            return nil, fmt.Errorf("第 %d 个字段键解码: %w", pos+1, err)
        }
        value, err := url.QueryUnescape(valueRaw)
        if err != nil {
            return nil, fmt.Errorf("第 %d 个字段值解码: %w", pos+1, err)
        }
        // 解码失败时不会返回部分成功的 Pair 列表。
        pairs = append(pairs, Pair{
            Raw: field, Key: key, Value: value, HasEquals: hasEquals,
        })
    }
    return pairs, nil
}

关键点是先按原始 & 分割，再按第一个等号切开，最后分别 QueryUnescape。不能先把整串解码：编码在值里的 %26 本应是普通数据，提前解码会把它变成假的参数分隔符；编码等号同理。

例如 tag=a%26b&tag=c%3Dd 应形成两个 tag 值 a&b 与 c=d。解码键后再比较，也意味着 ta%67 与 tag 可以对应同一个解码键。业务过滤时应明确使用解码键，不要把两种表示混在一起。

该函数忽略空字段，因此 a=1&&b=2& 的空分隔位置不会进入 Pair 序列；要一字不差保留它们，就继续使用原始 raw。HasEquals 只记录非空字段是否出现等号，不意味着保留了所有空字段。这一边界必须随函数一起传给使用方。

重新编码前确认允许改变哪些内容

如果只需要构造常规查询串，可以使用 url.Values.Encode()。它按键排序，保持每个键对应切片中的遍历顺序，但会把同键项聚在一起。它并不承诺恢复跨键交错位置，也不承诺恢复百分号转义大小写或空格的原始写法。

// 片段需要导入 net/url 与 fmt；Add 保留重复项，Set 会替换整组。
values := url.Values{}
values.Add("tag", "graph")
values.Add("lang", "zh")
values.Add("tag", "queue")
fmt.Println(values.Encode())

若从 Pair 序列生成一个新的规范化查询串，应按 Pair 的切片顺序对每个 Key、Value 分别 QueryEscape 再连接；这保留语义顺序，但编码形式可以变化。若仅需保留未修改的字段原样，可以按序使用 Pair.Raw，不过空字段仍需单独设计。要求整个查询串字节相同的转发或归档任务，应直接保留 RawQuery，而不是在 Values 与字符串之间反复往返。

QueryUnescape 会把查询中的 + 解释为空格；字面加号应编码成 %2B。这些变化不是值切片重排。若后续操作要给 tag 排序，先复制切片再排序；直接 sort 原切片会改变 Values 中的值序列。示例提供读取与模型选择，不声称已经在本机运行或测得性能收益。

读者可以用下表作为业务核对清单。表中是根据输入与接口定义推导的预期，不是实际运行记录。

常见问题

重复参数要不要自动去重？

由接口协议决定。顺序优先级、重复过滤条件与多选字段可能有不同含义。保序读取阶段不要自动丢弃重复项；若业务要求去重，应另行规定保留首次还是末次出现。

QueryEscape 和 PathEscape 能互换吗？

不能把路径段编码规则当作查询组件编码规则。此处处理查询键值，使用 QueryEscape 和 QueryUnescape，尤其要关注加号的含义。官方入口：https://pkg.go.dev/net/url#QueryUnescape。

前端发 tag[] 会自动成为 tag 吗？

不会自动按其他框架的数组命名约定转换。解码后的键名是 tag[]，应按约定读取这个键，或者要求调用方统一使用重复 tag；不要把两种键名悄悄合并。