Go strings.Builder Grow 之后如何避免误判：容量、拷贝与 String 快照

线上拼接一段带前缀的日志或 JSON 时，strings.Builder 经常被当成“预先分配好最终长度”的字符串容器。实际情况更细：Grow(n) 只承诺后面还能写入至少 n 个字节，Cap() 看到的是底层总容量，String() 得到的是当前已经写入的内容。把这三个量混在一起，性能判断和边界测试都会跑偏。

记住一条就够了：Grow 看“还要写多少”，Cap 看“总共占了多少”，String 看“目前已经写了什么”；非零 Builder 只能通过指针继续使用，不能复制。

Grow 预留的是剩余容量，不是最终长度

官方文档对 Grow(n) 的保证是“再写入 n 个字节时不发生新的分配”。因此，假设当前已经写入 7 个字节，要再写入 20 个字节，应该调用 b.Grow(20)，而不是把 27 当成参数。后者通常不会导致错误，但会把容量需求夸大，尤其是在循环中反复估算时。

package main

import (
    "fmt"
    "strings"
)

func main() {
    var b strings.Builder
    b.WriteString("prefix:")
    b.Grow(20)
    fmt.Println("Len before:", b.Len())
    fmt.Println("Cap after Grow:", b.Cap())
    b.WriteString("request-id=42")
    fmt.Println(b.String())
}

这段程序里，Len() 只随实际写入增长，Cap() 则包含已经写入的 7 个字节和 Grow 预留的空间。写入 request-id=42 后，String() 只返回已写入的完整文本，不能拿 Cap() 去推断字符串长度。

为什么 Cap 变大不代表 String 已经变长

Builder 内部维护的是一段字节缓冲区。Grow 只在剩余容量不足时扩容，容量计算会把已经使用的部分一起算进去；而 String() 按当前长度返回结果。这个差异很适合用在测试里：验证写入结果用 String()，验证是否提前留出空间才看 Cap()。

别把“容量足够”写成业务断言。例如日志字段后来增加了 Unicode 文本时，字节数和字符数并不相同；Grow 的单位是字节。若预估来自字符数，至少要按 UTF-8 字节长度校正，或者只把 Grow 当作减少扩容的提示，而不是硬性容量协议。

String 之后仍要守住 Builder 的生命周期

String() 取的是当前累计内容。拿到结果后继续对同一个 Builder 写入，后续调用会看到更新后的内容；但这不意味着可以把 Builder 本身复制给另一个变量。源码明确要求不要复制非零 Builder，内部的 copyCheck 会记录接收者地址，用来发现这种误用。

var b strings.Builder
b.WriteString("header")
snapshot := b.String()
b.WriteString("-body")

fmt.Println(snapshot) // header
fmt.Println(b.String()) // header-body

// 不要这样做：var other = b

这里的两个输出能说明快照边界：snapshot 是调用 String() 时的内容，后一次 String() 才包含追加的正文。真正需要清空并复用时调用 Reset()，而不是复制一个 Builder 保存“旧状态”。

一套不容易误判的验收方式

先测内容，再测容量

单元测试先断言 b.String()、b.Len() 与预期文本一致，再单独检查 b.Cap() - b.Len() 是否满足下一段写入的预估。不要断言某个具体容量数字，因为扩容策略属于实现细节，未来版本可能改变。

把负数和复制当成边界用例

Grow(-1) 按文档会触发 panic；非零 Builder 的复制也属于错误用法。正常业务代码不应依赖 panic 做流程控制，但可以在测试中确认错误确实被发现，这比把它悄悄传入 goroutine 更容易定位。

复用时清楚地区分 Reset 和重新声明

短生命周期函数里直接声明零值 Builder 最简单；需要复用时，用指针持有同一个 Builder 并在下一轮开始调用 Reset()。如果对象要跨边界传递，传递 String() 的结果通常比传 Builder 更容易维护。

常见问题

Grow 会让 String 立即包含空白内容吗？

不会。Grow 只扩大可写空间，String 仍然只返回已写入的字节。

可以把 Builder 放进结构体后按值返回吗？

非零 Builder 不应按值复制。让结构体持有指针，或在边界处返回已经生成的 string。

小结

把 Grow 当成“下一段写入的预算”，把 Cap 当成底层空间观察值，把 String 当成内容快照，代码里的判断就不会互相串位。需要复用时坚持 Reset，需要跨边界传递时交付字符串；这两条比追着某个具体扩容数字做优化更稳。