Go strings.Builder 拼接文本的容量规划

我在拼接日志行、导出文本时，最容易犯的错误不是把 strings.Builder 写错，而是把容量优化当成“固定调用 Grow”。更稳妥的做法是：先估算最终文本的字节数，只有预算相对可靠时才预留；写完后把 String() 当成读取边界；已经写入过内容的 Builder 则只通过指针传递，不能复制。

容量规划的目标是减少不必要的扩容和内存复制，不是把容量一次性猜到最大。小文本直接写，大文本按字节预算调用 Grow，结果需要跨越复用边界时再显式复制字符串。

先区分三种拼接场景

如果只是拼接两三个短常量，直接调用 WriteString 往往最清楚；为了这点文本专门维护一套容量估算，反而会增加阅读成本。容量规划真正有价值的场景通常有三个：

• 输出由许多片段组成，最终长度大致可知；
• 循环写入大段文本，希望避免缓冲区反复扩容；
• 同一类输出反复生成，需要用 Len 和 Cap 观察预算是否过大。

这里的“可知”不是要求提前得到每个字符，而是能用输入字段的字节长度做出接近实际的估计。如果片段来自压缩、转义或格式化结果，长度变化很大，就不要为了一个看似精确的数字牺牲代码可读性。

按字节预算决定 Grow 的容量

Grow(n) 预留的是至少可以再写入的 n 个字节。Go 字符串按 UTF-8 保存时，一个中文字符通常占多个字节，所以不能用“字符数”直接当容量。len(s) 也返回字节数，正好适合做这类预算。

下面的函数把固定前缀和动态片段长度相加，再一次性预留。代码里的注释只标出容量和错误边界，避免把每行都解释成注释。

package report

import "strings"

func buildLine(prefix string, parts []string) string {
	// len 统计 UTF-8 字节数，正好对应 Builder 的容量单位。
	budget := len(prefix)
	for _, part := range parts {
		budget += len(part)
	}

	var b strings.Builder
	b.Grow(budget) // 预算可靠时减少后续扩容；预算过小也不会影响正确性。
	b.WriteString(prefix)
	for _, part := range parts {
		b.WriteString(part)
	}
	return b.String()
}

Grow 的安全点在于：预算不足时，Builder 仍会继续扩容；预算过大时，代价是可能多占一段容量。因此，容量估算应该服务于稳定的大输出，而不是给每个小函数都塞一个“拍脑袋”的常量。

Len 和 Cap 要一起看

Len() 表示已经累计的字节数，Cap() 表示底层缓冲区可用的总容量。两者的差值可以帮助判断预留是否合理：如果输出刚写了一小段就得到远大于预期的 Cap，说明预算偏大；如果写入后容量增长很多，说明输入长度估算偏小或输入本身波动很大。

这两个值更适合在开发阶段帮助校准策略，不应把某次运行得到的具体容量当成跨 Go 版本、跨实现都不变的契约。文章要解决的是“是否需要预算”和“预算按什么单位计算”，不是承诺某个内部增长算法。

func appendFields(fields []string) string {
	var b strings.Builder
	for i, field := range fields {
		if i > 0 {
			b.WriteByte(',') // 分隔符也要计入容量估算时的字节预算。
		}
		b.WriteString(field)
	}

	// Len 是已写入字节数，Cap 是已分配的总容量；两者都不代表字符数。
	_ = b.Len()
	_ = b.Cap()
	return b.String()
}

String 应该成为读取边界

String() 返回当前已经累计的字符串。工程上可以把它视为“写入阶段结束、读取阶段开始”的边界：调用方拿到结果后，不要再把同一个 Builder 交给多个 goroutine，也不要把 Builder 值复制到另一个变量里继续写。

官方文档明确提醒：零值 Builder 可以直接使用，但非零 Builder 不应复制。这个限制不是“性能建议”，而是 API 的使用契约。需要共享结果时，共享生成出来的字符串；需要继续构造下一份文本时，使用新的 Builder 或在明确的单线程复用点调用 Reset()。

需要复用时，把 Reset 放在明确的生命周期里

Reset() 会把 Builder 变为空状态，适合在同一个拥有者准备重新生成文本时使用。它不应该被隐藏在返回值仍被使用的并发流程中，否则读者很难判断某个字符串结果和下一轮写入之间是否存在生命周期耦合。

func renderTwice(first, second string) (string, string) {
	var b strings.Builder
	b.WriteString(first)
	left := strings.Clone(b.String()) // 明确复制，避免后续复用时绑定到同一写入边界。

	b.Reset() // 只在上一份结果已经脱离 Builder 后复用。
	b.WriteString(second)
	right := b.String()
	return left, right
}

如果 Builder 不会在返回后继续写入，直接返回 b.String() 就够了，不必无条件调用 strings.Clone。只有在结果需要跨越后续 Reset、复用或所有权转移时，显式复制才是在代码中表达真实意图。

不要复制已经使用过的 Builder

下面这种写法看起来像普通的值复制，但它把一个已经写入过的 Builder 复制成了两个对象：

func wrongCopy() string {
	var original strings.Builder
	original.WriteString("header")

	// 错误示例：非零 Builder 不应通过值复制继续使用。
	copyOfBuilder := original
	copyOfBuilder.WriteString("-body")
	return copyOfBuilder.String()
}

正确的组织方式是让一个函数或一个结构体字段拥有 Builder，通过指针传递：

func writeBody(b *strings.Builder, body string) {
	// 指针传递保持单一写入拥有者，避免复制非零 Builder。
	b.WriteString(body)
}

func render(title, body string) string {
	var b strings.Builder
	writeBody(&b, title)
	writeBody(&b, ":")
	writeBody(&b, body)
	return b.String()
}

这里的重点不是“所有 Builder 都必须放在指针里”，而是零值初始化后就应保持稳定的拥有关系。函数内部的局部 Builder 可以自然地使用；一旦它已经非零，就不要再把它当作普通结构体复制。

我的容量规划清单

官方参考可以从 https://pkg.go.dev/strings#Builder 查看 Grow、Len、Cap、Reset 和“不复制非零 Builder”的完整说明。实际项目里，先用最小实现跑通，再针对稳定的大输出校准容量，通常比提前堆叠优化更可靠。

常见疑问

Grow 的参数应该填字符数还是字节数？

填字节数。可以直接使用字符串的 len，不要用 rune 数或中文字符个数替代。

调用 String 后还能继续写 Builder 吗？

API 允许继续使用 Builder，但工程代码最好把 String 当成读取边界；如果后续会 Reset 或复用，先明确结果是否需要独立复制。

为什么不能复制已经使用过的 Builder？

官方文档明确规定非零 Builder 不应复制。用指针传递或让单一函数拥有它，能避免把内部状态复制成两个写入对象。