Go net/url URL.AppendBinary 怎样复用缓冲区构造 URL 文本

需要把一个 url.URL 写进已有的字节缓冲区时，可以调用 URL.AppendBinary。它的关键不是“返回一个固定的新数组”，而是把 URL 文本追加到传入的 []byte，再返回追加后的切片：返回值必须接住，底层容量不足时也要允许它指向新的数组。

确认 AppendBinary 的输入输出与版本边界

URL.AppendBinary(b) 适合“我已经有一段 []byte，还要把 URL 接在后面”的场景。它返回追加完成后的切片和一个错误值；当前 Go 标准库源码中的实现会把 u.String() 的结果追加到 b，因此它解决的是统一的字节追加接口和缓冲区衔接问题，不等于完全跳过 URL 文本构造。

这个方法在 Go 1.24 加入。如果项目仍要兼容更早的 Go 版本，不能直接编译这段调用，应继续使用 u.String() 或自行保留兼容分支。官方接口说明见 https://pkg.go.dev/net/url#URL.AppendBinary。

把 URL 追加到已有缓冲区

典型用法是先写入协议前缀，再把 URL 接在后面。示例中的 buf 可能复用原数组，也可能在容量不够时获得新数组，所以不要只检查原变量的底层地址。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    u, err := url.Parse("https://example.com/search?q=go")
    if err != nil {
        // 解析失败时直接停止，避免把不完整地址写入协议数据。
        panic(err)
    }

    buf := []byte("target=")
    // 追加可能触发扩容，必须用返回值覆盖 buf。
    buf, err = u.AppendBinary(buf)
    if err != nil {
        // 保留错误分支，调用方可以在生产环境改为返回或记录错误。
        panic(err)
    }

    fmt.Println(string(buf))
}

结果是 target=https://example.com/search?q=go。这里的 string(buf) 只是为了展示或交给字符串接口；如果下游本来接受 []byte，可以继续传递 buf，少做一次显式转换。

处理返回值与错误并避免切片别名误用

调用方最容易犯的错误有两个：忽略返回切片，或者把返回切片保存起来后又继续复用同一底层数组。第一种会丢掉追加结果；第二种会让后续写入覆盖已经保存的内容。

func appendURL(prefix []byte, u *url.URL) ([]byte, error) {
    // 让 AppendBinary 决定是否复用 prefix 的容量，调用方只使用返回切片。
    result, err := u.AppendBinary(prefix)
    if err != nil {
        return nil, fmt.Errorf("追加 URL 文本: %w", err)
    }
    return result, nil
}

func snapshot(data []byte) []byte {
    // 长期保存或跨 goroutine 传递前复制，避免后续 append 改写共享数组。
    return append([]byte(nil), data...)
}

上面的辅助函数需要额外导入 fmt。如果数据只在当前调用栈内立即写入网络或日志，可以直接使用返回切片；如果要放进队列、缓存或异步任务，应该先复制。另一个边界是：当前实现通常不会返回非空错误，但接口保留了 error，调用方仍应保留错误处理，不要依赖“现在一定为 nil”的实现细节。

选择 AppendBinary、String 与 MarshalBinary

三个 API 的核心差异在于下游需要什么类型。String 最直观，适合模板、日志和参数函数；AppendBinary 适合已有字节缓冲区；MarshalBinary 没有传入缓冲区，适合实现 encoding.BinaryMarshaler 的通用序列化调用。标准库源码中，MarshalBinary 直接调用 AppendBinary(nil)，两者的 URL 文本编码路径一致。

常见问题

AppendBinary 会保证复用传入切片吗？

不会。它会尝试把内容追加到传入切片，但容量不足时可能扩容并返回新切片。调用方只应使用返回值，不要假设底层数组一定不变。

AppendBinary 能避免所有 URL 字符串分配吗？

不能这样保证。当前标准库实现先调用 u.String() 再追加，因此它更适合统一追加接口和已有缓冲区的写法，而不是承诺零分配。

什么时候应该复制返回的字节切片？

当结果要跨越当前函数、进入异步队列或后续还会复用同一缓冲区时复制；只在当前调用中立即消费则可以直接传递。