Go bufio.NewWriterSize 怎样设置合适的缓冲区容量

bufio.NewWriterSize 的容量没有通用的“越大越快”答案。更稳妥的起点是：先估计单条写入和一小批写入的大小，再给每个 Writer 分配能覆盖常见批次的容量，最后用 Size()、Buffered() 和 Flush() 观察实际状态。对日志、批量文本和大块文件写入，应分别做选择，而不是给所有输出统一套一个很大的数字。

官方资料入口：https://pkg.go.dev/bufio#NewWriterSize

先分清 NewWriterSize 的 size 到底控制什么

NewWriterSize(w, size) 返回一个 *bufio.Writer，它把数据暂存在自己的缓冲区，再通过底层的 io.Writer 输出。这里的 size 描述的是缓冲区容量下限，不是单次写入的硬上限，也不是保证每写多少字节就立刻落盘的阈值。

官方实现还规定了两个容易忽略的边界：当 size 时使用默认容量；如果传入的对象本来就是一个容量足够大的 *bufio.Writer，函数可以直接返回它，而不会再包一层。也就是说，重复包装并不能用一个更小的 size 把已有缓冲区缩小。

package main

import (
    "bufio"
    "os"
)

func newLogWriter(path string) (*bufio.Writer, *os.File, error) {
    file, err := os.Create(path)
    if err != nil {
        return nil, nil, err
    }

    // 先给日志 Writer 一个明确的起始容量；实际数值应结合记录大小调整。
    writer := bufio.NewWriterSize(file, 16*1024)
    return writer, file, nil
}

这个示例把文件句柄和缓冲 Writer 一起返回，调用方仍然要在写完后先处理 Flush()，再关闭文件。只关闭文件并不能替代对缓冲数据的显式提交。

用 Size 和 Buffered 看清缓冲状态

Size() 返回底层缓冲区的总大小，Buffered() 返回已经写入当前缓冲区、但还没有提交给底层 Writer 的字节数。一个 Writer 可能拥有很大的总容量，但当前只缓存了很少数据；也可能因为记录集中到来而接近满载。

func writeBatch(w *bufio.Writer, records []string) error {
    for _, record := range records {
        // Write 只表示数据被 Writer 接收，不代表底层目标已经完成写入。
        if _, err := w.WriteString(record + "\n"); err != nil {
            return err
        }
    }

    // 用两个观测值区分“总容量”和“当前积压”，避免只看一个数字。
    _ = w.Size()
    _ = w.Buffered()

    // 批次边界必须显式 Flush，并把底层错误交给调用方。
    return w.Flush()
}

如果 WriteString 或 Flush 返回错误，调用方不要把这次输出当成成功。bufio.Writer 会记住底层写入错误，之后的写入和 Flush 也会继续返回该错误；这时继续追加数据通常没有意义，应记录上下文并结束或切换到新的目标。

按写入记录大小选择一个可解释的起点

容量选择首先看输入形态，而不是先抄一个“最佳值”。可以把一批常见记录的总量作为起点，再留出少量余量，随后结合内存和底层目标的实际表现调整。

这些数字只是工程起点，不是基准测试结论。每个 Writer 都会保留自己的缓冲区；如果同时服务很多请求，把容量从 16 KB 放大到 1 MB，内存成本会随并发实例数量线性增加。更大的缓冲也可能让错误更晚暴露，不能只看底层写入调用次数。

重复包装、超大写入和 Flush 错误怎么处理

有三个边界值得单独记住。第一，若把一个已经足够大的 *bufio.Writer 再传给 NewWriterSize，不能借助更小的 size 缩容；需要换容量时，应明确创建新的 Writer，并处理旧 Writer 中尚未提交的数据。第二，当单次写入大于剩余缓冲空间时，Writer 可能先刷新已有数据，再继续处理输入；容量不是对单次 Write 的限制。

第三，Flush() 是输出生命周期的一部分，必须检查返回值。文件、网络响应或队列写入都不能仅凭“Write 没报错”就宣布完成，因为部分数据可能仍停留在缓冲区。

func closeWriter(w *bufio.Writer, file *os.File) error {
    // 先提交缓冲区，确保函数返回前把错误暴露出来。
    if err := w.Flush(); err != nil {
        _ = file.Close()
        return err
    }

    // Flush 成功后再关闭文件，关闭错误同样不能被丢弃。
    return file.Close()
}

如果底层 Writer 失败后需要换目标，不要复用已经记住错误的旧 Writer。可以创建新的 bufio.Writer，把仍然明确属于业务的未提交数据按业务规则重新组织；是否重试、如何避免重复写入，则要由上层协议决定。

一张速查表：什么时候该调大或调小

• 调大：记录较短但经常成批到来，底层目标适合批量写入，且并发 Writer 数量可控。
• 调小：请求并发高、每次只写少量内容，或需要更早暴露底层错误。
• 先不调：单次写入本身已经远大于缓冲区，或者底层已经提供高效的批量写入路径。
• 必须配套：在明确的批次、响应结束或资源关闭前调用 Flush() 并处理错误。

常见问题

NewWriterSize 的 size 越大越好吗？

不是。它会增加每个 Writer 的内存占用，也可能让错误更晚出现。应该从常见批次大小和并发数量出发选择起点。

size 设置为 0 会得到一个零容量 Writer 吗？

不会。官方实现会把小于等于 0 的值改为默认缓冲区大小；如果需要明确容量，应直接传入正数并用 Size() 观察。

Write 成功后是不是已经写入文件？

不一定。Write 可能只把数据复制进 bufio 的缓冲区，真正提交到底层目标要看缓冲是否被刷新，以及最终的 Flush() 是否成功。