Go bufio.Reader让 UnreadByte 与缓冲位置匹配的边界

在协议解析里，先读一个字节判断是不是目标前缀，再决定交给后续逻辑还是放回去，是 bufio.Reader 很常见的用法。要让 UnreadByte 与缓冲位置匹配，关键规则只有一条：它只能回退最近一次成功读取的一个字节，而且回退成功后不能再次回退同一个字节。中间插入 Peek、Discard 或其他改变状态的调用，都会让这次回退失效。

先把 UnreadByte 的“最近一次读取”边界说清楚

UnreadByte 的语义不是“把缓冲区指针随便减一”，而是“撤销最近一次读取操作拿到的最后一个字节”。官方文档明确说明，最近一次方法调用必须是读取操作；Peek 只查看缓冲区，Discard 直接跳过数据，WriteTo 也不算可供 UnreadByte 识别的读取。

调用成功后，Reader 会把当前位置向前移动一个字节，并立即清掉这次可回退状态。因此下面的第二次回退不是“再退一格”，而会得到 bufio.ErrInvalidUnreadByte：

package main

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

func main() {
	r := bufio.NewReader(bytes.NewBufferString("GET"))
	c, err := r.ReadByte() // 先成功读取一个字节，建立唯一的回退点
	if err != nil {
		fmt.Println("读取失败:", err) // EOF 等错误时没有可安全回退的字节
		return
	}
	fmt.Printf("读到 %q，缓冲剩余 %d 字节\n", c, r.Buffered())

	if err := r.UnreadByte(); err != nil { // 第一次回退恢复到 G 之前
		fmt.Println("第一次回退失败:", err)
		return
	}
	if err := r.UnreadByte(); err != nil { // 回退状态已消费，第二次应当失败
		fmt.Println("第二次回退失败:", err)
	}
}

这里的 Buffered() 只能告诉你当前缓冲里还有多少可读字节，不能代替“最近一次方法是否为成功读取”的状态判断。也不要把它当成可以回退的历史长度。

让 ReadByte 与 Peek、Discard 不互相打断

最容易误判的场景是先用 Peek(1) 看首字节，再调用 UnreadByte。Peek 本身不会推进读取位置，但它会阻止当前这次 UnreadByte 成功，直到下一次读取操作重新建立状态。换句话说，“位置没有变化”不等于“存在可回退记录”。

如果任务只是试探一个字节，应把读取、判断和回退放在相邻代码里：

func acceptPrefix(r *bufio.Reader, want byte) (bool, error) {
	c, err := r.ReadByte() // ReadByte 成功后，UnreadByte 才有明确的最近字节
	if err != nil {
		return false, err // EOF 或底层错误时保持当前位置，不伪造回退
	}
	if c == want {
		return true, nil // 目标前缀已消费，调用方继续读取后续内容
	}
	if err := r.UnreadByte(); err != nil { // 非目标字节退回一次，交给其他解析分支
		return false, err
	}
	return false, nil
}

这个函数只允许“成功读取一个字节后，最多回退一次”。不要在 ReadByte 和 UnreadByte 之间调用 Peek、Discard、另一个读取器方法，也不要把同一个 Reader 交给多个并发解析协程；bufio.Reader 的这段状态没有并发安全承诺。

用四项检查固定缓冲位置

遇到 bufio: invalid use of UnreadByte 时，先不要调整 Reader 缓冲区大小。按下面四项检查，通常能快速定位：

1. 最近一次调用是不是成功的 Read、ReadByte 或其他读取方法？如果是 Peek、Discard、WriteTo，就没有可回退状态。
2. 读取是否真的拿到字节？检查 err 和 n，不能把零字节读取当成成功消费。
3. 这次回退是否已经成功过？成功后状态会失效，不能把它当作两级撤销。
4. 同一个 Reader 是否在多个解析分支之间交错调用？把试探逻辑集中到一个函数，或为不同流建立独立 Reader。

如果业务确实需要撤销多个字节，保存已经读出的数据并在业务层做回放，或者重新组织解析入口；不要依赖多次 UnreadByte。缓冲区容量只影响填充和可查看的数据量，不会改变这个 API 的回退协议。

相关问题

UnreadByte 能回退 Read 读出的全部字节吗？

不能。一次成功的 Read 即使返回多个字节，也只能回退最后一个字节；多字节撤销要由调用方保存和处理。

Peek 后为什么 UnreadByte 会失败？

因为 Peek 不被视为读取操作，并会阻止当前回退状态。需要回退时，应直接用成功的 ReadByte 建立最近字节。

UnreadByte 与 UnreadRune 可以混用吗？

可以理解为两套不同粒度的协议，但不应交错设计。按字节读取后用 UnreadByte，按 UTF-8 字符读取后用 UnreadRune，并各自只回退最近一次对应的读取。