Go url.URL 怎样从 URL 中区分 Hostname 和 Host

在 Go 的 net/url 中，URL.Host 和 URL.Hostname() 不是两个同义字段。Host 面向 URL 的 authority 部分，可能是 example.com:8443；Hostname() 则把有效端口剥离出来，只返回主机名。需要完整连接地址时读 Host，需要域名或 IP 本身时用 Hostname()。

一句话判断：要保留端口就用 u.Host，要得到不带端口的主机名就用 u.Hostname()；IPv6 场景下，Hostname() 还会去掉字面量外层的方括号。

先把 Host 看成 authority 字段

解析一个绝对 URL 后，URL.Host 对应的是 URL 中 // 后、路径前的主机部分。它可以包含主机和端口，例如 api.example.com:8443；如果是 IPv6 字面量，通常会带着方括号，例如 [2001:db8::10]:8443。因此，Host 更适合记录原始的连接目标或交给需要 host:port 形式的接口。

下面的代码只观察解析后的字段，不把示例输出描述成线上运行证据：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// Parse 负责把 URL 文本拆成结构；失败时必须先处理 error。
	u, err := url.Parse("https://api.example.com:8443/v1/items")
	if err != nil {
		panic(err)
	}

	// Host 保留主机与端口，适合展示完整 authority。
	fmt.Println(u.Host) // api.example.com:8443
}

用 Hostname 获取纯主机名

Hostname() 是 URL 提供的语义化方法。官方文档说明，它会从 u.Host 中去掉有效端口；当结果是 IPv6 字面量时，还会移除外层方括号。这样一来，做域名匹配、主机白名单或按 IP 分类时，不必自己用字符串切分冒号。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 端口属于 Host，但不是 Hostname 的返回值。
	u, err := url.Parse("https://api.example.com:8443/v1/items")
	if err != nil {
		panic(err)
	}
	fmt.Println(u.Host)     // api.example.com:8443
	fmt.Println(u.Hostname()) // api.example.com
	fmt.Println(u.Port())   // 8443

	// IPv6 的方括号用于 URL 语法，Hostname 返回地址本身。
	ipv6, err := url.Parse("https://[2001:db8::10]:8443/health")
	if err != nil {
		panic(err)
	}
	fmt.Println(ipv6.Host)     // [2001:db8::10]:8443
	fmt.Println(ipv6.Hostname()) // 2001:db8::10
}

用 Host、Hostname 和 Port 做决策

三个访问方式解决的是不同问题：

例如，比较访问来源是否属于某个主机时，应比较 u.Hostname()，而不是比较 u.Host，否则同一主机使用不同端口会被当成两个值。反过来，调用需要 host:port 的网络接口时，不能把 Hostname() 直接当成完整地址；IPv6 还应使用 net.JoinHostPort 重新组合主机和端口。

覆盖端口与 IPv6 边界

没有显式端口时，u.Port() 返回空字符串，u.Hostname() 仍返回主机名。解析相对路径时，URL 没有 authority，Host 和 Hostname() 都可能为空，这不是解析失败，而是输入本来没有主机。真正的解析错误仍要检查 error，不要在空字段上继续猜测。

package main

import (
	"fmt"
	"net/url"
)

func describe(raw string) {
	// 相对路径可以成功解析，但没有 Host；空主机不能当作网络目标。
	u, err := url.Parse(raw)
	if err != nil {
		fmt.Printf("parse failed: %v\n", err)
		return
	}
	fmt.Printf("raw=%q host=%q hostname=%q port=%q\n",
		raw, u.Host, u.Hostname(), u.Port())
}

func main() {
	describe("https://example.com/path")
	describe("https://[2001:db8::10]:443/path")
	describe("/local/path")
}

实际编码时可以把规则压缩成一个判断：展示或保留 URL 的 authority 用 Host；只关心主机身份用 Hostname()；单独读取端口用 Port()。不要用 strings.Split(host, ":") 代替这些 API，因为 IPv6 地址本身就含有多个冒号。

常见问题

Host 一定包含端口吗？

不一定。端口是可选部分；没有显式端口时，Host 只包含主机，Port() 返回空字符串。

Hostname() 会返回 IPv6 的方括号吗？

不会。方括号是 URL 中用于包裹 IPv6 字面量的语法，Hostname() 会把它们去掉；如果要重新组合主机和端口，应使用能正确处理 IPv6 的主机端口组合 API。

参考：https://pkg.go.dev/net/url