Go io.ByteScanner 怎样在读取 token 时保留 UnreadByte 能力

在解析类似 alpha=42; 的输入时，我希望第一个阶段只拿到 token alpha，但不要吞掉分隔符 =，这样后面的解析阶段仍能决定它代表赋值还是比较。Go 的 io.ByteScanner 正好提供了一个很窄的工具：先成功调用 ReadByte，发现分隔符后调用一次 UnreadByte，下一次读取就能再次看到这个字节。

官方文档：https://pkg.go.dev/io#ByteScanner

关键限制也同样明确：UnreadByte 只负责回退最近一次成功读取的一个字节。它不是通用的多字节回退栈，不能在 Read、ReadRune 或另一次 UnreadByte 之后随意调用。

先看 ByteScanner 到底增加了什么能力

io.ByteScanner 由 io.ByteReader 和 UnreadByte() error 组成。前者提供 ReadByte，后者让调用方在必要时把刚读出的一个字节交还给流。官方接口描述还特别提醒：如果上一个操作不是成功的 ReadByte，实现可以返回错误。

对于普通的 io.Reader，你一次可能读取一整段字节，读过头后再想退回并不容易。ByteScanner 的取舍是把读取粒度缩小到单字节，把回退能力限制为一个字节。它适合“读到分隔符就停”的小型扫描步骤，而不是完整的编辑器式回退。

遇到分隔符时，把它留给下一个解析阶段

标准库里的 bufio.Reader 实现了 ReadByte 和 UnreadByte，因此可以直接作为扫描器。下面的函数读取连续的普通字符；一旦遇到 =、; 或空格，它先退回这个分隔符，再把 token 返回给调用方。

package main

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

// readToken 读取普通字节，遇到分隔符时把它留给下一阶段。
func readToken(s *bufio.Reader) (string, error) {
    var token []byte
    for {
        b, err := s.ReadByte()
        if err != nil {
            // 输入在 token 结束前耗尽时，保留已经读取到的内容。
            if err == io.EOF && len(token) > 0 {
                return string(token), nil
            }
            return "", err
        }

        if b == '=' || b == ';' || b == ' ' {
            // 当前字节属于下一个语法阶段，只回退这一个字节。
            if err := s.UnreadByte(); err != nil {
                return "", fmt.Errorf("unread delimiter %q: %w", b, err)
            }
            return string(token), nil
        }

        // 普通字符加入 token，继续读取下一个字节。
        token = append(token, b)
    }
}

func main() {
    r := bufio.NewReader(strings.NewReader("alpha=42;"))

    token, err := readToken(r)
    if err != nil {
        panic(err)
    }

    // 回退成功后，下一次 ReadByte 仍然能读到分隔符 '='。
    delimiter, err := r.ReadByte()
    if err != nil {
        panic(err)
    }
    fmt.Printf("token=%q delimiter=%q\n", token, delimiter)
}

这里最重要的不是 append，而是返回前的时序：先成功完成一次 ReadByte，再立即调用 UnreadByte，然后才把控制权交给下一阶段。这个实现只回退分隔符，不会把已经收集好的 token 重新放回缓冲区。

用几个可观察指标判断扫描策略是否合适

对于一个 token 扫描器，可以把结果记录成三个简单指标：token 长度、ReadByte 成功次数和 UnreadByte 次数。以 alpha=42; 为例，第一次扫描得到长度 5 的 alpha，成功读取 6 个字节，其中第 6 个字节是分隔符，并且只发生 1 次回退。这个数字关系能快速发现“循环多读了一次”或“同一分隔符被回退两次”的问题。

这些指标不是为了制造复杂的基准测试，而是为了把接口契约变成可观察的工程事实。尤其是回退次数，正常的“读到一个分隔符再交接”通常应该是一进一退；如果回退次数持续增加，往往说明扫描层和语法层的职责混在了一起。

这几种调用顺序为什么不能混用

UnreadByte 的语义依赖“最近一次成功的 ReadByte”。因此下面三类写法都不应该当成可靠的回退方式：

package main

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

func main() {
    r := bufio.NewReader(strings.NewReader("ab"))

    // 这次 Read 可能一次拿走多个字节，不能用 UnreadByte 回退整段数据。
    buf := make([]byte, 1)
    _, _ = r.Read(buf)
    fmt.Println("after Read, UnreadByte is not a general rollback")

    // 连续调用两次 UnreadByte 不等于连续回退两个字节。
    _, _ = r.ReadByte()
    _ = r.UnreadByte()
    if err := r.UnreadByte(); err != nil {
        // 第二次回退通常会报错，调用方必须处理这个边界。
        fmt.Println("second unread:", err)
    }
}

如果按 rune 处理中文或其它多字节字符，应该让 ReadRune 和 UnreadRune 成对出现。字节级回退只适合语法边界本身就是单字节的格式；把 UTF-8 字符拆成字节后再尝试拼回字符，会让边界判断更难维护。

什么时候应该换成显式缓冲

当语法需要任意长度的 lookahead、多个候选分支，或者一次回退两个以上字节时，继续堆叠 UnreadByte 就不合适了。更稳妥的做法是把已读字节放进一个小的 token 缓冲，或者在更高层保存当前位置和候选片段。

可以用下面的清单做选择：

• 只在单字节分隔符处停下，并把该分隔符交给下一阶段：使用 bufio.Reader 的 ReadByte + UnreadByte。
• 需要按 Unicode 字符回退：使用 ReadRune + UnreadRune，不要混用字节接口。
• 需要多字节回退或任意 lookahead：维护显式缓冲，不把 UnreadByte 当作回退栈。
• 输入边界可能提前结束：把 io.EOF 当作状态处理，并区分“已有 token 的正常结束”和“空 token 的输入耗尽”。

归根到底，io.ByteScanner 的价值在于让一个很小的解析交接动作变得清晰：成功读出一个字节，发现它属于下一阶段，再原样退回一次。只要把“最近一次成功 ReadByte”和“最多一个字节”这两个条件写进代码设计，token 扫描就不会因为误用 UnreadByte 而出现隐蔽的吞分隔符问题。

相关问题

UnreadByte 能连续调用两次吗？通常不能把它当成两级回退。它只对应最近一次成功的 ReadByte，第二次调用应按返回错误处理。

ReadRune 之后能调用 UnreadByte 吗？不应这样设计。按 rune 读取后需要回退字符时，使用 UnreadRune。

bufio.Reader 没有实现 ByteScanner 怎么办？标准库的 bufio.Reader 提供 ReadByte 和 UnreadByte；如果自定义 reader 只有 Read，可以先用它创建一个 bufio.Reader。