Go binary.Varint 返回负数读取长度是什么意思

binary.Varint 的第二个返回值 n 小于 0，表示输入编码出的值超过了 64 位范围，也就是 varint 溢出；此时 -n 才是函数为确认溢出而读取的字节数。它不是“读取了负数字节”，更不能直接拿 n 做切片下标。

官方文档：https://pkg.go.dev/encoding/binary

我为什么会把 n 小于 0 看错

我第一次在批量帧解析器里遇到这个返回值时，把 n 统一归为“半包”。这在数据量小时很隐蔽：半包确实应该等待，但溢出输入永远等不到“补完整”的那一刻。结果是解析器反复保留同一段坏数据，缓冲区持续增长，后面的正常帧也无法前进。

问题不在 varint 本身，而在调用方把两种性质完全不同的失败合并了。n == 0 是暂时缺数据；n 是已经可以确定的格式错误。前者需要等待，后者需要拒绝或按协议丢弃。

先把 n 分成三种状态

Go 标准库对 Varint 的契约写得很直接：返回值为正表示成功，零表示缓冲区太小，负数表示溢出。64 位 varint 最长为 binary.MaxVarintLen64，也就是 10 字节；源码还会捕获超过这一上限的连续字节，以及第 10 个字节携带超出有效范围的情况。

把三态包装成调用方能直接处理的结果

我后来把 binary.Varint 封装在一个很薄的函数里，目的不是隐藏标准库，而是禁止业务代码遗漏某个分支。成功时返回真实消耗量；不完整时返回 io.ErrUnexpectedEOF；溢出时把 -n 写进错误信息。

package main

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

func decodeVarint(buf []byte) (int64, int, error) {
    value, n := binary.Varint(buf)

    switch {
    case n > 0:
        // 成功时，n 才是可以用于推进切片的字节数。
        return value, n, nil
    case n == 0:
        // 当前数据不完整，调用方应保留缓冲区并等待更多字节。
        return 0, 0, io.ErrUnexpectedEOF
    default:
        // 溢出时，-n 是为确认错误而读取的字节数。
        return 0, -n, fmt.Errorf("varint overflow after %d bytes", -n)
    }
}

这里把溢出分支返回的第二个值改成正数，方便日志和上层策略使用，但要注意：这不代表所有协议都应该自动丢弃这 -n 个字节。是否推进缓冲区，要由帧边界和恢复策略决定。

增量缓冲区里，等待和拒绝必须分开

网络读取常常把一个 varint 拆成多个包。对于 n == 0，解析器应该原样保留缓冲区；对于 n ，继续等待只会让坏数据占住队头。我的做法是让帧层决定恢复方式：有明确帧长度时跳过整个坏帧；没有可靠边界时关闭连接，避免从任意字节重新同步。

func parseLengthPrefix(buf []byte) (length int64, rest []byte, needMore bool, err error) {
    value, n := binary.Varint(buf)

    if n > 0 {
        // 只有成功分支才能安全推进到剩余载荷。
        return value, buf[n:], false, nil
    }
    if n == 0 {
        // 半包不消费任何数据，等待下一次读取后重试。
        return 0, buf, true, nil
    }

    // 溢出说明前缀已经非法；具体丢弃范围交给更了解帧边界的上层。
    return 0, buf, false, fmt.Errorf("invalid length prefix: overflow after %d bytes", -n)
}

这段代码刻意没有写 buf = buf[-n:]。虽然 -n 表示已读取字节数，但在没有可靠帧边界时，跳过这些字节后继续解析可能把载荷内容误认成新前缀。恢复策略属于协议层，不属于 binary.Varint。

Varint 和 ReadVarint 怎么选

两套接口解码的是同一种格式，但错误表达不同。已经有连续 []byte 缓冲区时，binary.Varint 最省事，代价是必须正确处理 n 三态。数据来自实现了 io.ByteReader 的流时，binary.ReadVarint 更自然，它通过 error 报告问题。

ReadVarint 在一个字节都没读到时返回 io.EOF，读到一部分后遇到 EOF 时返回 io.ErrUnexpectedEOF。它的溢出错误由标准库内部返回，不需要调用方解释负数长度。不过 Reader 接口会逐字节读取，若系统本来就维护聚合缓冲区，为了换错误形式而强行改接口通常没有必要。

上线前我会固定这四类边界测试

这类解析错误很适合表格测试。最重要的不是多测几个普通整数，而是让三个返回状态都稳定出现，并把 10 字节边界单独覆盖。

func TestVarintStates(t *testing.T) {
    tests := []struct {
        name string
        data []byte
        wantSign int
    }{
        {name: "成功", data: []byte{0x02}, wantSign: 1},
        {name: "数据不完整", data: []byte{0x80}, wantSign: 0},
        {name: "第十字节溢出", data: []byte{0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x02}, wantSign: -1},
        {name: "超长连续字节", data: []byte{0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80}, wantSign: -1},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // 这里只验证 n 的状态，具体数值可在独立用例中断言。
            _, n := binary.Varint(tt.data)
            gotSign := 0
            if n > 0 {
                gotSign = 1
            } else if n 

生产环境里，我还会把“不完整”和“溢出”拆成两个指标。前者偶尔出现很正常，因为网络分包不可避免；后者持续增长通常说明上游编码错误、协议不一致或异常输入。两个指标混在一起，只会把真正需要处理的坏数据藏在正常半包里。

常见问题

n 为负数时，返回的 value 还能用吗？

不能把它当作有效结果。官方契约规定发生错误时值为 0，调用方应先检查 n，只在 n > 0 时使用 value。

-n 是应该从缓冲区删除的字节数吗？

它是函数为确认溢出而读取的字节数，但是否删除取决于协议恢复策略。有明确帧边界时可以丢弃整帧；没有边界时盲目跳过 -n 个字节可能造成错误重同步。

为什么十个字节也可能溢出？

64 位 varint 最长是 10 字节，但第 10 个字节只能承载最后一个有效位。源码会在第 10 个字节大于 1 时判定溢出，所以“长度没有超过 10”不等于编码一定合法。

Uvarint 的 n 规则一样吗？

一样。binary.Varint 先调用 Uvarint，再做有符号整数的 zig-zag 还原，因此成功、缓冲区不足和溢出的 n 语义保持一致。

最终我把这条规则浓缩成一句代码审查标准：只在 n 大于 0 时推进切片，n 等于 0 时等待，n 小于 0 时按溢出拒绝并用 -n 做诊断。这样既不会把半包误杀，也不会让确定的坏数据无限堵住解析器。