Go bufio.Writer Available 返回的容量怎么用于批量写入

批量生成日志、CSV 行或协议帧时，很多代码只关注“写了多少”，却忽略了当前 bufio.Writer 还剩多少缓冲空间。Available() 返回的不是底层文件或网络连接的可写容量，而是 Writer 内部缓冲区尚未使用的字节数。把这个数和一条记录的字节长度放在同一个判断里，就能让批次边界更稳定。

最实用的判断是：记录长度不超过 w.Available() 时，可以把它作为当前批次的一部分写入；记录更大时，不要强行把它拆成“缓冲大小”，让 Write 按自身规则处理，并始终检查最后一次 Flush 的错误。

Available、Buffered 和 Size 的关系

Size() 表示内部缓冲区总大小，Buffered() 表示已经占用的字节数，Available() 则是当前还能放入的字节数。Go 标准库源码的实现就是用缓冲区长度减去当前写入位置，因此它反映的是 Writer 的瞬时状态。

让批次边界跟着剩余容量变化

假设每条记录都要保持完整，批量写入时应先计算 len(record)。只要记录不超过 Available()，直接 Write 就能继续累积；当它放不下时，可以先 Flush 已有批次，再写入当前记录。这样“批次满了”由真实字节数决定，而不是用一个与记录内容无关的固定条数猜测。

package main

import (
    "bufio"
    "bytes"
    "fmt"
)

// writeRecords 按完整记录控制批次，不把一条记录拆到两个批次中。
func writeRecords(records []string) (string, error) {
    var dst bytes.Buffer
    w := bufio.NewWriterSize(&dst, 16)

    for _, record := range records {
        data := []byte(record)
        // 容量不足时先提交已有记录，避免批次边界被悄悄推迟。
        if len(data) > w.Available() && w.Buffered() > 0 {
            if err := w.Flush(); err != nil {
                return "", fmt.Errorf("flush batch: %w", err)
            }
        }

        // 超过整个缓冲区的记录由 Writer 自己处理，不能假设会被拆分。
        if _, err := w.Write(data); err != nil {
            return "", fmt.Errorf("write record: %w", err)
        }
    }

    // 最后一批仍在内存缓冲中，必须显式 Flush。
    if err := w.Flush(); err != nil {
        return "", fmt.Errorf("flush final batch: %w", err)
    }
    return dst.String(), nil
}

func main() {
    result, err := writeRecords([]string{"id=1\n", "id=2\n", "long-record=abcdef\n"})
    if err != nil {
        panic(err)
    }
    fmt.Print(result)
}

这里的关键不是每次都主动刷新，而是只在“已有缓冲数据且下一条完整记录放不下”时刷新。若当前缓冲为空，单条记录仍然大于 Size()，bufio.Writer.Write 会把大写入直接交给底层 Writer，避免先复制进一个放不下的内部缓冲。

AvailableBuffer 适合构造紧邻写入的记录

如果记录需要用 strconv.AppendInt 或 append 拼接，Go 1.18 起可以先拿到 w.AvailableBuffer()，在这块容量上构造数据，再立刻传给 w.Write。这个切片的生命周期很短：下一次对同一个 Writer 写入后，就不能继续依赖它。

import (
    "bufio"
    "strconv"
)

// appendRecord 利用 Writer 的剩余容量构造一条紧邻写入的记录。
func appendRecord(w *bufio.Writer, id int64) error {
    buf := w.AvailableBuffer()
    buf = append(buf, "id="...)
    buf = strconv.AppendInt(buf, id, 10)
    buf = append(buf, '\n')
    // AvailableBuffer 只保证服务于紧随其后的这一次 Write。
    _, err := w.Write(buf)
    return err
}

如果业务记录可能大于当前容量，append 仍可能扩容到 Writer 缓冲之外，最终要以 Write 的返回值和错误为准。不要把 AvailableBuffer 保存到循环外，也不要在下一次写入后再修改它。

三个容易误用的边界

第一，Available() 是字节数，不是字符数或记录数。中文文本、表情符号和 UTF-8 编码内容必须按 len([]byte(text)) 计算。第二，容量变成零只说明当前缓冲已满，不等于底层 Writer 已经成功接收；真正的下游错误通常在 Flush 或写入时返回。第三，复用 Writer 前要确认上一批已经刷新，否则 Reset 会丢弃未刷出的数据。

常见问题

Available 返回 0 时必须立刻 Flush 吗？

不一定。下一次 Write 会按 Writer 的实现处理满缓冲；如果你需要按完整记录控制批次，或者想在一个明确的业务边界提交，就主动 Flush 并检查错误。

Available 能判断文件或网络还能写多少吗？

不能。它只描述 bufio.Writer 的内部空间，磁盘、内核发送缓冲和远端服务的状态要由底层 Writer 的错误和应用层协议判断。

一条记录比 Size 大，应该手动切片吗？

只有协议明确允许分片时才切片。对普通文本或日志记录，保留完整记录并直接调用 Write 更安全，让 Writer 自己选择刷新或直写路径。

为什么写完 bytes.Buffer 还是空的？

数据可能仍在 bufio.Writer 的内部缓冲中。调用最后一次 Flush 后再读取下游 Buffer，并处理返回的错误。