Go binary.PutVarint 预分配缓冲区与负数编码边界

binary.PutVarint 适合把一个 int64 写成节省空间的有符号变长编码，但它的使用前提很明确：调用方必须先准备足够大的 []byte，再用返回值截取真正有效的字节。最稳妥的起点是使用 binary.MaxVarintLen64 预分配容量；负数并不会按固定 8 字节写入，而是经过符号映射后参与变长编码。

一次常见的故障现场是：协议字段偶尔出现负数，代码却按“一个整数就是 8 个字节”去切片；或者缓冲区只分配了 1～2 个字节，平时的小正数没暴露问题，边界值一到就发生越界。排查时应把编码容量、返回长度和底层写入拆开看。

PutVarint 的输入、容量和编码结果如何对应

PutVarint(buf, x) 会把 int64 编码到调用方提供的缓冲区，并返回写入的字节数。官方文档明确说明，缓冲区太小时该函数会触发 panic，所以容量不是一个可有可无的性能参数，而是调用契约的一部分。

package main

import "encoding/binary"

func encodeSigned(x int64) []byte {
    buf := make([]byte, binary.MaxVarintLen64)
    n := binary.PutVarint(buf, x)
    return buf[:n]
}

这里没有把结果固定成 buf[:8]。小整数通常只需要较少字节，负数也会参与同一套变长编码；真正应该交给网络或文件的是 buf[:n]。MaxVarintLen64 表示 64 位变长整数的最大编码长度，预留它可以覆盖任意 int64 输入。

负数为什么不能按固定 8 字节理解

有符号变长编码的目标是让较小的绝对值尽量使用较短表示。PutVarint 会先把有符号值映射到无符号空间，再使用变长字节布局；解码端的 binary.Varint 会执行相反的映射。因此，编码长度由映射后的值决定，不能仅凭“类型是 int64”推断长度。

这也解释了两个排查误区。第一，n 不是“应该写入 8 的某个比例”，而是本次输入实际占用的字节数。第二，编码结果的尾部可能仍保留缓冲区旧内容，不能把整个 buf 交给下游。只有 buf[:n] 属于当前字段。

把返回长度接入批量写入路径

如果编码结果要进入文件、网络连接或自定义 io.Writer，建议让“编码”和“提交”各自承担清晰职责：编码函数只返回有效字节，写入层负责处理短写、底层错误和批次边界。下面的示例不依赖固定协议头，适合说明这条边界。

import (
    "encoding/binary"
    "io"
)

func writeVarints(w io.Writer, values []int64) error {
    buf := make([]byte, binary.MaxVarintLen64)
    for _, value := range values {
        n := binary.PutVarint(buf, value)
        if _, err := w.Write(buf[:n]); err != nil {
            return err
        }
    }
    return nil
}

示例中的 buf 可以在循环中复用，因为每轮只把 buf[:n] 交给 Writer。若底层 Writer 还包着缓冲层，应在明确的批次结束处调用对应的 Flush，并把错误返回给上层；PutVarint 成功只代表字节已经写入调用方的内存，不代表数据已经到达最终介质或对端。

容量和协议边界的检查清单

• 先保容量：单值编码优先使用 binary.MaxVarintLen64，只有在协议已证明范围更窄时才缩小。
• 再取长度：始终保存 n，写入或拼接时只使用 buf[:n]。
• 分清错误：容量不足是调用方 bug，Writer 返回错误是输出路径问题，解码失败还可能是双方协议约定不一致。
• 检查提交：有缓冲 Writer 时，在批次、响应或资源关闭前处理 Flush() 返回值。

如果协议允许负数，测试样例至少应覆盖 0、正负小值和接近 int64 边界的值；测试重点不是记住某个固定字节串，而是验证编码端返回长度、解码端消费长度与字段边界能够互相对齐。

常见问题

PutVarint 的缓冲区可以只分配 8 个字节吗？

不建议用类型宽度代替编码契约。应按 binary.MaxVarintLen64 预留，或者由协议明确证明更小容量一定覆盖所有输入；容量不足不会由 PutVarint 自动扩容。

为什么不能把整个 buf 写出去？

因为缓冲区通常大于本次编码的有效长度，尾部可能是旧数据或零值。返回的 n 才是当前结果边界，写入时应使用 buf[:n]。

PutVarint 成功后还要检查 Writer 错误吗？

要。PutVarint 只完成内存中的编码；文件、网络或缓冲 Writer 的写入和 Flush 仍可能失败，最终状态必须由输出层确认。