Go net/url URL.Hostname 解析 IPv6 地址的主机名

解析 URL 时，u.Host 不是“纯主机名”：它可能同时包含端口，IPv6 字面量还会带方括号。需要把主机和端口分别交给下游代码时，优先使用 u.Hostname() 与 u.Port()，不要自己按冒号切字符串。对 https://[2001:db8::7]:8443/api，前者得到 2001:db8::7，后者得到 8443。

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

先看现象：Host 不是纯主机名

net/url 的 URL 结构把主机和端口放在 Host 字段中。例如普通域名可能是 api.example.com:443，IPv6 形式则必须写成 [2001:db8::7]:8443。如果直接把 Host 当成主机名传给连接器，端口会混进去；如果用 strings.Split(host, ":")，IPv6 内部的多个冒号又会被误认为字段分隔符。

第一层检查：先确认 Parse 成功

字段读取的第一步不是打印结果，而是处理 url.Parse 的错误。解析失败时，返回的 URL 不能被当成有效输入继续使用；把错误留到网络请求阶段才处理，会让问题位置变得模糊。

package main

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

func main() {
    raw := "https://api.example.com:443/v1/users"
    u, err := url.Parse(raw)
    if err != nil {
        // 输入可能来自配置或请求参数，解析失败时应立即返回。
        log.Fatalf("parse URL: %v", err)
    }

    // Host 保留主机与端口，Hostname 和 Port 负责拆出可用字段。
    fmt.Println("Host:", u.Host)
    fmt.Println("Hostname:", u.Hostname())
    fmt.Println("Port:", u.Port())
}

对这段输入，Host 是 api.example.com:443，Hostname() 是 api.example.com，Port() 是 443。这里的要点是：Hostname() 与 Port() 读取的是同一个已解析 URL，不需要再写一套字符串拆分规则。

第二层判断：用 Hostname 和 Port 读取 IPv6

IPv6 的地址本身包含冒号，所以 URL 语法用方括号包住字面量，再在方括号外写端口。Go 的 Hostname() 会去掉合法端口；如果主机是方括号包裹的 IPv6 字面量，还会移除方括号。

package main

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

func main() {
    raw := "https://[2001:db8::7]:8443/api"
    u, err := url.Parse(raw)
    if err != nil {
        // 只有解析成功后，Hostname 和 Port 的结果才有意义。
        log.Fatalf("parse IPv6 URL: %v", err)
    }

    // Host 保留 URL 语法中的方括号和端口，便于还原原始主机字段。
    fmt.Println(u.Host)      // [2001:db8::7]:8443
    fmt.Println(u.Hostname()) // 2001:db8::7
    fmt.Println(u.Port())     // 8443
}

下游如果需要拼接网络地址，不能把 Hostname() 直接和冒号相连，因为 IPv6 需要再次加方括号。可以使用 net.JoinHostPort 统一完成这一层格式化：

package main

import (
    "fmt"
    "net"
)

func main() {
    host := "2001:db8::7"
    port := "8443"

    // JoinHostPort 会按主机类型决定是否补 IPv6 方括号。
    address := net.JoinHostPort(host, port)
    fmt.Println(address) // [2001:db8::7]:8443
}

IPv6 边界：Zone、缺失端口和非法端口要分开看

IPv6 链路本地地址可能带 Zone，例如 [fe80::7%25eth0]:5353。URL 文本中的百分号需要按 URL 规则转义，Hostname() 返回的主机名会带 Zone 语义。没有端口时，Port() 返回空字符串；不要擅自把空字符串改成某个默认端口，默认值应由业务协议决定。

package main

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

func main() {
    samples := []string{
        "https://example.com/path",             // 没有端口
        "https://[fe80::7%25eth0]:5353/query", // IPv6 Zone 使用 URL 转义
        "https://example.com:not-a-port/path",  // 非数字端口
    }

    for _, raw := range samples {
        u, err := url.Parse(raw)
        if err != nil {
            // 每个输入单独报告错误，避免一个坏值终止整批处理。
            log.Printf("skip %q: %v", raw, err)
            continue
        }
        // 空 Port 只表示没有有效数字端口，不等于协议默认端口。
        fmt.Printf("host=%q port=%q raw=%q\n", u.Hostname(), u.Port(), u.Host)
    }
}

非法端口的具体表现应以解析结果和错误为准，不要为了“得到一个端口”而从 Host 中截取最后一段。尤其是 IPv6 地址，最后一段可能只是地址的一部分。

反向复查：把读取结果交给下游前再确认一次

如果代码要创建连接地址、记录访问日志或做主机白名单判断，可以在边界处明确字段契约：白名单比较使用 Hostname()，端口策略使用 Port()，需要重新组成 host:port 时使用 net.JoinHostPort。这样可以避免把展示格式和业务字段混在一起。

速查清单

• Host 可能同时包含主机和端口，IPv6 还可能包含方括号。
• Hostname() 返回不含合法端口的主机部分，IPv6 字面量不带方括号。
• Port() 返回不含冒号的端口字符串；空值需要由业务决定如何处理。
• 需要还原 host:port 时使用 net.JoinHostPort。
• 先处理 url.Parse 错误，再进入字段判断和后续网络操作。

相关问题

为什么不能用 strings.Split(u.Host, ":")？

因为 IPv6 字面量内部本来就有多个冒号，分割后无法可靠区分地址分隔符和端口分隔符。使用 URL 的字段方法和 net.JoinHostPort 才能保持语义。

Hostname() 返回值为什么没有 IPv6 方括号？

方括号属于 URL 中区分主机与端口的语法标记，不是 IPv6 主机名本身。需要重新放回 URL 或网络地址格式时，再交给 net.JoinHostPort 补回。

Port() 是数字类型吗？

不是，它返回字符串。这样可以保留“没有有效端口”的空值状态；如果业务需要数值，应在边界处单独转换并处理转换错误。