Go strings.Builder Cap 怎样预估缓冲区容量减少扩容

在 Go 里用 strings.Builder 拼接一段已知结构的文本时，真正需要估算的是“还要写入多少字节”。Len() 是已经写入的字节数，Cap() 是底层缓冲区总容量；调用 Grow(n) 后，Builder 至少能再写入 n 个字节而不触发新的分配。

容量规划的核心是：先算出预计的最终字节数，再用“最终字节数减去当前 Len”作为 Grow 的参数；Grow 传入的是剩余空间，不是最终总长度。

本文只讨论 strings.Builder 的容量估算和复用边界，不把它延伸成所有字符串拼接场景的性能结论。

先看懂 Len、Cap 与 Grow 的关系

Builder 底层保存的是字节缓冲区，所以 Cap() 也按字节计数。已经写入的内容同时占据了 Len() 个字节；可继续写入的空间可以用 Cap() - Len() 粗略表示。

package main

import (
    "fmt"
    "strings"
)

func main() {
    var b strings.Builder
    b.WriteString("name=") // 先写入固定前缀，Len 和 Cap 都按字节计算

    fmt.Println(b.Len(), b.Cap()) // Cap 是总容量，不是剩余容量
    b.Grow(len("alice"))          // 这里只预留还要追加的字节数
    b.WriteString("alice")        // 写入后 Len 增加，Cap 不一定增加

    fmt.Println(b.String()) // 结果是 name=alice
}

官方文档对 Grow(n) 的承诺是“至少还能写入 n 个字节而不再分配”；它不是把容量精确设置成某个数。运行时可能一次申请比请求更多的容量，因此不能把 Cap() 当成精确的内存布局接口。

按最终文本长度预估 Grow 参数

如果模板结构固定，可以先估算最终结果的字节长度，再减去当前长度。对 ASCII 文本，len(s) 与字符数相同；中文、表情等 UTF-8 内容则应使用 len(s) 得到实际字节数，而不是凭字符个数估算。

func buildGreeting(name, city string) string {
    var b strings.Builder
    prefix := "你好，"
    middle := "，欢迎来到"
    suffix := "！"

    // 先用最终字符串的字节长度估算，避免把中文字符数误当成字节数。
    finalBytes := len(prefix) + len(name) + len(middle) + len(city) + len(suffix)
    b.Grow(finalBytes)

    // 这些写入的总字节数正好对应上面的容量估算。
    b.WriteString(prefix)
    b.WriteString(name)
    b.WriteString(middle)
    b.WriteString(city)
    b.WriteString(suffix)
    return b.String()
}

如果 Builder 已经写入了前缀，等价写法是先读取 b.Len()，再只为“剩余部分”调用 Grow(finalBytes - b.Len())。把最终总长度直接传给 Grow 通常不会导致结果错误，但会把预留目标放大，失去容量规划的意义。

什么时候值得预留，什么时候不要硬算

当输出由多段已知模板和少量动态字段组成时，预留通常容易维护；如果输出内容来自不确定长度的循环、用户输入或多层格式化，硬算所有长度反而会让代码复杂。此时可以先写入，再根据稳定的性能证据决定是否增加估算。

需要注意，WriteString、Write 和 WriteByte 都会让 Builder 的长度变化；WriteRune 写入的是该 Unicode 码点的 UTF-8 编码，返回的数量也是写入的字节数。容量预算应按字节相加，不应按“可见字符数”相加。

复用 Builder 时的两个边界

第一，非零 Builder 不应被复制。它内部可能持有对缓冲区的引用，复制后继续写入会破坏预期；如果需要重新开始，应调用 Reset()，但 Reset 后原来的字符串值仍然应被视为独立结果，不要把 Builder 当成可并发共享对象。

第二，Grow 接受负数会触发 panic。容量估算来自外部长度时，要先保证“预计最终字节数不小于当前 Len”，再计算差值。

func reserveRemaining(b *strings.Builder, finalBytes int) {
    // 负数预算说明估算值落后于已写入内容，不能直接交给 Grow。
    remaining := finalBytes - b.Len()
    if remaining > 0 {
        b.Grow(remaining) // 只为尚未写入的字节预留空间
    }
}

可以把判断归纳为：固定模板、长度可估算时预留；长度不确定时保持简单；无论哪种方式，都把 Len、Cap 和实际字节长度的含义分清。

常见问题

Cap 越大，字符串一定越快吗？ 不一定。它只说明底层缓冲区容量更大，过度预留会增加内存占用；应针对稳定的构建路径再做测量。

中文字符串要按几个字符调用 Grow？ 不要按字符数估算，按 len(s) 得到 UTF-8 字节数；Builder 的容量和写入接口都是字节语义。

Grow 后 Cap 必须等于 Len 加参数吗？ 不需要。Grow 只保证至少有足够空间，具体扩容策略属于实现细节，调用方只应依赖它的保证。