Go bufio.Reader.UnreadRune 失败时怎样避免读取位置错乱

Go 里的 bufio.Reader.UnreadRune 不是“撤销最近一次读取”的通用按钮。它只有在最近一次方法调用确实是 ReadRune 时才有资格回退，而且一次成功回退后，不能紧接着再次回退。要避免读取位置错乱，关键是把“判断字符”和“回退字符”放在同一段代码里，并立即检查返回的错误。

官方文档：https://pkg.go.dev/bufio#Reader.UnreadRune

稳定规则可以记成一句话：ReadRune → 判断 → UnreadRune。中间插入 ReadByte、Read、Peek、Discard 或其他会改变 Reader 状态的调用，回退资格就可能被清除；失败后不要假设读取位置已经恢复。

先把 UnreadRune 的成功条件讲清楚

ReadRune 每次读取一个 UTF-8 字符，同时返回 rune 和它占用的字节数。UnreadRune 回退的不是“一个字节”，而是最近一次 ReadRune 记录的那个 rune。因此中文字符、表情符号等多字节字符也能按一个字符回退。

标准库内部会记录最近一次 rune 的字节大小。只要最近一次操作不是 ReadRune，这项状态就无效，UnreadRune 会返回 bufio.ErrInvalidUnreadRune。成功回退后，回退资格也会被清除，所以不能把它当成可连续调用的栈。

最小的安全写法如下，先读取，再判断，最后在没有插入其他 Reader 操作的情况下回退：

package main

import (
	"bufio"
	"fmt"
	"strings"
)

func main() {
	// 用多字节字符说明 UnreadRune 回退的是一个 rune，而不是一个字节。
	reader := bufio.NewReader(strings.NewReader("Go语言"))

	ch, size, err := reader.ReadRune()
	if err != nil {
		// 读取失败时没有可回退的字符，先结束当前分支。
		fmt.Println("读取失败:", err)
		return
	}
	fmt.Printf("当前字符=%q，字节数=%d\n", ch, size)

	// 只有最近一次调用是 ReadRune 时，UnreadRune 才有确定的回退资格。
	if err := reader.UnreadRune(); err != nil {
		fmt.Println("回退失败:", err)
		return
	}

	// 回退成功后再次 ReadRune，得到刚才的同一个字符。
	again, _, err := reader.ReadRune()
	if err != nil {
		fmt.Println("重新读取失败:", err)
		return
	}
	fmt.Printf("回退后重新读取=%q\n", again)
}

这里的 size 主要用于诊断，不需要手动拿它去修改文件偏移。Reader 已经保存了回退所需的内部状态；业务代码只需要把错误当成读取状态的一部分处理。

哪些调用会让回退条件失效

排查 UnreadRune 失败时，先看它前面最近的一次 Reader 方法，而不是先怀疑 UTF-8。最常见的错误是先 ReadRune，随后为了查看下一个字节调用了 ReadByte 或 Peek，最后才调用 UnreadRune。此时“最近一次操作”已经不是 ReadRune。

func readWordPrefix(reader *bufio.Reader) (rune, error) {
	// ReadRune 建立本次判断所需的回退资格。
	ch, _, err := reader.ReadRune()
	if err != nil {
		return 0, err
	}

	if ch == '_' {
		return ch, nil
	}

	// 不要在这里先 ReadByte、Peek 或 Discard，再尝试 UnreadRune。
	// 中间操作可能清除最近一次 ReadRune 的状态。
	if err := reader.UnreadRune(); err != nil {
		return 0, fmt.Errorf("撤销首字符失败: %w", err)
	}
	return 0, nil
}

上面的函数只保留一个判断分支：不是下划线就立刻回退。若解析器确实需要预读多个字节，应该改用 Peek 设计“查看但不消费”的策略，而不是把 Peek 和 UnreadRune 串成一条隐含的撤销链。

下面这段调用顺序看似合理，实际上会失败：

reader := bufio.NewReader(strings.NewReader("abc"))

// 先读取一个 rune。
_, _, _ = reader.ReadRune()
// ReadByte 会让“最近一次是 ReadRune”的前提不再成立。
_, _ = reader.ReadByte()
// 这里应检查错误，不能假设位置回到了第一个字符之前。
if err := reader.UnreadRune(); err != nil {
	fmt.Println("预期中的回退失败:", err)
}

如果代码跨函数调用 Reader，要特别留意被调用函数是否偷偷执行了 Peek、Discard 或普通 Read。这类隐式读取会让上层函数的 UnreadRune 失败。Reset 则会重置 Reader 的缓冲数据和状态，不能把 Reset 前读取的字符拿到 Reset 后回退。

把回退逻辑收进解析分支

在实际解析器里，最稳妥的做法是让一次“读取—判断—可选回退”保持局部闭环，并把 ErrInvalidUnreadRune 原样包装到业务错误中。这样日志能区分输入结束、UTF-8 解码结果和调用顺序错误。

常见问题

UnreadRune 能连续调用两次吗？

不能。一次成功回退会清除这次回退资格；如果需要保存多个候选位置，应在业务层复制数据或重新设计解析窗口。

ReadRune 读到非法 UTF-8 后还能回退吗？

ReadRune 会把非法编码按一个字节消费并返回替换字符。只要它仍是最近一次 Reader 方法调用，回退契约仍按这次 ReadRune 处理；是否接受非法输入则由业务校验决定。

为什么不用 UnreadByte 代替 UnreadRune？

UnreadByte 面向字节，不能表达一个多字节 UTF-8 字符的完整边界。按字符解析时使用 ReadRune 与 UnreadRune，按字节协议解析时再选择字节级接口。

最后记住：UnreadRune 的可靠性来自调用顺序，而不是调用者自己维护的猜测位置。把回退动作紧跟在 ReadRune 后面、立即检查错误，并在需要预读时改用 Peek，就能避免失败后继续读取造成的错位。