Go bufio.Scanner 提高超长 token 读取上限

用 bufio.Scanner 按行读日志时，最容易遇到的现象是：短行都能处理，某一行变长后扫描突然结束。通常不是 ScanLines 把换行切错了，而是 token 超过了 Scanner 当前允许的缓冲上限。解决方法是把 Scanner.Buffer 放在第一次 Scan 之前，并同时给出初始缓冲与最大 token 大小。

官方地址：https://pkg.go.dev/bufio

默认上限适合普通文本，不适合没有稳定行长上限的日志、JSON 行或导出记录。先用 Buffer 给出业务可接受的最大字节数，再检查 scanner.Err()；如果还需要分段读取、保留部分结果或更细的错误控制，应换用 bufio.Reader。

先看清 Scanner 的默认上限

Scanner 的默认 split 函数按行产生 token。Go 官方 bufio 文档说明，MaxScanTokenSize 默认值是 64 * 1024，而实际可用的 token 上限可能还要更小，因为缓冲可能需要容纳换行字节。也就是说，不能简单把“64 KB”理解成每一行都一定能放下 64 KB 的正文。

这类问题常出现在一行中嵌入大 JSON、堆栈字段或压缩后的文本时。扫描停止后，继续调用 Scan 也不能恢复；先确认自己的读取目标是“一条完整记录”，再决定是否扩大上限。

把默认上限改成可控的缓冲配置

Buffer(buf, max) 的第二个参数是允许的最大 token 大小，单位是字节。初始缓冲可以先给一个常见值，超过初始容量后 Scanner 才会在不超过 max 的范围内扩展。关键点是：它必须在第一次调用 Scan 前设置。

package main

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

func main() {
    input := strings.NewReader("短行\n一条可能包含较大 JSON 字段的记录\n")
    scanner := bufio.NewScanner(input)

    // 初始缓冲用于普通行，最大值控制单个 token 的硬上限。
    initial := make([]byte, 32*1024)
    scanner.Buffer(initial, 1024*1024)
    scanner.Split(bufio.ScanLines)

    for scanner.Scan() {
        // Text 返回当前 token 的字符串副本，适合交给后续解析。
        line := scanner.Text()
        fmt.Println(line)
    }
    if err := scanner.Err(); err != nil {
        // 超过 max 或底层读取失败，都要从 Err 取得原因。
        fmt.Printf("扫描失败：%v\n", err)
    }
}

这里的 1024*1024 只是示例边界，不是所有项目都应照抄。上限应由单条记录的实际协议约束、内存预算和最坏输入共同决定；把它改成很大的数，并不会让读取无限安全。

把调用时机和错误出口一起迁移

从默认写法迁移到可配置写法时，不只增加一行 Buffer。应把它放在扫描循环之前，并保留 Err 检查。否则超长 token 与底层 I/O 错误都会被同一个“循环结束”现象掩盖。

scanner := bufio.NewScanner(reader)

// Buffer 必须先于第一次 Scan；max 仍然是单个 token 的上限。
scanner.Buffer(make([]byte, 64*1024), 2*1024*1024)

for scanner.Scan() {
    // 只在这里消费完整 token，不把 Scan 的 false 当成正常 EOF。
    consume(scanner.Bytes())
}

// false 可能表示 EOF，也可能表示 token 太长或底层读取失败。
if err := scanner.Err(); err != nil {
    return fmt.Errorf("读取记录失败: %w", err)
}

如果业务允许“跳过一条坏记录后继续”，Scanner 并不能提供这种恢复模型：官方文档明确提示，扫描因 EOF、I/O 错误或 token 过大而停止后不可恢复，底层 reader 也可能已经向前读取了不确定的距离。因此，错误策略要在选型时一起确定。

什么时候应该换成 bufio.Reader

扩大上限适合“记录仍然是完整 token，只是偶尔偏长”的场景。若记录长度没有可靠上限，或者需要保留超长行的片段、逐块处理、在分隔符前后做更细的错误判断，bufio.Reader 更合适。

因此，迁移清单可以压缩成四项：先估算最大单条记录；在第一次 Scan 前调用 Buffer；对 Err 做分支；确认超长输入是否需要恢复。如果最后一项答案是“需要”，不要只把 max 调到更大。

常见问题

Buffer 的 max 是字符数吗？

不是，缓冲按字节计算。中文、emoji 等 UTF-8 文本占用的字节数可能大于字符数，估算上限时要按编码后的字节预算。

可以在 Scan 循环里临时调大 Buffer 吗？

不应这样设计。把 Buffer 放在第一次 Scan 前，才能让本次扫描从一开始就使用明确的上限；循环中遇到超长 token 时已经太晚。

scanner.Scan() 返回 false 就一定是读完了吗？

不一定。正常 EOF 通常让 Err 返回 nil，但超长 token 或底层读取错误需要通过 scanner.Err() 区分。