Go netip.Addr.StringExpanded 怎样固定 IPv6 展开格式

如果下游要求 IPv6 始终写成完整的八组十六进制形式，可以直接使用 netip.Addr.StringExpanded()。它只改变 IPv6 的文本展示：把 :: 压缩省略的部分补回去，并保留前导零；IPv4 仍然使用点分十进制，零值地址也不会因此变成有效地址。

我更建议把这个方法放在“输出边界”使用，而不是把它当成解析或校验方法。先用 netip.ParseAddr 判断输入是否是合法地址，再按地址族决定展示形式，日志、缓存键和对接固定格式协议时会更容易保持一致。

StringExpanded 解决的是什么问题

IPv6 常见的压缩写法会把连续的零组替换成双冒号，例如 2001:db8::1。这种写法适合人阅读，但同一地址可能出现多种等价文本。若日志检索、固定宽度报表或外部协议希望每组都明确出现，就可以使用展开格式：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    addr := netip.MustParseAddr("2001:db8::1")

    // String 适合紧凑展示；StringExpanded 保留 IPv6 的八组结构。
    fmt.Println(addr.String())
    fmt.Println(addr.StringExpanded())
}

上面的两个输出都指向同一个地址，但第二行会补齐 IPv6 的省略部分。这里使用 MustParseAddr 只是为了表达一个写死且已知正确的示例；服务端接收用户输入时不要用它替代错误处理。

先解析，再决定是否展开

实际项目通常拿到的是配置文件、请求参数或日志字段。正确的顺序是先解析，再格式化。解析失败时保留错误信息，避免把原字符串误当成一个可比较的地址：

package main

import (
    "fmt"
    "net/netip"
)

func formatAddress(input string) (string, error) {
    addr, err := netip.ParseAddr(input)
    if err != nil {
        // 解析失败直接返回错误，不让非法文本进入地址键或日志规范化流程。
        return "", fmt.Errorf("parse IP address %q: %w", input, err)
    }

    // 只有 IPv6 需要展开；IPv4 用常规点分十进制即可。
    if addr.Is6() {
        return addr.StringExpanded(), nil
    }
    return addr.String(), nil
}

func main() {
    for _, input := range []string{"2001:db8::1", "192.0.2.10", "not-an-ip"} {
        value, err := formatAddress(input)
        if err != nil {
            fmt.Println("error:", err)
            continue
        }
        fmt.Println(value)
    }
}

这里的判断不是必须的：直接对 IPv4 调用 StringExpanded 也不会把它改写成 IPv6。显式判断的价值在于让代码意图更清楚，也方便未来给 IPv4 和 IPv6 接入不同的序列化规则。

四类输入的结果边界

理解边界比记住方法名更重要。StringExpanded 是展示方法，它不负责判断字符串是否合法，也不负责把不同地址族转换成同一种地址。

特别要留意 IPv4 映射 IPv6。netip 会保留地址族语义，映射地址和普通 IPv4 并不是同一个类型判断结果。若业务需要统一它们，应先明确是否要调用 Unmap，再决定输出；不要仅因为两种文本看起来相似就直接合并。

package main

import (
    "fmt"
    "net/netip"
)

func describe(input string) {
    addr, err := netip.ParseAddr(input)
    if err != nil {
        // 失败分支只记录解析错误，避免继续读取无效地址的属性。
        fmt.Printf("%q -> invalid: %v\n", input, err)
        return
    }

    // 同时输出地址族和文本，便于排查 IPv4、IPv6 与映射地址的差异。
    fmt.Printf("%q -> is4=%v is6=%v expanded=%s\n", input, addr.Is4(), addr.Is6(), addr.StringExpanded())
}

func main() {
    describe("2001:db8::1")
    describe("192.0.2.10")
    describe("::ffff:192.0.2.10")
    describe("not-an-ip")
}

把展开格式放到日志和序列化边界

格式化最适合发生在“值已经确定、即将离开程序”的位置。例如日志字段、审计事件或需要稳定文本的 JSON DTO。业务内部仍可以保留 netip.Addr 值，避免过早转换成字符串后丢失地址族和有效性信息。

package main

import (
    "encoding/json"
    "net/netip"
)

type AddressEvent struct {
    // Address 保存固定格式文本，方便下游日志和序列化读取。
    Address string `json:"address"`
}

func newEvent(input string) (AddressEvent, error) {
    addr, err := netip.ParseAddr(input)
    if err != nil {
        // 让调用方决定如何返回 400、丢弃事件或记录告警。
        return AddressEvent{}, err
    }

    // 输出边界统一使用展开形式，内部仍以 netip.Addr 完成判断。
    return AddressEvent{Address: addr.StringExpanded()}, nil
}

func main() {
    event, _ := newEvent("2001:db8::1")
    payload, _ := json.Marshal(event)
    println(string(payload))
}

示例中的错误被忽略只是为了压缩演示入口，生产代码应检查 newEvent 和 json.Marshal 的返回值。更重要的是，不要把 StringExpanded 当作“规范化一切”的开关：它解决的是 IPv6 展开显示，不会替你决定大小写策略、IPv4 映射策略或业务字段是否允许空值。

什么时候值得使用

如果下游只面向人阅读，String() 的紧凑形式通常更短、更友好；如果下游需要稳定的 IPv6 八组文本，StringExpanded() 更合适。常见判断可以归纳为：

• 日志检索需要同一地址尽量只有一种 IPv6 文本形态时，使用展开格式。
• 对接固定字段宽度、教学示例或网络排障报表时，使用展开格式更直观。
• 地址要参与业务比较或作为 map 键时，优先保存 netip.Addr，不要只比较字符串。
• 输入来自用户或网络时，先 ParseAddr，再按地址族和下游契约格式化。

落地清单

1. 把 netip.ParseAddr 放在外部输入边界，并处理返回的错误。
2. 确认下游要的是紧凑 IPv6，还是不省略零组的完整 IPv6。
3. 只在输出边界调用 StringExpanded，内部保留地址值。
4. 明确 IPv4 映射 IPv6 是否需要先 Unmap，不要隐式合并地址族。
5. 为零值和非法文本准备独立错误路径，不把展示格式当作校验结果。

常见问题

StringExpanded 会把 IPv4 转成 IPv6 吗？

不会。它主要改变 IPv6 的展示形式，IPv4 仍按 IPv4 文本表示。是否把 IPv4 映射地址统一为普通 IPv4，需要业务显式决定。

已经是完整 IPv6 形式，还需要调用吗？

可以调用。方法是幂等的展示操作，适合在输出边界统一使用；但它不会替代输入解析和地址有效性判断。

为什么不直接比较两个 IPv6 字符串？

不同写法可能表示同一个地址。需要判断地址相等时，应先解析为 netip.Addr 再比较值；字符串格式化只服务于展示、日志和序列化契约。

零值 Addr 调用 StringExpanded 安全吗？

调用本身不会补出一个有效 IP。零值应被视为无效或未初始化状态，在进入业务输出前单独处理。

一句话总结：先解析成 netip.Addr，再把 StringExpanded 放在需要固定 IPv6 文本的输出边界；不要让展示格式承担校验、地址族转换和业务判定。