Go strings.Builder.Reset 复用构建器时的容量保留边界

在循环里反复拼接响应、日志或模板片段时，strings.Builder.Reset() 是很容易被误解的接口：它负责把已经写入的内容清空，但“下一轮能不能直接复用原来的存储空间”不能靠猜，也不能把一次观察到的容量当成永久承诺。实用做法是把 Len()、Cap() 和下一轮写入量放在一起判断。

官方文档：https://pkg.go.dev/strings#Builder.Reset

Reset 清空的是长度，不是一次性的复用意图

Builder 的 Len() 表示已经累计的字节数，Cap() 表示底层存储的容量。调用 Reset() 后，长度回到零，后续写入从空内容开始；容量是否继续保留，应通过当前实现的 Cap() 观察，而不是把它当作接口层面的永久保证。

这一区分很重要。业务上说“复用构建器”，通常只是复用一个仍由当前代码独占的对象；它不等于复用上一次字符串的逻辑内容，也不等于允许多个 goroutine 同时写入。

用 Len、Cap 和下一轮写入量安排复用

下面的示例只演示状态判断，不把输出当成固定的运行证据。重点是：每次开始下一轮前先清空内容，再根据预计写入的字节数决定是否提前扩容。

package main

import (
    "fmt"
    "strings"
)

func main() {
    var b strings.Builder
    b.WriteString("request=alpha") // 第一轮写入一段可复用的文本。
    fmt.Println("before:", b.Len(), b.Cap()) // Len 是内容长度，Cap 是当前容量。

    b.Reset() // 只清空已写内容；下一轮仍由当前代码独占这个 Builder。
    nextSize := len("request=beta&trace=enabled")
    if b.Cap() 

Grow(n) 的含义是保证至少有 n 个字节可以继续写入而不必因为这次调用再次分配；它不是把最终字符串长度设置为 n，也不是要求容量精确等于 n。如果下一轮长度变化很大，直接让 Builder 按需增长往往比每次都计算容量更简单。

Grow 与 Reset 的组合边界

可以把复用策略分成三档：写入量稳定且对象独占时，Reset 后按经验容量继续写；写入量有上限且希望减少扩容时，Reset 后在 Cap 不足时调用 Grow；写入内容可能突然变得很大时，则要防止一次异常请求让长期持有的 Builder 留住过大的底层空间。

还要记住标准库的硬约束：不要复制一个已经写入过的非零 Builder。把它作为结构体值传参、赋值，或在并发代码中让多个执行单元共享，都可能破坏内部状态的所有权假设。需要跨函数传递时，优先传指针并明确调用方负责何时 Reset；需要并发时，每个任务拥有自己的 Builder。

复用前的检查清单

• 是否确认 Builder 在整个写入周期内只有一个所有者？
• 是否把 Len 当内容长度、把 Cap 当容量，而没有混用二者？
• 是否依据字节数决定 Grow，并为异常大输入设置边界？
• 是否避免把非零 Builder 复制进结构体、闭包或 goroutine？

常见问题

Reset 后一定会保留原来的 Cap 吗？

不要把容量保留当成业务契约。Reset 的确定语义是清空内容；如果复用策略依赖容量，应在当前代码路径中观察 Cap，并允许实现或输入变化带来不同结果。

Grow 之后能否直接得到指定长度的字符串？

不能。Grow 只保证后续写入空间，真正的长度仍由 Write、WriteString 或 WriteRune 等操作决定。

Builder 适合直接放进 sync.Pool 吗？

可以把“独占、清理、容量上限”作为前提评估，但不能无条件放入。取出后应确认使用者独占对象，归还前完成 Reset，并考虑极端大容量对象是否应该丢弃。