Go bufio.Reader.UnreadRune 与 ReadRune 配对的回退边界

bufio.Reader.UnreadRune 不是“把最近读到的字符退回去”的通用按钮。它只接受紧邻的一次 ReadRune，最多回退一个 UTF-8 符文；如果中间调用了其他读取方法，或已经回退过一次，就会返回 bufio.ErrInvalidUnreadRune。

记住一条调用契约：先用 ReadRune 试读，需要把这个符文交给后续解析时立刻调用一次 UnreadRune；不要在两者之间插入 ReadByte、Read、Peek、Discard 或第二次 UnreadRune。

官方文档地址：https://pkg.go.dev/bufio#Reader.ReadRune、https://pkg.go.dev/bufio#Reader.UnreadRune。实现参考：https://go.dev/src/bufio/bufio.go。

ReadRune 记录了什么，UnreadRune 回退什么

ReadRune 从 Reader 的缓冲区读取一个 UTF-8 编码字符，返回字符本身、占用的字节数和错误。ASCII 字符通常占 1 个字节，常见中文字符占 3 个字节；返回的 size 才是后退时需要使用的长度。

在实现里，读取成功后会把本次符文的字节数记到内部状态 lastRuneSize。UnreadRune 不重新解析字节，也不接收参数，而是依据这个状态把读指针向前移动同样的字节数，然后清空回退资格。所以它只能恢复“最近一次 ReadRune”读出的那个符文。

还要注意无效 UTF-8 的边界：文档规定遇到无效编码时会消耗一个字节，并返回 utf8.RuneError 与大小 1。此时如果紧接着调用 UnreadRune，回退的也是这个已经被当作一个符文处理的字节，不是任意长度的错误片段。

为什么会得到 ErrInvalidUnreadRune

最常见的错误不是 UTF-8 本身，而是调用顺序。下面的示例只展示接口契约，代码块中的注释说明每个分支的意图；不要把两次回退写成一个可重复调用的“撤销”操作。

package main

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

func main() {
	reader := bufio.NewReader(strings.NewReader("Go语言"))
	_, _, _ = reader.ReadRune() // 中文注释：先试读一个符文，再决定是否交还给解析器。
	if err := reader.UnreadRune(); err != nil { // 中文注释：只能紧接 ReadRune 回退一次。
		if errors.Is(err, bufio.ErrInvalidUnreadRune) { // 中文注释：把顺序错误与输入错误分开处理。
			fmt.Println("UnreadRune 调用顺序不合法")
			return
		}
		fmt.Println("回退失败:", err)
		return
	}

	// 中文注释：再次读取会重新建立新的配对，但不能连续第二次 UnreadRune。
	_, _, _ = reader.ReadRune()
}

核心只有两点：让同一个 Reader 连续完成 ReadRune 与 UnreadRune，并在错误处理里识别 ErrInvalidUnreadRune。为了避免把探测逻辑散落到多个层级，下面给出更适合直接改造的解析片段。

func readPrefixOrPutBack(r *bufio.Reader) (bool, error) {
	// 试读一个符文，只有不属于目标前缀时才把它交回去。
	ch, _, err := r.ReadRune()
	if err != nil {
		return false, err
	}
	if ch == '@' {
		return true, nil
	}
	if err := r.UnreadRune(); err != nil { // 中文注释：回退必须紧跟本次 ReadRune。
		return false, err
	}
	return false, nil
}

哪些调用会打断这次配对

UnreadRune 对顺序比 UnreadByte 更严格。源码中的状态字段会在其他读取动作中失效，因此下面几类写法都不能期待成功。

因此，解析器如果需要先看一个字符再决定由谁处理，最好把“试读—判断—立即回退”封装在一个小函数里。不要把 Reader 交给多个层级后，让上层的日志、探测或预读调用悄悄插入两次操作之间。

把规则落到实际解析边界

一个可靠的调用方通常遵循三条规则：第一，回退对象只使用最近一次 ReadRune 的返回结果；第二，回退后把 Reader 交还给明确的下一层，不在同一层继续猜测；第三，把 ErrInvalidUnreadRune 当作调用契约错误处理，而不是把它重试成无限循环。

如果业务需要回退多个符文，UnreadRune 就不是合适的缓存设计。可以在应用层保存已经读出的字符串或字节片段，或者改用更适合随机访问的数据结构；不要连续调用 UnreadRune，因为第一次成功后内部回退状态已经被清空。

常见问题

UnreadRune 能回退多个中文字符吗？不能。一次成功调用只回退最近一次 ReadRune 读取的一个符文，中文字符占几个字节不改变“一次一个符文”的契约。

ReadRune 之后调用 Buffered 会打断回退吗？不会把它当作新的读取动作；但为了让调用关系清楚，仍建议把 ReadRune 与 UnreadRune 放在同一段小逻辑里，避免中间再加入会改变状态的读取方法。

为什么 UnreadByte 看起来更宽松？官方文档明确区分了两者：UnreadByte 可以回退最近读取操作得到的最后一个字节，而 UnreadRune 要求最近一次方法就是 ReadRune。

总结

ReadRune 成功后记录的是本次 UTF-8 符文的字节长度，UnreadRune 只依据这份短暂状态回退一次。只要把它当成严格的一对接口：紧邻调用、一次回退、错误及时上交，中文字符和无效 UTF-8 都能按明确的字节边界处理；如果需要多次回看，就应把历史数据放到应用层，而不是强行堆叠 UnreadRune。