Go net/url.URL 怎样安全修改路径而不丢查询参数

在 Go 里修改一个已经解析好的 URL，最容易踩的坑不是路径本身，而是为了改路径重新拼接整条字符串，结果把原来的查询参数、片段或转义形式一起弄丢。更稳妥的做法是：先用 url.Parse 得到 *url.URL，只改它的 Path，最后调用 String 重新生成 URL。

只改路径时，直接修改 u.Path 或使用 u.JoinPath；不要用新的路径字符串覆盖整个 *url.URL。原查询参数位于 RawQuery，不会因为单独修改 Path 而消失。

官方文档：https://pkg.go.dev/net/url

本文只讨论 Go net/url.URL 的路径修改与查询参数保留，不展开 HTTP 重定向策略、路由匹配或服务端 URL 规范化。

先看清 URL 对象里的几个字段

url.Parse 会把一条 URL 拆成多个字段。对这篇问题最关键的是 Path、RawPath、RawQuery 和 Fragment。

官方文档说明，Path 通常是解码后的形式，String 会通过 EscapedPath 重新生成路径。RawQuery 则是已经编码好的查询部分，所以“路径”和“查询参数”本来就是两个独立区域。

只改路径时直接赋值 Path

如果新路径已经是业务上确定的路径文本，最小方案就是给 u.Path 赋值。因为没有重建 u.RawQuery，原有的 page、sort 等参数会继续保留。

package main

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

func main() {
    u, err := url.Parse("https://api.example.com/v1/orders?page=2&sort=created#summary")
    if err != nil {
        log.Fatal(err) // 输入来自外部时，解析失败不能继续拼接路径
    }

    // 只替换路径字段，查询参数、主机和片段仍由原 URL 对象保留。
    u.Path = "/v2/orders"

    fmt.Println(u.String())
}

https://api.example.com/v2/orders?page=2&sort=created#summary

这个写法适合“旧路径整体替换成已确定的新路径”。如果新路径来自多个动态片段，不要先用 "/" + a + "/" + b 拼字符串，因为片段里的斜杠、空格和保留字符可能改变路径层级。

动态拼接路径时使用 JoinPath

当路径由版本号、资源名和对象 ID 等多段组成时，可以使用 u.JoinPath。它返回一个新的 URL 值，并把给定路径元素接到原路径后面，同时清理多余的 ./ 或 ../ 成分。原 URL 不会被原地改写，更适合把同一基础地址用于多个请求。

package main

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

func main() {
    base, err := url.Parse("https://api.example.com/api?tenant=demo")
    if err != nil {
        log.Fatal(err) // 先确认基础地址可解析，再组合路径
    }

    resource := "orders"
    orderID := "A-100"
    // JoinPath 只负责静态路径组合，查询参数仍沿用 base 的 RawQuery。
    requestURL := base.JoinPath(resource, orderID)

    fmt.Println(requestURL.String())
}

JoinPath 的参数应当是路径元素，不是完整 URL，也不是带 ? 的查询字符串。若某个动态值本身可能包含斜杠，需要先明确它代表一个路径片段还是多个路径层级；两者的编码策略不同。

需要改参数时再处理 RawQuery

如果任务不仅是换路径，还要新增或覆盖查询参数，就不要手写 ?a=1&b=2。通过 u.Query() 取得 url.Values，修改后再用 Encode 写回 RawQuery。

package main

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

func main() {
    u, err := url.Parse("https://api.example.com/v2/orders?page=2&sort=created")
    if err != nil {
        log.Fatal(err) // 查询参数也无法弥补无效的 URL 输入
    }

    // Query 会解码已有参数，Set 只覆盖 page，不会删除 sort。
    query := u.Query()
    query.Set("page", "3")
    query.Set("limit", "20")

    // Encode 负责重新转义参数值，并把结果写回 URL 的查询区域。
    u.RawQuery = query.Encode()
    u.Path = "/v2/orders/archive"

    fmt.Println(u.String())
}

这里的重点是先改路径，再按需要改查询参数，两者各自使用对应字段。Encode 可能重新排序键并规范化编码；如果业务必须保留原始查询串的字节顺序或某种特殊转义形式，就不要无条件调用 Query().Encode()，只改路径并保留原来的 RawQuery。

编码路径和整条 URL 重建的误区

普通路径可以直接操作 Path，但遇到编码斜杠等场景要留意 RawPath。官方文档把它定义为可选的编码路径提示，通常应通过 EscapedPath 读取，而不是直接把 RawPath 当作普通路径字符串。

另一个常见错误是这样做：

// 错误示例：把新路径解析成独立 URL，原对象的查询参数不会自动搬过来。
replacement, err := url.Parse("/v2/orders")
if err != nil {
    log.Fatal(err) // 解析失败时停止替换
}
u = replacement

replacement 是一个新的相对 URL 对象，它没有原来的主机、查询串和片段。若确实需要从另一个 URL 解析相对引用，应明确调用 ResolveReference 并理解相对引用的替换规则；单纯修改路径则没有必要走这条路径。

还要区分 PathEscape 和 QueryEscape：前者用于一个路径片段，后者用于查询参数值。把查询参数编码后的文本直接塞进路径，或者把带斜杠的整段路径交给 PathEscape，都会得到与预期不同的层级。

修改前后的检查清单

• 只换路径：直接改 u.Path，保留 RawQuery。
• 多段路径组合：优先使用 u.JoinPath，不要手工拼整条 URL。
• 新增或覆盖参数：使用 Query、Set 或 Add，最后写回 RawQuery。
• 保留原始查询串格式：不要无条件重新 Encode，因为键顺序和转义可能变化。
• 动态值含斜杠：先判断它是一个路径片段还是多个层级，再决定是否编码。
• 输出最终地址：调用 u.String()，不要把字段重新按字符串模板拼回去。

常见问题

直接修改 u.Path 会删除查询参数吗？ 不会。只要没有覆盖 *url.URL 或改写 RawQuery，查询参数仍在。

JoinPath 会返回新对象吗？ 会。它适合从同一个基础 URL 派生多个路径，调用方不必担心基础对象被原地改变。

什么时候需要手动处理 RawPath？ 只有当路径中的编码形式本身有业务意义，或需要保留编码斜杠等信息时才重点关注；普通路径优先使用 Path 与 EscapedPath。

为什么修改查询参数后 URL 顺序变了？ Values.Encode 会按自己的编码规则生成查询串，字节顺序不等同于原始输入顺序。若只改路径，保留原始 RawQuery 即可。