Go netip.AddrPort 怎么无歧义表示 IPv6 端口

Go 里表示“IPv6 地址加端口”，不要把字符串简单拼成 2001:db8::8a2e:370:7334:443。IPv6 地址本身就包含多个冒号，正确的文本边界是 [2001:db8::8a2e:370:7334]:443；进入程序后，优先把它解析为 netip.AddrPort，让地址和端口保持结构化。

IPv6 端口为什么必须用方括号

解析器需要知道最后一个冒号是不是端口分隔符。IPv4 的 192.0.2.8:443 只有一个明显分隔点，但 IPv6 的 2001:db8::8a2e:370:7334 内部已经有冒号。如果继续裸拼，程序无法稳定区分“地址结束”和“端口开始”。方括号把地址整体包起来，外层的最后一个冒号才承担端口分隔职责。

这条规则也适用于带 zone 的链路本地地址，例如 [fe80::1%eth0]:8080。zone 属于 IPv6 地址的一部分，端口仍然在右方括号之后；不要把 %eth0 当成端口或额外字段。

已知地址优先使用 AddrPortFrom 构造

如果地址已经由配置或其他 API 得到，直接构造值更稳。端口参数是 uint16，这让范围边界在调用处变得明确；来自表单、环境变量或 JSON 的整数则应先检查是否落在 0 到 65535，再转换。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 先解析纯地址，再把已确认范围内的端口交给 AddrPortFrom。
    addr, err := netip.ParseAddr("2001:db8::8a2e:370:7334")
    if err != nil {
        panic(err) // 示例输入是常量；真实服务应返回可处理的错误。
    }
    endpoint := netip.AddrPortFrom(addr, 443)

    // String 会按 IPv6 的无歧义格式输出，适合日志和连接参数。
    fmt.Println(endpoint.String())
    fmt.Println(endpoint.Addr(), endpoint.Port())
}

这里的返回值包含地址和端口两个独立字段，比较、排序或作为 map key 时不必再次拆字符串。AddrPortFrom 本身不分配；真正需要关注的是上游地址是否有效以及端口转换前是否经过范围检查。

外部输入用 ParseAddrPort 统一判断

配置文件和请求参数通常给的是完整的地址端口文本，这时用 ParseAddrPort 比手工 Split 更安全。它不做 DNS 解析，地址和端口都必须是数字；解析失败时保留错误，让调用方决定提示、丢弃还是回退。

package main

import (
    "fmt"
    "net/netip"
)

func parseEndpoint(text string) (netip.AddrPort, error) {
    // ParseAddrPort 同时处理 IPv4:port 与 [IPv6]:port 的边界。
    endpoint, err := netip.ParseAddrPort(text)
    if err != nil {
        return netip.AddrPort{}, fmt.Errorf("地址端口无效 %q: %w", text, err)
    }
    // IsValid 检查地址部分；端口 0 仍是合法端口值。
    if !endpoint.IsValid() {
        return netip.AddrPort{}, fmt.Errorf("地址无效: %q", text)
    }
    return endpoint, nil
}

2001:db8::1:443 不应被猜测成合法 IPv6 端点；应要求输入者写成 [2001:db8::1]:443。同样，[2001:db8::1]:https 也会失败，因为这个 API 不负责服务名到端口号的解析。

参数边界与排查清单

连接 TCP 时还要留意其他 API 的边界。例如 net.TCPAddr.AddrPort 会把地址转换为 netip.AddrPort，其端口字段最终按 uint16 表示；业务层仍应在更早位置校验来源数据，不要依赖窄化后的值“碰巧可用”。

常见问题

AddrPort.String 会不会漏掉 IPv6 方括号？

不会。它会根据地址族生成可再次解析的无歧义文本；IPv6 地址会放在方括号内。

端口 0 是不是 ParseAddrPort 的错误？

不是。AddrPort 的端口字段是 uint16，0 在类型层面有效；是否允许由监听、代理或配置业务决定。

什么时候可以用 MustParseAddrPort？

只建议用于测试或源码中的硬编码常量。用户输入、配置和网络数据都应使用带错误返回的 ParseAddrPort，避免一个格式错误直接触发 panic。