Go url.URL.AppendBinary 怎样把 URL 追加到已有缓冲区

如果目标是把一个已经解析好的 URL 编码结果接到已有的 []byte 后面，直接使用 u.AppendBinary(buf)，并把返回值重新赋给缓冲区变量。这个方法不会把结果单独返回成新的字符串，而是返回“追加完成后的切片”和一个错误值。

官方地址：https://pkg.go.dev/net/url#URL.AppendBinary

AppendBinary 从 Go 1.24.0 起提供。最容易写错的地方有两个：忽略返回的切片，或者把它当成会覆盖原缓冲区的格式化函数。它的核心语义是追加，不是清空。

已有缓冲区怎样接收 URL

先把角色分开：url.URL 是结构化对象，[]byte 是承载编码结果的缓冲区，AppendBinary 负责把 URL 的编码表示追加到后者。下面的 buf 是输入和输出共用的切片值。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 先解析 URL；解析失败时，不继续调用 AppendBinary。
	u, err := url.Parse("https://example.com/search?q=go%20url")
	if err != nil {
		fmt.Println("parse URL:", err)
		return
	}

	// 前缀可以来自协议头、日志字段或待写出的其他字节。
	buf := []byte("target=")

	// 必须接住返回的切片；它可能复用底层数组，也可能扩容。
	buf, err = u.AppendBinary(buf)
	if err != nil {
		fmt.Println("append URL:", err)
		return
	}

	fmt.Println(string(buf))
}

关键不是 buf 是否一定扩容，而是调用者只使用返回值。切片包含指针、长度和容量三个描述字段；追加后长度可能已经变化。继续使用旧变量，就可能只看到原来的前缀。

AppendBinary 与 String、MarshalBinary 有什么区别

String() 返回字符串，适合展示或字符串接口；MarshalBinary() 返回一份独立字节结果；AppendBinary(b) 允许调用方提供已有的字节前缀。三者表达的是同一个 URL 的编码形态，但承载结果的方式不同。

如果调用方已经有必须保留的前缀，AppendBinary 的意图最清晰；如果只想得到一个独立结果，MarshalBinary 更直观。

重复追加时为什么会出现两个 URL

AppendBinary 的语义是追加，不是清空。一次调用后再次把同一个返回切片传进去，第二个 URL 会接在第一个 URL 后面。构造连续记录时这可能是有意行为；如果业务要的是刷新当前值，就要先重新建立目标切片或重置长度。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 这个 URL 只解析一次，演示同一缓冲区上的两次追加。
	u, err := url.Parse("https://example.com/item")
	if err != nil {
		fmt.Println("parse URL:", err)
		return
	}

	buf := []byte("first=")
	// 追加后继续沿用返回切片，保留第一次结果。
	buf, err = u.AppendBinary(buf)
	if err != nil {
		fmt.Println("first append:", err)
		return
	}

	buf = append(buf, '|')
	// 第二次调用会继续追加；分隔符由调用方负责。
	buf, err = u.AppendBinary(buf)
	if err != nil {
		fmt.Println("second append:", err)
		return
	}

	fmt.Println(string(buf))
}

输出布局的责任在调用方：是否添加分隔符、是否预留容量、是否在每条记录之间重置长度，都不由 URL 方法替你决定。可以使用 buf = buf[:0] 清空逻辑长度并保留容量，也可以重新创建切片。

解析错误和追加错误要分别处理

url.Parse 的错误发生在字符串转换为 *url.URL 之前，AppendBinary 的错误发生在结构化 URL 被编码时。两个错误属于不同阶段，不要用一个布尔标记把它们混在一起。

func encodeWithPrefix(raw string, prefix []byte) ([]byte, error) {
	// 解析错误说明输入字符串还没有形成可用的 URL 对象。
	u, err := url.Parse(raw)
	if err != nil {
		return nil, fmt.Errorf("parse URL: %w", err)
	}

	// 返回值同时承载追加后的切片和编码阶段的错误。
	buf, err := u.AppendBinary(prefix)
	if err != nil {
		return nil, fmt.Errorf("append URL: %w", err)
	}
	return buf, nil
}

示例函数需要导入 fmt 和 net/url；这里把阶段信息包进错误，只是为了让上层日志更容易定位。对外部输入尤其要避免把包含用户名或密码的 URL 直接打印到日志，必要时先使用脱敏表示。

版本和内存复用边界

AppendBinary 是 Go 1.24.0 起的 API。如果项目需要支持更早版本，不能只把调用替换进旧的构建环境；可以继续使用 String 或 MarshalBinary，或者用版本条件组织代码。

可以通过 make([]byte, 0, n) 预留容量，但不能据此断言一定没有分配。容量不足时会返回指向新底层数组的切片；容量足够时也只是有机会复用。正确做法仍然是始终使用返回切片，把容量预估当作优化手段而不是语义保证。

常见问题

AppendBinary 会修改 URL 对象吗？

它的重点是把编码结果写入目标字节切片。调用后应把返回的切片当成新状态，不能把旧缓冲区变量继续当作追加完成后的结果。

已有缓冲区中的前缀会被覆盖吗？

正常使用时，前缀保留在返回切片的前面；如果不希望保留旧内容，应在调用前重置长度或创建新的目标切片。

为什么还需要检查 error？

方法签名明确返回 ([]byte, error)。编码失败时，不应把返回的字节结果当成可发送的完整 URL。

什么时候选 MarshalBinary？

只需要一个独立完整字节结果时，MarshalBinary 更直接；需要复用目标缓冲区时再选 AppendBinary。

记住一句话：AppendBinary 的核心是“把 URL 编码结果追加到切片，并使用返回切片继续工作”。先处理解析错误，再处理追加错误；需要覆盖时重置缓冲区，需要串联时保留返回值。