Go fmt.Appendf 如何复用字节缓冲区：格式化追加、容量增长与错误处理

日志拼接或协议编码里，经常会先拿到一段已有的字节，再把编号、状态和时间追加进去。此时如果先用 fmt.Sprintf 得到字符串，再转成 []byte，代码虽然直白，却多了一次中间结果。fmt.Appendf 的边界更适合这种场景：它接收目标切片，按格式说明符追加内容，并返回新的切片。

fmt.Appendf 解决的是哪一段数据路径

它的调用链很短：已有 []byte 作为输入，格式串和参数进入 fmt.Appendf，返回值成为下一轮追加的输入。这个函数没有单独的 error 返回值，所以“格式是否符合预期”要由调用方通过结果内容或长度检查确认。

先跑一个最小追加示例

示例刻意保留容量不足和容量充足两种情况。第一轮从 cap=8 的切片开始，追加后的内容超过预留空间；第二轮预留更大的容量，便于观察长度增长而不是把容量增长误认为业务结果。

package main

import (
    "fmt"
)

func main() {
    small := make([]byte, 0, 8)
    small = append(small, "id="...)
    beforeCap := cap(small)
    small = fmt.Appendf(small, "%d status=%s", 42, "ready")
    fmt.Printf("small beforeCap=%d len=%d cap=%d text=%q\n", beforeCap, len(small), cap(small), small)

    roomy := make([]byte, 0, 32)
    roomy = fmt.Appendf(roomy, "id=%d status=%s", 42, "ready")
    fmt.Printf("roomy len=%d cap=%d text=%q\n", len(roomy), cap(roomy), roomy)

    bad := fmt.Appendf(nil, "count=%d", "not-an-int")
    fmt.Printf("mismatch len=%d text=%q\n", len(bad), bad)
}

运行结果里，small 的 text 包含完整的 id=42 status=ready，说明追加没有覆盖已有前缀。roomy 则在更大的初始容量上完成同样的格式化，长度相同，但容量策略不同。

为什么一定要接住返回值

fmt.Appendf 遵循切片追加的返回语义：当容量不够时，函数可能返回指向新数组的切片。只调用而不赋值，后续代码仍拿着旧切片，既看不到追加内容，也无法利用新的底层存储。

buf := make([]byte, 0, 4)
buf = append(buf, "前缀"...)
buf = fmt.Appendf(buf, "-%d", 7)
if string(buf) != "前缀-7" {
    panic("unexpected append result")
}
fmt.Printf("checked len=%d text=%q\n", len(buf), buf)

这里的判断比比较 cap 更有价值：业务真正关心的是字段内容是否完整。容量可以用于性能观察，但不能作为协议正确性的依据。

格式错误没有 error，怎么验收

与 fmt.Fprintf 不同，Appendf 的签名只返回 []byte。如果把字符串传给 %d，结果会出现带有 %!d(string=...) 的诊断片段。它不是静默成功，正因为它已经进入字节结果，所以固定格式协议不能只检查长度。

如果输出要进入日志，诊断片段通常已经足够暴露问题；如果输出要进入二进制协议，建议把字段值先用明确的 strconv.AppendInt 等函数编码，再对长度、字符集和边界做断言。

常见问题

fmt.Appendf 会修改原来的底层数组吗？

容量足够时通常会复用已有数组；容量不足时可能分配新数组。调用方只应依赖返回后的切片，不应依赖底层数组地址。

fmt.Appendf 和 fmt.Sprintf 怎么选？

已有字节缓冲区并且要继续追加时优先考虑 Appendf；需要一个独立字符串、或格式结果要直接作为字符串传递时，Sprintf 更直观。

格式错误为什么没有返回 error？

这是 fmt.Appendf 的 API 设计：它返回更新后的字节切片。参数类型检查要靠测试、静态检查和对结果内容的验收完成。

把检查点留在代码旁边

最小写法是“追加—接回返回值—检查结果”。性能敏感的路径可以预留合理容量，减少增长次数；正确性敏感的路径仍要断言最终文本，特别是格式串来自配置或字段较多的代码。这样既利用了字节切片的追加路径，也不会把容量变化误当成格式化成功。