Go netipAddrPort 解析缺少端口时怎么办

netip.ParseAddrPort 要求输入同时包含 IP 字面量和数字端口，不会在缺端口时自动补 0、80 或 443。配置允许省略端口时，应由业务先约定默认值，再将裸 IP 解析成 netip.Addr，用 netip.AddrPortFrom 构造结果；格式有误的显式端口不能被悄悄修复。

设想一个配置迁移场景：旧配置只写 IP，新代码改用 AddrPort 后开始报错。问题不一定是 Go 升级改变了规则，而可能是输入契约从“地址”变成了“地址与端口”。本文只迁移这层业务契约，不宣称标准库发生了新的破坏性变更。官方文档：https://pkg.go.dev/net/netip#ParseAddrPort。

缺端口是输入契约问题，不是自动补零

先决定字段究竟支持哪种格式。如果端口必须填写，就保留 ParseAddrPort 错误并要求修正配置；如果允许纯 IP，就明示默认端口和适用协议。AddrPort 只存地址与端口，不知道应用使用 HTTP、HTTPS 还是其他协议，因此不可能替你选择正确默认值。

只给完整裸IP添加业务默认端口

不要用“字符串含不含冒号”来猜端口，IPv6 地址本身就有冒号；也不要按错误文案包含 missing port 决定如何修补。下面先尝试显式端点，失败后只接受完整裸 IP，其他输入保持为错误。程序仅做内存中的字符串解析，未在本文执行。

package main

import (
    "fmt"
    "net/netip"
)

// endpoint 接受显式IP端口，或完整裸IP；默认端口来自业务配置。
func endpoint(s string, defaultPort uint16) (netip.AddrPort, bool, error) {
    if defaultPort == 0 {
        return netip.AddrPort{}, false, fmt.Errorf("默认目标端口不能为零")
    }
    ap, endpointErr := netip.ParseAddrPort(s)
    if endpointErr == nil {
        // 零端口是合法语法，但本例的目标地址策略不允许它。
        if ap.Port() == 0 {
            return netip.AddrPort{}, false, fmt.Errorf("显式目标端口不能为零")
        }
        return ap, false, nil
    }
    // 只有完整裸IP才补默认值，不按错误字符串猜测是否缺端口。
    ip, ipErr := netip.ParseAddr(s)
    if ipErr != nil {
        return netip.AddrPort{}, false,
            fmt.Errorf("输入既不是IP端口也不是裸IP: %w", endpointErr)
    }
    return netip.AddrPortFrom(ip, defaultPort), true, nil
}

func main() {
    // 文档保留地址只用于本地解析，不发起任何网络连接。
    inputs := []string{
        "192.0.2.40", "192.0.2.40:9443",
        "2001:db8::40", "[2001:db8::40]:9443",
        "192.0.2.40:", "[2001:db8::40]",
        "192.0.2.40:65536", "192.0.2.40:0",
        "api.example:9443", "2001:db8::40:9443",
    }
    for _, input := range inputs {
        ap, usedDefault, err := endpoint(input, 8443)
        if err != nil {
            fmt.Printf("%q -> error: %v\n", input, err)
            continue
        }
        // 保留是否补默认端口，方便配置迁移时定位来源。
        fmt.Printf("%q -> %s default=%t\n", input, ap, usedDefault)
    }
}

函数额外返回 usedDefault，用于区分用户显式选择的端口与迁移层补入的端口。本例先要求默认目标端口非零，即使某次输入带端口也要保证配置策略完整；这是一项业务约束，不是 netip 的要求。对配置错误返回普通 error，不以 panic 代替输入处理。

把IPv6、空端口和越界值放进回归表

# 将程序保存为 main.go 后运行；本文没有实际执行。
go run main.go

以下是按函数契约推导的预期，不是复制的 stdout。读者运行时应核对成功值、default 标志和错误分类，不要依赖具体错误文本长期不变。

特别留意 2001:db8::40:9443：它自身是合法的裸 IPv6 地址。本例会把最后的 9443 当作地址的一部分，再补默认端口；不能猜测用户是否原本想表达端口。如果这种歧义在产品中不可接受，应把 IP 与端口拆成两个字段，或要求所有目标都使用标准的显式端点形式。

上线前保留端口来源与拒绝规则

迁移配置时先保存原始输入和规范化端点的对应关系，确认默认端口来自明确配置。不要用字符串直接追加冒号与端口，AddrPortFrom 配合 String 能正确表达 IPv6 端点。也不要在解析失败后返回零值 AddrPort 却丢掉 error，否则错误可能在网络连接阶段才暴露。

本例不自动 TrimSpace，不接受 URL、CIDR 或服务名端口。若产品需要允许前后空格，应在入口显式规定并单独处理，不以“尽可能猜对”为原则无限扩展解析格式。AddrPort 解析成功也不等于目标可访问、可授权或适合连接；地址范围、区域标识与网络访问策略属于后续独立职责。

常见追问

IsValid 为 true，为什么端口还能是 0？

AddrPort.IsValid 检查地址有效性，端口包含零在内均可作为其值。需要非零目标端口时，必须单独检查 Port。

缺端口能否直接改用 MustParseAddrPort？

不能。MustParse 只会在错误时 panic，不会替你补业务默认值；外部配置应使用带 error 的解析函数。

域名与端口能用同一个方法处理吗？

ParseAddrPort 不进行名称解析。如果配置允许域名，应设计单独的主机名与端口处理路径，而不是在失败后把域名当 IP 构造 AddrPort。

解析实现可参阅 https://go.dev/src/net/netip/netip.go。迁移的核心是明确接受哪些输入，并让所有被拒绝的情况继续可见，而不是改变标题中的缺端口错误字符串。