Go url.Values 批量合并查询参数的覆盖规则

Go 里批量合并查询参数时，先定“同名键是追加还是覆盖”，再决定合并顺序。url.Values 的类型是 map[string][]string：筛选标签、范围这类允许多个值的字段用 Add 追加；分页、排序、租户这类单值控制项用 Set 覆盖。要保护默认参数不被后续调用改掉，可以先复制一份，再把最终结果交给 Encode。

先把 Add 追加和 Set 覆盖分成两种策略

把参数分层后再合并更容易排错。下面的例子把默认分页、租户标签和本次请求的排序条件放在三组输入中。标签可以有多个，排序只能有一个最终选择，因此两者不能用同一个合并动作。

package main

import (
    "fmt"
    "net/url"
)

func mergeValues(defaults, tenant, request url.Values) url.Values {
    // 复制第一层，避免给调用方传入的默认参数增加或替换值。
    merged := cloneValues(defaults)

    // 标签是多值字段：租户标签和请求标签都要保留。
    for _, value := range tenant["tag"] {
        merged.Add("tag", value)
    }
    for _, value := range request["tag"] {
        merged.Add("tag", value)
    }

    // 排序是单值字段：请求级配置拥有更高优先级，使用 Set 覆盖旧值。
    if sort := request.Get("sort"); sort != "" {
        merged.Set("sort", sort)
    }
    return merged
}

func cloneValues(src url.Values) url.Values {
    // 每个键都新建切片，避免后续 append 共享底层数组。
    dst := make(url.Values, len(src))
    for key, values := range src {
        dst[key] = append([]string(nil), values...)
    }
    return dst
}

func main() {
    defaults := url.Values{"page": {"1"}, "sort": {"created_at"}}
    tenant := url.Values{"tag": {"backend", "go"}}
    request := url.Values{"tag": {"http"}, "sort": {"updated_at"}}

    merged := mergeValues(defaults, tenant, request)
    fmt.Println(merged["tag"])
    fmt.Println(merged.Get("sort"))
}

这个策略的结果是标签切片保留 backend、go、http，排序只保留 updated_at。注意，url.Values 的键区分大小写，tag 与 Tag 不会互相覆盖。

合并顺序决定单值参数的最终结果

Set 的语义是“把这个键设置为一个值，并替换已有值”，所以单值参数应按默认值、业务层值、请求层值的顺序处理。不要把所有字段都改成 Set，否则多选条件会只剩最后一项；也不要把排序字段都改成 Add，否则下游必须再定义多个排序值如何解释。

如果业务要求“请求方不能覆盖租户限定条件”，就不要简单地把请求参数整体循环写入结果，而应先筛出允许覆盖的键。所谓批量合并，真正需要批量的是字段处理，优先级规则仍然要逐类明确。

Clone 保证批量合并不污染原始输入

默认参数常常会被多个请求复用。直接在它上面调用 Add 或 Set，下一次请求可能继承上一次的状态。Go 1.27 的 Values.Clone 可以生成深复制；在需要兼容较早版本时，使用前文的显式复制函数即可。

base := url.Values{
    "page": {"1"},
    "tag":  {"go"},
}

// Clone 会复制 map 和每个值切片，后续修改不会回写 base。
copy := base.Clone()
copy.Set("page", "2")
copy.Add("tag", "http")

fmt.Println(base.Encode()) // page=1&tag=go
fmt.Println(copy.Encode()) // page=2&tag=go&tag=http

图示中的“深复制”是本节关键：只复制 map 外壳而继续共享 []string，仍可能在追加时产生隐蔽的串改。若项目的 Go 版本没有 Clone，使用前文的 cloneValues。

Encode 前后检查四个容易误判的边界

合并完成后通常把结果赋给 u.RawQuery。Encode 会对键排序，并对值做 URL 编码；这保证输出适合传输，但不代表业务字段已经校验。中文、空格、百分号等值要通过编码结果传递，不要手工拼接字符串。

• 同名多值：Get 只返回首值，需要完整筛选时读取 values[key]。
• 空值：Set("q", "") 与没有 q 不是同一语义，可用 Has 区分。
• 覆盖边界：循环合并前先列允许覆盖的键，避免请求参数覆盖权限或租户约束。
• 编码边界：只修改 Values，最后统一 Encode，不要把已编码字符串再次编码。

可以把最终拼接写成：

u, err := url.Parse("https://example.com/search")
if err != nil {
    // URL 解析失败时直接返回，避免把不完整请求发出去。
    return err
}
u.RawQuery = merged.Encode()
fmt.Println(u.String())

相关问题

url.Values 的 Add 和 Set 有什么区别？

Add 把新值追加到同名键的切片末尾，Set 删除该键原有值后只保留一个新值。

为什么 Encode 后参数顺序变了？

Encode 会按键排序以生成稳定的查询字符串；同一个键对应的多个值仍按切片顺序编码。

批量覆盖时怎样避免污染默认参数？

先使用 Values.Clone，或像示例一样复制 map 和每个 []string，再在副本上合并。