Go netip.ParseAddr 为什么拒绝带端口字符串

我在处理监听地址配置时，最容易遇到的一类误解是：看到 192.0.2.10:8080，就顺手把它交给 netip.ParseAddr。这个函数拒绝输入并不是端口格式写错了，而是它的输入契约只描述一个 IP 地址；端口属于 netip.AddrPort，应使用 netip.ParseAddrPort。

记住一句话：只有 IP 地址用 ParseAddr，IP 加数字端口用 ParseAddrPort。IPv6 端点要写成 [地址]:端口，端口不能写成服务名。

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

一、ParseAddr 为什么会拒绝带端口的字符串

netip.ParseAddr 返回的是一个 netip.Addr。它处理的是 IPv4、IPv6，或者带区域标识的 IPv6 地址，例如 192.0.2.10、2001:db8::7 和 fe80::1%eth0。字符串中的 :8080 不属于地址本身，所以把它拼进输入后，解析器会把整个文本视为“不符合 IP 地址格式”。

这里的关键不是“ParseAddr 不支持网络地址”，而是地址和端点是两个不同的数据对象：

如果配置字段的语义是“主机地址”，就不要为了兼容端口而先截断字符串。截断会把输入契约藏起来，也可能把本来应该报错的配置误当成另一台主机。先确定字段代表 Addr 还是 AddrPort，再选择解析函数，代码会更清楚。

二、带端口时改用 ParseAddrPort

最小写法是让 ParseAddrPort 一次完成地址和端口解析，然后通过 Addr() 与 Port() 分别取出两个部分：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 端点字符串同时包含 IP 和十进制端口，使用 AddrPort 作为目标类型。
    endpoint, err := netip.ParseAddrPort("192.0.2.10:8080")
    if err != nil {
        // 外部配置解析失败时返回错误，避免把零值继续传给网络层。
        panic(err)
    }

    // AddrPort 将地址和端口分开暴露，便于分别记录、比较或传给下游 API。
    fmt.Println(endpoint.Addr())
    fmt.Println(endpoint.Port())
}

解析成功后，endpoint.Addr() 是 netip.Addr，endpoint.Port() 是 uint16。端口为 0 也属于合法的数值端口；它是否代表“让系统选择端口”，要由调用方的监听或连接语义决定，而不是由解析器替你判断。

如果地址和端口已经是分开的字段，也可以跳过拼接字符串，直接构造端点：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 地址字段和端口字段已经分别完成了自己的类型转换。
    ip := netip.MustParseAddr("203.0.113.7")
    port := uint16(443)

    // AddrPortFrom 不再解析文本，适合字段已经分离的内部数据。
    endpoint := netip.AddrPortFrom(ip, port)
    fmt.Println(endpoint.String())
}

对外部输入不要照搬 MustParseAddr。它遇到错误会 panic，官方文档也将这类 Must 函数定位在硬编码测试数据等确定不会失败的场景。配置文件、HTTP 参数和环境变量都应优先使用返回 (值, error) 的解析函数。

三、IPv6 端点为什么必须加方括号

IPv6 地址本身就包含多个冒号。如果直接写成 2001:db8::7:443，文本无法清楚表达最后的 443 是地址的一部分还是端口。端点格式因此使用方括号包住 IPv6 地址：[2001:db8::7]:443。

区域标识也属于地址部分，放在右方括号之前，例如 [fe80::1%eth0]:8080。这里的 %eth0 不是端口，也不能把它拆到方括号外。

package main

import (
    "fmt"
    "net/netip"
)

func showEndpoint(text string) {
    // ParseAddrPort 要求地址和端口都能按数字形式解析，不负责 DNS 查询。
    endpoint, err := netip.ParseAddrPort(text)
    if err != nil {
        // 记录原始输入，便于定位是缺少方括号、端口非数字还是地址本身无效。
        fmt.Printf("无法解析 %q: %v\n", text, err)
        return
    }

    // String 会按 AddrPort 的规范形式重新组合地址和端口。
    fmt.Printf("地址=%s 端口=%d\n", endpoint.Addr(), endpoint.Port())
}

func main() {
    showEndpoint("203.0.113.7:443")
    showEndpoint("[2001:db8::7]:443")
    showEndpoint("[fe80::1%eth0]:8080")
}

还有一个常见误区是把 example.com:443 直接交给 ParseAddrPort。这个函数只解析数字地址和数字端口，不做名称解析。如果输入确实是域名，应先按业务需要使用 DNS 或连接层 API；不要把域名解析失败误认为是端口分隔符问题。

四、把输入边界固定在解析层

在配置或接口边界，建议把“原始字符串解析”和“下游使用”分成两步。解析层只负责确认文本是否符合目标类型；通过后再把强类型的 Addr 或 AddrPort 交给监听、连接、路由或日志代码。

可以按下面的规则快速判断：

• 字段只允许 IP：用 netip.ParseAddr，接受 IPv4、IPv6 和带 zone 的 IPv6。
• 字段表达 host:port：用 netip.ParseAddrPort，IPv6 写成 [addr]:port。
• 地址与端口已经是强类型字段：用 netip.AddrPortFrom，避免不必要的字符串拼接。
• 输入是域名或服务名：不要期待 netip 自动解析，先完成名称解析或服务名映射。
• 只有测试中的固定常量才适合 MustParseAddr 或 MustParseAddrPort。

netip.AddrPort 也适合作为 map 的键或结构体字段，因为它把一个端点作为明确的值对象保存。比起在各处保存未拆分的字符串，这样可以更早暴露端口为空、IPv6 未加方括号等输入问题。

五、几个容易混淆的问题

ParseAddr 能不能先解析再从字符串里截取端口？

不建议。对于带端口的完整文本，直接使用 ParseAddrPort 能保留地址、端口和错误边界；手动截取还要自行处理 IPv6 冒号和方括号。

端口写成 http 或 https 可以吗？

不可以直接交给 ParseAddrPort。它要求端口是数字；服务名到端口号的映射属于另一个步骤。

端口为 0 是不是解析错误？

不是。AddrPort.IsValid 只要求其中的地址有效，端口包括 0 在内都属于有效值。端口 0 的具体含义由监听或连接 API 决定。

总结

ParseAddr 拒绝 192.0.2.10:8080，是因为它只负责把文本解析成 netip.Addr，不会把端口偷偷塞进地址。需要完整端点时使用 ParseAddrPort；IPv6 端点写成 [IPv6]:端口，并保证端口是数字。把这个类型边界放在输入层，后续网络代码就不需要重复猜字符串格式。