当前位置：首页 > 文章列表 > Golang > Go教程 > Go netip.ParseAddrPort 怎么校验 host:port：IPv6 方括号与端口边界

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

来源：17golang原创 2026-08-27 19:51:17 0浏览收藏

配置文件里把监听地址写成 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()。

实践要点

127.0.0.1:8080 和 localhost:8080 都是完整输入，但 2001:db8::1:8080 缺少 IPv6 方括号。
ParseAddrPort 只负责解析 IP 地址和数字端口，不替你做 DNS 解析。
解析失败时保留原始错误，按缺少端口、非法地址和端口越界分别给出提示。

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

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

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

Go netip.ParseAddrPort 从 host:port 输入到 Addr 和 Port 的数据流示意图 — 完整 host:port 输入进入 netip.ParseAddrPort，成功后再拆出 Addr 与 Port。

先把完整输入交给 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，也不要擅自当成默认端口，默认值应该由配置层明确提供。

Go netip.ParseAddrPort 成功分支与错误分支的真实校验流程图 — ParseAddrPort 返回 err 时停止拆分；成功时才读取 Addr 与 Port。

测试四个容易混淆的输入

测试重点不是把所有字符串都列出来，而是固定住协议边界。下面的用例分别验证普通 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)
        }
    }
}