Go net/url.ParseRequestURI 为什么不能直接解析完整 URL

遇到 url.ParseRequestURI 解析“完整 URL”失败时，先不要急着改成字符串拼接。很多输入实际上是 example.com/search?q=go 这种“主机名加路径”，它没有协议，不属于该函数接受的绝对 URI；而 https://example.com/search?q=go 带有协议，属于绝对 URI，通常可以正常解析。真正的关键是分清输入来自 HTTP 请求行，还是来自配置、表单和数据库。

官方参考：https://pkg.go.dev/net/url#ParseRequestURI

ParseRequestURI 适合解析 HTTP 请求中的绝对 URI 或绝对路径，并假定输入不带 #fragment。如果你要解析相对地址、带主机名但没有协议的字符串，或需要保留通用 URL 解析语义，应优先考虑 url.Parse，然后再按业务规则检查结果。

• /search?q=go 是绝对路径，适合作为请求目标解析。
• https://example.com/search?q=go 是绝对 URI，适合作为完整地址解析。
• example.com/search?q=go 缺少协议，不能直接当作绝对 URI。
• /search#top 含有片段，HTTP 请求目标不应把片段传到服务器端。

先判断输入是哪一种地址

排查时把“完整 URL”拆成三个维度：是否有 scheme，是否以斜杠开头，是否包含片段。ParseRequestURI 的语义不是“尽可能宽松地解析任意 URL”，而是模拟 HTTP 请求已经携带到服务端的请求目标。因此绝对 URI 和绝对路径是它的主要输入，浏览器端的 #fragment 也不应成为服务端请求目标的一部分。

为什么不带协议的地址容易失败

下面三种写法看起来都像地址，但含义不同：绝对 URI 有协议和后续资源；绝对路径只有请求路径；example.com/path 则把主机名和路径写在了一起，却没有告诉解析器它是哪个协议下的主机。对 ParseRequestURI 来说，第三种输入不满足绝对 URI 的形态，也不是以 / 开头的绝对路径。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    samples := []string{
        "/search?q=go",                  // HTTP 请求行里的绝对路径
        "https://example.com/search?q=go", // 带协议的绝对 URI
        "example.com/search?q=go",       // 缺少协议的主机加路径
        "/search?q=go#top",              // 片段不属于发往服务器的请求目标
    }

    for _, raw := range samples {
        parsed, err := url.ParseRequestURI(raw)
        if err != nil {
            // 失败时保留原始输入，便于定位是形态问题还是转义问题。
            fmt.Printf("输入 %q 解析失败：%v\n", raw, err)
            continue
        }
        // 只打印解析结果，不把解析成功误认为网络请求已经成功。
        fmt.Printf("输入 %q -> scheme=%q host=%q path=%q query=%q\n",
            raw, parsed.Scheme, parsed.Host, parsed.Path, parsed.RawQuery)
    }
}

这个示例的重点不是记住某条错误文本，而是观察输入形态。对于绝对路径，Host 和 Scheme 为空是正常的；对于带协议的绝对 URI，二者通常会被解析出来。解析函数只负责把字符串拆成 URL 结构，不负责访问目标主机。

用 url.Parse 处理通用 URL

如果输入来自配置文件、数据库字段或用户表单，来源通常不保证它已经是 HTTP 请求目标。这时可以先使用 url.Parse，再决定是否要求协议、主机或绝对路径。url.Parse 支持相对地址和绝对地址，但它更宽松，并不替你完成业务校验。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    raw := "example.com/search?q=go"
    parsed, err := url.Parse(raw)
    if err != nil {
        // 语法错误仍然要直接返回，不能靠补协议掩盖坏输入。
        fmt.Println("URL 语法错误：", err)
        return
    }

    if parsed.Scheme == "" {
        // 这里是业务策略：没有协议就拒绝，而不是把它当成可访问地址。
        fmt.Println("缺少协议，不能作为绝对 URL 使用")
        return
    }

    fmt.Printf("可继续处理：scheme=%s host=%s path=%s\n",
        parsed.Scheme, parsed.Host, parsed.Path)
}

如果业务确定要求绝对地址，可以在 url.Parse 之后检查 Scheme 和 Host；如果业务接受站内相对路径，则不应因为 Scheme 为空就一律报错。校验规则要跟输入来源匹配。

排查时怎样选函数

几个容易误判的边界

带 https 的地址也会失败吗？

带协议的绝对 URI 在形态上符合 ParseRequestURI 的主要输入范围；如果仍然失败，应继续检查非法转义、控制字符或其他语法问题，不要先把问题归咎于“完整 URL 不支持”。

绝对路径为什么没有 host？

绝对路径本来就只描述请求路径和查询串，例如 /health?full=1。它不包含服务器主机，主机通常来自当前连接或请求上下文。

能不能给缺少协议的字符串自动补上 https？

只有在业务明确规定默认协议、并且输入来源可信时才可以补。更稳妥的做法是把“补协议”作为显式归一化步骤，并记录原始输入；不要把任意用户输入静默变成外部请求地址。

解析成功后还需要检查什么？

至少检查是否允许目标协议、是否必须有主机、路径是否符合业务格式，以及查询参数是否满足类型和长度限制。解析库解决的是语法分解，不是权限、网络连通性或业务合法性。

结论

ParseRequestURI 不是通用的“任意地址解析器”，它按 HTTP 请求目标解释输入：接受绝对 URI 或绝对路径，并假定没有片段。所谓“完整 URL”如果只是 example.com/path，本质上缺少协议；如果输入来自配置或表单，先用 url.Parse 再做明确的 scheme、host 和业务校验，通常更容易定位问题。