Go net/netip AddrPort 如何解析带端口地址

处理配置文件、服务发现或监听地址时，host:port 不应该再手动按冒号切分。Go 的 net/netip 提供了 netip.ParseAddrPort：它把数字 IP 和数字端口一次解析成 netip.AddrPort，IPv6 使用 [地址]:端口 写法。

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

最小写法是 p, err := netip.ParseAddrPort("127.0.0.1:8080")。解析成功后用 p.Addr() 和 p.Port() 取字段；解析失败就不要把结果交给后续连接配置。

先把字符串解析成 AddrPort，再拆出地址和端口

AddrPort 是 IP 地址和端口的组合值。解析函数返回一个值和一个 error，因此适合直接放进配置加载、请求参数或服务发现的边界处。下面三种输入分别覆盖 IPv4、普通 IPv6 和带区域标识的 IPv6：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    inputs := []string{
        "127.0.0.1:8080",
        "[2001:db8::1]:443",
        "[fe80::1%eth0]:5353",
    }

    for _, raw := range inputs {
        // 解析阶段只接收数字 IP 和数字端口，不会替你查询域名。
        endpoint, err := netip.ParseAddrPort(raw)
        if err != nil {
            fmt.Printf("%q 解析失败：%v\n", raw, err)
            continue
        }
        // 结构化读取避免再次按冒号切分 IPv6 文本。
        fmt.Printf("%q -> addr=%s port=%d normalized=%s\n",
            raw, endpoint.Addr(), endpoint.Port(), endpoint.String())
    }
}

这里的关键不是把字符串“切成两半”，而是让解析器识别 IPv4 和 IPv6 的不同边界。IPv4 的最后一个冒号可以分隔端口；IPv6 本身包含多个冒号，所以必须用方括号包住地址。解析后的 Addr() 返回 netip.Addr，Port() 返回 uint16，String() 则可生成规范化的地址端口文本。

把解析结果放进连接配置前先判断有效性

工程代码通常不应只看返回值是否“长得像地址”。先检查 err，再按业务需要检查 IsValid()。零值 netip.AddrPort{} 无效；但一个合法 IP 配合端口 0 仍然有效，端口 0 常用于让系统选择临时端口。

func parseEndpoint(raw string) (netip.AddrPort, error) {
    // 让错误停在输入边界，调用方不会拿到可疑的半成品。
    endpoint, err := netip.ParseAddrPort(raw)
    if err != nil {
        return netip.AddrPort{}, fmt.Errorf("地址端口 %q 无效: %w", raw, err)
    }
    // IsValid 关注地址是否初始化；不要把端口0误当成失败。
    if !endpoint.IsValid() {
        return netip.AddrPort{}, fmt.Errorf("地址端口 %q 没有有效 IP", raw)
    }
    return endpoint, nil
}

如果业务要求“必须显式指定非零端口”，应在成功解析之后另写 endpoint.Port() == 0 的业务规则，而不是把它混入通用解析判断。这样网络层的格式校验和应用层的配置策略各自清楚。

常见解析错误，先看输入形状再改代码

遇到 not an ip:port、no port 或端口解析错误时，优先打印原始输入并检查来源。常见问题有三类：漏写端口、把域名当成 IP、把 IPv6 当成普通冒号分隔字符串。端口超过 65535 或包含非数字字符，也会在端口转成 uint16 时失败。

net.SplitHostPort 与 netip.ParseAddrPort 解决的问题不同：前者负责拆分 host 和 port，后者进一步要求 host 是可解析的数字 IP。只需要保存地址端口值时，直接使用 AddrPort 可以少一次手工转换；如果输入允许域名，应先按业务做 DNS 解析，再把解析出的 IP 与端口组合。

相关问题

ParseAddrPort 能解析 localhost:8080 吗？

不能。它要求地址和端口都是数字，不负责把 localhost 解析为回环地址。域名场景应使用 DNS 解析流程。

IPv6 地址为什么必须写方括号？

因为 IPv6 地址内部已经有多个冒号，方括号为端口分隔符提供了明确边界，例如 [::1]:8080。

AddrPort 的端口为 0 是错误吗？

不是。官方文档明确指出所有端口都有效，包括 0；是否允许临时端口由应用配置策略决定。

什么时候使用 MustParseAddrPort？

只建议用于测试或写死且确定正确的字符串。外部配置和用户输入应使用 ParseAddrPort 并显式处理错误，因为 MustParseAddrPort 出错会 panic。