Go netip.AddrPort 怎样从字符串拆出地址和端口

在配置监听地址、保存服务端点或编写网络测试时，经常会拿到类似 192.0.2.10:8080 或 [2001:db8::10]:443 的字符串。想把它继续用于比较、排序或放进 map，最好不要一直手工切分字符串。

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

Go 的 netip.ParseAddrPort 会把带数字端口的 IPv4 或 IPv6 文本解析成 netip.AddrPort。成功后用 Addr() 取得 IP，用 Port() 取得端口；输入包含主机名、缺端口或非法端口时直接返回错误，而且不会替你做 DNS 解析。

ParseAddrPort 把文本变成什么

netip.AddrPort 是一个由 IP 地址和端口组成的值。它适合在配置层完成一次解析，然后把结构化结果传到拨号、监听或测试代码中。与先取两个字符串相比，它的地址部分和端口部分有明确类型，后续比较和格式化也更稳定。

最小写法如下：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 两种输入分别覆盖 IPv4 和带方括号的 IPv6 端点。
    inputs := []string{"192.0.2.10:8080", "[2001:db8::10]:443"}
    for _, raw := range inputs {
        endpoint, err := netip.ParseAddrPort(raw)
        if err != nil {
            // 解析失败时不要继续读取字段，保留原始输入便于定位配置。
            fmt.Printf("parse %q failed: %v\\n", raw, err)
            continue
        }
        // AddrPort 已经保存了结构化地址，分别读取 IP、端口和有效性。
        fmt.Printf("raw=%q addr=%s port=%d valid=%t\\n",
            raw, endpoint.Addr(), endpoint.Port(), endpoint.IsValid())
    }
}

这里的关键不是把字符串拆成两个变量，而是让解析边界集中在一个入口。后面的代码只接收 AddrPort，就不会再重复猜测 IPv6 中的冒号到底是地址内容还是端口分隔符。

IPv4、IPv6 和端口分别怎样读取

IPv4 端点可以直接写成 地址:端口；IPv6 端点必须把地址放在方括号中，例如 [2001:db8::10]:443。解析完成后，endpoint.Addr() 返回 netip.Addr，endpoint.Port() 返回 uint16。

func describe(raw string) (string, error) {
    // 统一入口负责把配置文本变成强类型端点。
    endpoint, err := netip.ParseAddrPort(raw)
    if err != nil {
        return "", fmt.Errorf("端点 %q 无法解析: %w", raw, err)
    }

    // 字段读取不再依赖 strings.LastIndex 等手工切分规则。
    return fmt.Sprintf("地址=%s，端口=%d", endpoint.Addr(), endpoint.Port()), nil
}

端口是无符号 16 位整数，因此它天然对应网络端口范围。端口 0 也可以作为值存在；是否允许系统后续选择临时端口，要由使用它的监听或拨号 API 决定。

哪些输入会返回错误

ParseAddrPort 只做数值地址和数值端口的解析，不调用 DNS。也就是说，api.example.com:443 不是它的输入；如果需求是先解析主机名，再对多个 IP 尝试连接，应使用解析器或更高层的网络 API。

常见错误可以按下面的顺序判断：

• 只有 192.0.2.10：它是地址，不是地址加端口的完整端点。
• IPv6 没有方括号：多个冒号会让地址和端口边界不明确，应使用 [IPv6]:port。
• 端口不是数字或超过可表示范围：让解析函数返回错误，不要先用字符串截断再强转。
• 主机名代替 IP：解析函数不会把它转换为地址，需在更早的配置阶段明确做名称解析。

func parseConfiguredEndpoint(raw string) (netip.AddrPort, error) {
    // 把底层错误补上配置字段名，调用方可以决定提示还是终止启动。
    endpoint, err := netip.ParseAddrPort(raw)
    if err != nil {
        return netip.AddrPort{}, fmt.Errorf("server_endpoint %q 无效: %w", raw, err)
    }
    // 保留显式的有效性判断，便于后续扩展空值或零值策略。
    if !endpoint.IsValid() {
        return netip.AddrPort{}, fmt.Errorf("server_endpoint %q 没有有效地址", raw)
    }
    return endpoint, nil
}

怎样把解析结果放进配置流程

如果一个配置文件只在启动时读取一次，可以让解析函数返回 AddrPort，业务结构体从一开始就保存值类型。这样日志、比较和 map 索引都能复用同一份结果。

type ServerConfig struct {
    Endpoint netip.AddrPort
}

func loadServerConfig(raw string) (ServerConfig, error) {
    // 启动阶段尽早拒绝错误配置，避免运行到拨号时才发现格式问题。
    endpoint, err := parseConfiguredEndpoint(raw)
    if err != nil {
        return ServerConfig{}, err
    }
    return ServerConfig{Endpoint: endpoint}, nil
}

func endpointKey(endpoint netip.AddrPort) string {
    // String 会输出适合再次识别的地址加端口形式。
    return endpoint.String()
}

对固定写在测试代码里的常量，可以使用 netip.MustParseAddrPort，但它会在错误时 panic，适合测试数据或明确由开发者控制的常量，不适合用户配置和环境变量。

什么时候改用 net.SplitHostPort

net.SplitHostPort 返回的是两个字符串，适合你必须保留原始主机文本、还要接受主机名，或者需要与旧接口对接的场景。netip.ParseAddrPort 返回的是强类型 IP 与端口，适合输入边界明确、后续要比较或存储端点的场景。

最后记住这几个边界

1. 完整端点必须同时包含数字地址和数字端口。
2. IPv6 写成带方括号的 [地址]:端口。
3. ParseAddrPort 不做 DNS；主机名要走单独的解析流程。
4. 解析成功后用 Addr()、Port() 读取字段，用 String() 重新格式化。
5. 用户输入用返回错误的函数，代码内固定常量才考虑 MustParseAddrPort。

相关问题

为什么 IPv6 必须加方括号？因为 IPv6 地址本身包含多个冒号，方括号明确了地址和端口的分界。

ParseAddrPort 会自动解析域名吗？不会，它要求地址部分是数字形式；域名解析应由独立的 Resolver 或更高层 API 完成。

端口为 0 是错误吗？不是，AddrPort 允许端口为 0；是否把 0 交给系统选择临时端口，要看后续网络操作的语义。