Go fmt.Appendf 追加格式化结果的低分配写法

我第一次认真用 fmt.Appendf，是在组装一批日志行时发现代码反复执行 append(dst, fmt.Sprintf(... )...)。这类写法先得到一个字符串，再把字符串内容追加到字节切片；如果目标本来就是 []byte，可以直接用 fmt.Appendf 把格式化结果写到现有切片末尾，并接住它返回的更新切片。

官方文档：https://pkg.go.dev/fmt#Appendf

先找到 Sprintf 再 append 的中间结果

我原来的代码可读性没有问题，但目标容器已经是字节切片，Sprintf 返回的字符串只是过渡值。格式化发生一次，字符串再复制到 dst，这正是 fmt.Appendf 想缩短的路径。

func appendRecordOld(dst []byte, id int, name string) []byte {
	// 旧写法先构造字符串，再把字符串内容复制进目标切片。
	line := fmt.Sprintf("id=%d name=%q", id, name)
	return append(dst, line...)
}

官方对 Appendf 的定义很直接：按格式说明符完成格式化，把结果追加到字节切片，并返回更新后的切片。它使用的格式化规则与 Printf、Sprintf 同属一套 fmt 规则，因此迁移时通常不必重写格式字符串。

用 Appendf 直接追加并接住返回切片

替换后的最小写法只有一处容易踩坑：一定要接住返回值。和内置 append 一样，原切片容量不足时，追加操作可能换到底层新数组；如果忽略返回值，调用方仍然持有旧的长度和底层数组视图。

func appendRecord(dst []byte, id int, name string) []byte {
	// Appendf 可能扩容，因此必须返回并使用更新后的切片。
	dst = fmt.Appendf(dst, "id=%d name=%q", id, name)
	dst = append(dst, '\n') // 固定字节继续用内置 append 即可。
	return dst
}

func buildBatch() []byte {
	// 长度从 0 开始，容量为后续追加预留空间。
	dst := make([]byte, 0, 256)
	dst = appendRecord(dst, 17, "alice")
	dst = appendRecord(dst, 23, "bob")
	return dst
}

fmt.Append、fmt.Appendln 和 fmt.Appendf 都在 Go 1.19 加入标准库。项目若还要支持更旧的 Go 版本，就只能继续使用 Sprintf、Fprintf 或自己组合 strconv.Append*；不能仅修改源码而不调整最低工具链要求。

预留容量，但不要把估算写成魔法数字

Appendf 能省掉中间字符串，并不意味着目标切片永远不分配。切片剩余容量不足时仍然要增长底层数组。我比较喜欢从稳定前缀、字段数量和常见值长度估一个保守容量，把它留在调用层，而不是在每个小函数里偷偷创建新缓冲区。

func buildAccessLine(path string, status int, micros int64) []byte {
	// 96 是本业务常见行长度的保守估计，应由真实样本调整。
	dst := make([]byte, 0, 96)
	dst = append(dst, "path="...)
	dst = fmt.Appendf(dst, "%q status=%d cost_us=%d", path, status, micros)
	return dst
}

容量设得太小，热点循环里仍可能反复扩容；设得过大，则每条短记录都保留了无用空间。更稳妥的做法是从实际长度分布出发，选择能覆盖大多数记录的值，并给异常长字段设置独立上限。cap(dst)-len(dst) 能告诉你当前还剩多少空间，但它适合诊断，不必写进每次追加的业务分支。

把追加逻辑封装在同一个切片所有权里

真正让我觉得 Appendf 顺手的地方，不是少写一行，而是它让“谁持有缓冲区、谁继续追加”变得清楚。调用方创建切片并决定是否复用，辅助函数只接受 dst、追加字段、返回更新值，不在内部把切片转换成字符串。

type Event struct {
	Kind string
	Code int
}

func (e Event) AppendText(dst []byte) []byte {
	// 方法只追加自己的字段，不保存外部切片引用。
	dst = append(dst, "event="...)
	dst = fmt.Appendf(dst, "%q code=%d", e.Kind, e.Code)
	return dst
}

func encodeEvents(events []Event) []byte {
	// 调用层统一持有并更新缓冲区，生命周期更容易判断。
	dst := make([]byte, 0, len(events)*48)
	for _, event := range events {
		dst = event.AppendText(dst)
		dst = append(dst, '\n')
	}
	return dst
}

这种接口也有边界：返回的 []byte 仍由调用方拥有，辅助函数不应把它长期保存到结构体或异步任务中。若切片来自对象池，归还池之前必须保证所有消费者已经结束；否则降低分配的尝试会变成数据竞争或内容被覆盖。

固定类型优先考虑 strconv.Append 系列

fmt.Appendf 的优势是保留完整的格式化能力，但这种通用性也有成本。字段只包含整数、布尔值或浮点数时，strconv.AppendInt、AppendBool、AppendFloat 往往更直接；目标若是一个 io.Writer，则 fmt.Fprintf 比先积累完整切片更自然。

func appendCounter(dst []byte, name string, value int64) []byte {
	// 固定文本和字符串直接追加，整数交给类型化转换函数。
	dst = append(dst, name...)
	dst = append(dst, '=')
	dst = strconv.AppendInt(dst, value, 10)
	return dst
}

用基准测试确认“低分配”是否成立

我不会仅凭 API 名称判断优化成功。格式参数是否装箱、目标容量是否足够、被格式化类型是否实现 String 或 Formatter，都会影响结果。把旧写法和新写法放进同一个基准文件，用真实字段和接近生产的初始容量比较，才知道迁移是否值得。

var sink []byte

func BenchmarkAppendf(b *testing.B) {
	for i := 0; i 

# 查看每次操作的耗时和内存分配；这里不预设结果。
go test -run '^$' -bench 'Benchmark(Appendf|SprintfAppend)$' -benchmem

如果这段格式化不在热点路径，Sprintf 的清晰程度可能更重要；如果调用频率高、目标本来就是 []byte，并且基准显示分配确实下降，Appendf 才是有证据的改进。对我来说，这个条件比“看到 Append 就全量替换”更可靠。

相关问题

fmt.Appendf 会保证零分配吗？

不会。目标切片可能扩容，参数格式化过程也可能产生分配。它主要避免了显式的 Sprintf 中间字符串，最终效果要看具体参数和基准测试。

为什么必须写 dst = fmt.Appendf(dst, ... )？

因为追加时可能更换底层数组，而且新长度只体现在返回切片中。忽略返回值与忽略内置 append 的返回值是同类错误。

Go 1.18 项目能用 fmt.Appendf 吗？

不能直接使用。该函数在 Go 1.19 加入标准库；需要升级最低工具链，或保留兼容旧版本的实现。