Go strings.Builder 怎样安全复用缓冲区

如果一个请求处理函数反复拼接短字符串，通常会想到把 strings.Builder 放进循环或对象池里复用。这里最容易误解的一点是：Reset 可以复用 Builder 对象，但不应把它当成“下一轮一定继续使用原有容量”的承诺。安全做法是每轮使用同一个实例的指针，写完后先取出字符串，再在下一轮开始前清空；如果你的核心目标是长期保留字节容量，应重新评估是否更适合 bytes.Buffer。

官方资料：https://pkg.go.dev/strings#Builder

结论：复用的是 Builder 的生命周期，不是复制它，也不是强行保留它的底层缓冲区。非零 Builder 不能复制；同一个 Builder 也不能被多个 goroutine 同时读写。

Reset 清空内容，但不要混淆容量语义

strings.Builder 的零值可以直接使用，String 返回当前累计内容，Len 返回累计字节数。调用 Reset 后，Builder 回到空状态，下一轮可以继续调用 WriteString、WriteByte 或 WriteRune。

但“对象还能继续调用”和“旧容量一定被保留”是两个问题。当前 Go 源码中的 Reset 会把内部状态清空；因此不要把上一轮的 Cap 当成长期稳定的内存复用指标。需要预留本轮预计写入量时，可以在本轮开始后使用 Grow，而不是依赖上一轮的偶然容量。

最小安全写法：先取结果，再进入下一轮

把 Builder 作为局部变量或指针字段保存都可以，关键是让写入动作始终落在同一个实例上。下面的函数每次进入时先清空 Builder，再按当前输入重新构建字符串；返回值在函数结束时已经是独立的字符串结果，调用方不需要继续持有 Builder。

package main

import (
    "fmt"
    "strings"
)

// renderLine 复用传入的 Builder，但把本轮结果作为字符串返回。
func renderLine(builder *strings.Builder, name string, count int) string {
    // Reset 只清空当前累计内容，避免上一轮文本残留。
    builder.Reset()
    // Grow 为本轮预计写入预留空间；估算不准也不会改变正确性。
    builder.Grow(len(name) + 16)
    builder.WriteString("name=")
    builder.WriteString(name)
    builder.WriteString(" count=")
    fmt.Fprintf(builder, "%d", count)
    // 先取出本轮字符串，再由下一轮继续使用 Builder。
    return builder.String()
}

func main() {
    var builder strings.Builder
    fmt.Println(renderLine(&builder, "go", 2))
    fmt.Println(renderLine(&builder, "web", 3))
}

这段写法的边界很明确：每次调用都从空内容开始，Grow 只是减少本轮扩容机会，不能代替 Reset。如果把 String() 得到的结果保存下来，后续再重置 Builder 也不会把调用方的字符串变量变成“上一轮加下一轮”的混合内容。

三类容易出错的复用方式

第一类是忘记 Reset。这样下一次写入会直接追加到旧内容上，表现为日志前缀、缓存键或响应片段重复。第二类是按值复制已经写过内容的 Builder。标准库明确要求不要复制非零 Builder，复制后继续写入可能触发运行时检查。

第三类是把一个 Builder 放在多个 goroutine 之间共享。Builder 没有并发同步语义；如果并发任务各自构建结果，应让每个任务拥有自己的 Builder，最后再合并结果，或者在更外层用锁保护整个使用区间。

// 错误示例：非零 Builder 不应按值传递。
func appendSuffix(builder strings.Builder) string {
    // 这里的按值参数会复制已经使用过的 Builder，属于不安全边界。
    builder.WriteString("-suffix")
    return builder.String()
}

// 推荐示例：传指针，且由调用者明确管理生命周期。
func appendSuffixSafely(builder *strings.Builder) string {
    builder.WriteString("-suffix")
    return builder.String()
}

真的需要保留容量时，考虑 bytes.Buffer

如果需求是“清空长度，但尽量保留已经申请的字节空间”，bytes.Buffer 的语义更贴近这个目标。它适合构建字节序列，也能通过 String 在最终需要时转成字符串。两者不要只按名字替换：Builder 更直接地表达字符串构建，Buffer 则提供字节缓冲的读写能力。

如果使用 sync.Pool 保存 Builder，也要把它当作降低短期分配压力的可选优化，而不是缓存永久存在的保证。取出对象后仍应先 Reset，提交回池前确保没有别的代码继续使用它；池本身也可能丢弃元素。

复用前的速查清单

• 是否在本轮写入前调用了 Reset？
• 是否只传递 Builder 指针，而不是复制已经写入内容的值？
• 是否把 String() 的返回值和 Builder 生命周期分开管理？
• 是否误把 Cap() 当成下一轮必然保留的容量？
• 是否真的需要字节缓冲、读取和容量保留；如果是，是否应选 bytes.Buffer？

相关问题

strings.Builder 可以并发使用吗？不应把同一个实例交给多个 goroutine 并发读写；让每个任务使用独立实例更清晰。

Grow 传负数会怎样？Grow 的参数必须是非负数，负数会触发 panic。容量估算不确定时，可以少预留，但不要用负数表达“未知”。

Reset 后旧字符串会被清空吗？已经通过 String() 返回并保存的字符串应作为结果值管理；真正需要避免的是继续引用 Builder 自身的内部构建状态。