Go netip.ParseAddrPort 怎么校验 host:port：IPv6 方括号与端口边界

配置文件里把监听地址写成 127.0.0.1:8080 通常没什么悬念，换成 IPv6 后，2001:db8::1:8080 就容易被误判。Go 的 netip.ParseAddrPort 专门处理这种 host:port 输入：普通地址可以直接解析，IPv6 必须使用方括号，端口还要落在 0 到 65535 之间。

把用户输入当作完整的 host:port 交给 netip.ParseAddrPort，不要先按冒号手工切分；IPv6 写成 [2001:db8::1]:8080，解析成功后再读取 Addr() 和 Port()。

为什么 IPv6 的 host:port 必须加方括号

IPv4 的地址本身不含冒号，看到最后一个冒号就能大致分开主机和端口。IPv6 地址内部却有多个冒号，2001:db8::1:8080 既可能被理解成一个地址，也可能被误解成地址加端口。标准写法用方括号标出主机部分：[2001:db8::1]:8080。

这也是使用标准解析器的第一个好处：格式规则集中在一个函数里，调用方不必维护一套“最后一个冒号是否属于 IPv6”的分支。

先把完整输入交给 ParseAddrPort

下面的函数只接受完整的地址字符串。解析成功后返回 netip.AddrPort；失败时不继续猜测输入意图，这一点很重要，避免把错误地址“修”成另一个地址。

package main

import (
    "fmt"
    "net/netip"
)

func parseListenAddress(raw string) (netip.AddrPort, error) {
    addrPort, err := netip.ParseAddrPort(raw)
    if err != nil {
        return netip.AddrPort{}, fmt.Errorf("监听地址 %q 无效: %w", raw, err)
    }
    return addrPort, nil
}

func main() {
    addrPort, err := parseListenAddress("[2001:db8::1]:8080")
    if err != nil {
        panic(err)
    }
    fmt.Println(addrPort.Addr(), addrPort.Port())
}

这里的调用链很短：parseListenAddress 调用 netip.ParseAddrPort，成功后由返回值提供 Addr() 与 Port()。如果输入是 localhost:8080，解析会失败，因为 ParseAddrPort 要的是 IP 地址，不是需要 DNS 查询的主机名。

按错误边界给出可操作的提示

校验函数最好只做解析，不在内部偷偷替换方括号、补默认端口或解析域名。调用处可以把几类常见输入放在表格驱动的测试里，先确认行为，再决定界面提示。

func check(raw string) string {
    addrPort, err := netip.ParseAddrPort(raw)
    if err != nil {
        return fmt.Sprintf("%s：请填写 IP:端口，IPv6 使用方括号", raw)
    }
    return fmt.Sprintf("地址=%s，端口=%d", addrPort.Addr(), addrPort.Port())
}

// 这些输入分别覆盖 IPv4、IPv6 和错误格式。
inputs := []string{
    "127.0.0.1:8080",
    "[2001:db8::1]:8080",
    "2001:db8::1:8080",
    "127.0.0.1:65536",
}

对于 127.0.0.1:65536 这类端口越界输入，解析器会拒绝它；成功路径只会拿到合法的 Port()。对于缺少端口的 127.0.0.1，也不要擅自当成默认端口，默认值应该由配置层明确提供。

测试四个容易混淆的输入

测试重点不是把所有字符串都列出来，而是固定住协议边界。下面的用例分别验证普通 IPv4、带方括号的 IPv6、缺少方括号的 IPv6，以及端口越界。

func TestParseListenAddress(t *testing.T) {
    tests := []struct {
        raw string
        ok  bool
    }{
        {"127.0.0.1:8080", true},
        {"[2001:db8::1]:8080", true},
        {"2001:db8::1:8080", false},
        {"127.0.0.1:65536", false},
    }

    for _, test := range tests {
        _, err := parseListenAddress(test.raw)
        if (err == nil) != test.ok {
            t.Fatalf("raw=%q err=%v wantOK=%v", test.raw, err, test.ok)
        }
    }
}

几个不要混在一起的判断

解析地址不等于建立连接

ParseAddrPort 只检查字符串能否表示 IP 和端口。它不会确认目标可达，也不会打开 TCP 或 UDP 连接；连通性要在后续网络操作中单独处理。

不要先 strings.Split(raw, ":")

手工切分会把 IPv6 的内部冒号和端口分隔符混为一谈，还会让空端口、额外冒号等情况散落在业务代码里。完整输入交给标准库，边界更集中。

不要把失败输入自动补成默认端口

如果产品确实允许省略端口，可以先在配置层明确拼出完整字符串，再调用解析器；这样日志里仍能看到用户原始输入和最终配置值的区别。

相关问题

netip.ParseAddrPort 能解析域名吗？

不能。它面向 IP 地址和端口；域名需要先做 DNS 解析，再把得到的 IP 与端口交给后续逻辑。

IPv6 一定要写方括号吗？

在 host:port 这种组合格式里应当写。单独表示 IPv6 地址时不需要，但一旦后面跟端口，方括号就是区分主机和端口的边界。

什么时候读取 Addr() 和 Port()？

只有 err == nil 时读取。错误分支返回零值并保留错误信息，调用方再决定如何提示或拒绝配置。

小结

校验监听地址时，最稳妥的顺序是：保留完整输入，调用 netip.ParseAddrPort，成功后读取 Addr() 和 Port()，失败则按格式错误处理。IPv6 的方括号不是装饰，而是 host:port 语法里不可省略的分隔边界。