Go binary.PutUvarint 怎样把整数写入固定字节缓冲区

如果你已经知道协议字段最多只需要 10 个字节，想把一个 uint64 写进预先分配好的切片，binary.PutUvarint 就是直接的做法：准备至少 binary.MaxVarintLen64 字节的缓冲区，调用函数，再只使用返回的 n 个字节。

官方地址：https://pkg.go.dev/encoding/binary#PutUvarint

关键点是：PutUvarint 不返回新切片，而是原地写入并返回实际长度；缓冲区太小会 panic，所以容量和 buf[:n] 都不能省略。

PutUvarint 到底写入了什么

无符号变长整数会把较小的数编码成较少的字节。比如 127 只需要一个字节，128 开始需要两个字节。函数签名是：

func PutUvarint(buf []byte, x uint64) int

这里的 buf 是调用方管理的目标空间，x 是要编码的整数，返回值 n 是本次真正写入的字节数。它不会告诉你一个新的切片，因此后续发送或拼接时应使用 buf[:n]。

先准备不会越界的固定缓冲区

64 位无符号整数的变长编码最多占 10 个字节。直接使用标准库常量比手写数字更不容易出错：

package main

import (
    "encoding/binary"
    "fmt"
)

func main() {
    // MaxVarintLen64 给 uint64 预留最坏情况下的 10 字节空间。
    buf := make([]byte, binary.MaxVarintLen64)
    value := uint64(300)

    // PutUvarint 原地写入，n 表示本次实际占用的字节数。
    n := binary.PutUvarint(buf, value)
    encoded := buf[:n]

    // 只输出有效区间，不能把尚未使用的尾部一起写入协议。
    fmt.Printf("value=%d bytes=%x length=%d\n", value, encoded, n)
}

这段代码的核心不是打印，而是 encoded := buf[:n]。如果把完整的 buf 交给网络写入或文件写入，就会把尾部的零值也当成数据，接收方可能无法判断下一个字段从哪里开始。

返回长度会随着数值边界变化

变长编码的长度不是固定的。下面的例子把几个边界值放在一起，便于观察 127 到 128 的变化：

package main

import (
    "encoding/binary"
    "fmt"
)

func main() {
    values := []uint64{0, 127, 128, 16383, 16384}
    buf := make([]byte, binary.MaxVarintLen64)

    for _, value := range values {
        // 复用同一个最大缓冲区，每轮只读取本轮返回的 n 个字节。
        n := binary.PutUvarint(buf, value)
        fmt.Printf("%5d -> % x (%d bytes)\n", value, buf[:n], n)
    }
}

复用缓冲区是安全的，前提是每次都按本次返回的 n 截取。上一次写入较长数据留下的尾部不属于当前编码。

用 Uvarint 配对解码并识别异常

编码端返回了 n，解码端也会返回一个读取字节数。n > 0 表示成功；n == 0 表示给出的字节还不够；n 表示数值溢出。

package main

import (
    "encoding/binary"
    "errors"
    "fmt"
)

func decodeUvarint(data []byte) (uint64, error) {
    value, n := binary.Uvarint(data)
    switch {
    case n == 0:
        // 流式读取时，输入不足通常意味着还要等待更多字节。
        return 0, errors.New("varint 输入不完整")
    case n 

在网络协议中，n == 0 不一定是永久错误，它常常表示当前读取窗口还没有拿到完整字段；而 n 需要丢弃当前字段并记录协议错误。

缓冲区太小时为什么会 panic

PutUvarint 的契约要求调用方先提供足够空间。下面这样的写法风险很明确：

// 只分配 1 字节，无法容纳大多数 uint64 的变长编码。
buf := make([]byte, 1)
// value 需要多个字节时，PutUvarint 会因缓冲区不足而 panic。
n := binary.PutUvarint(buf, 300)

如果字段上限明确且小于 64 位，可以按协议上限分配；通用代码则直接使用 binary.MaxVarintLen64。不要先猜一个“常见长度”再依赖偶然不触发边界。

PutUvarint 和 AppendUvarint 怎么选

两者生成的是同一种变长整数编码，区别主要在空间所有权：PutUvarint 把容量责任交给调用方，AppendUvarint 把追加和扩容交给切片 API。

排查清单

• 目标缓冲区是否至少有 binary.MaxVarintLen64 字节？
• 发送、写文件或拼接时是否使用了 buf[:n]？
• 解码端是否区分 n == 0 的输入不足和 n 的溢出？
• 如果需要动态追加，是否误用了固定缓冲区 API？

记住“固定空间、原地写入、返回长度”这三个词，就能稳定使用 binary.PutUvarint：容量由调用方保证，数据范围由返回的 n 保证，异常由解码端的返回状态保证。

常见问题

PutUvarint 会返回新的字节切片吗？

不会。它只返回实际写入的字节数，调用方继续使用原切片的 buf[:n]。

为什么 128 比 127 多占一个字节？

Uvarint 是变长编码，小数值优先使用更短表示；跨过 127 后需要额外字节承载剩余位。

可以用 PutUvarint 编码负数吗？

它的参数是 uint64。如果协议字段是有符号整数，应先确认编码约定，并考虑 binary.PutVarint 的 ZigZag 变长表示语义。