Go net/url 怎样拆解并重建地址

Go 里处理地址，推荐把“拆解”和“重建”分成两个动作：先用 url.Parse 得到 *url.URL，再用 Values 改查询参数、用 JoinPath 组合路径，最后交给 URL.String 输出。这样可以避免手工拼接时漏掉转义、问号或井号。

先把 URL 拆成可判断的组件

一个地址通常由 scheme、host、path、query 和 fragment 组成。url.Parse 既能解析绝对地址，也能解析相对路径；解析主机名和路径但缺少 scheme 的字符串存在歧义，不能把“解析成功”当成“输入一定是业务允许的绝对地址”。

package main

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

func main() {
    raw := "https://api.example.test/v1/users/张三?active=1&tag=go#profile"
    u, err := url.Parse(raw)
    if err != nil {
        // 解析失败时立即停止，避免继续使用不完整的 URL 结构。
        log.Fatal(err)
    }

    fmt.Println(u.Scheme)    // https
    fmt.Println(u.Host)      // api.example.test
    fmt.Println(u.Path)      // /v1/users/张三
    fmt.Println(u.RawQuery)  // active=1&tag=go
    fmt.Println(u.Fragment)  // profile
    fmt.Println(u.EscapedPath()) // /v1/users/%E5%BC%A0%E4%B8%89
}

Path 面向程序语义，EscapedPath() 面向重新输出。比如原地址使用了 %2F，解析后路径字段可能表现为斜杠；要判断原始编码，就不要直接读取 RawPath，优先调用 EscapedPath。

查询参数要通过 Values 修改

u.Query() 返回 url.Values，它把同名参数保留为字符串切片。读取一个值可以用 Get，区分参数是否存在可以用 Has，修改后要把编码结果写回 RawQuery。

import (
    "net/url"
    "strconv"
)

func addPaging(raw string, page int) (string, error) {
    u, err := url.Parse(raw)
    if err != nil {
        // 将原始输入错误向上返回，让调用方决定是否返回 400。
        return "", err
    }
    q := u.Query()
    q.Set("page", strconv.Itoa(page))
    q.Set("format", "json")
    u.RawQuery = q.Encode() // Encode 会按 URL 查询规则转义键和值。
    return u.String(), nil
}

上面的函数还需要导入 strconv。如果需要保留多个同名参数，使用 Add；如果要删除某个键，使用 Del。不要只修改局部变量 q 就返回，因为 Query 得到的是要重新编码写回的参数集合。

路径、相对引用和完整地址的重建方式

路径片段和查询参数使用的是不同的转义规则。单个路径片段里如果包含斜杠，应先用 PathEscape；多个已经准备好的片段可以交给 JoinPath，它会清理 ./ 和 ../。完整地址最后用 String 输出。

func buildUserURL(base string, userID string) (string, error) {
    // PathEscape 只处理一个片段，避免 userID 中的斜杠改变路径层级。
    escapedID := url.PathEscape(userID)
    result, err := url.JoinPath(base, "v1", "users", escapedID)
    if err != nil {
        // base 不是可接受的 URL 时，不返回半成品地址。
        return "", err
    }
    return result, nil
}

func resolveAsset(base string) (string, error) {
    root, err := url.Parse(base)
    if err != nil {
        return "", err
    }
    ref, err := url.Parse("../assets/logo.svg")
    if err != nil {
        return "", err
    }
    return root.ResolveReference(ref).String(), nil
}

ResolveReference 适合“页面地址 + 相对资源”的场景；它不是字符串连接器。如果业务要求只允许站内路径，还应在解析后检查 scheme、hostname 和最终路径，再交给 HTTP 客户端。

上线前的排查清单

• 输入来自 HTTP 请求时，先明确要接受绝对 URI、绝对路径还是相对地址；不要只判断 err == nil。
• 记录日志时优先使用 u.Redacted()，避免把 URL 中的用户密码直接写入日志。
• 需要保留编码细节时使用 EscapedPath 和 EscapedFragment，不要依赖 RawPath 的偶然内容。
• 修改 query 后重新调用 Encode；输出前检查是否意外保留了旧的 Fragment 或空的强制问号。

常见问题

为什么 Path 和原始地址看起来不一样

Path 保存的是解码后的路径语义，原始转义提示由 RawPath 辅助保存。需要输出时调用 EscapedPath，不要直接把两个字段混用。

修改 u.Query() 后为什么地址没有变化

查询参数需要重新编码并赋值给 u.RawQuery：q := u.Query(); q.Set("k", "v"); u.RawQuery = q.Encode()。

PathEscape 能不能直接处理整条路径

不建议。它会把整条字符串当作一个路径片段；应按片段转义，再用 JoinPath 组合。