bufio - 缓冲 I/O 操作

概述

bufio 包实现了带缓冲的 I/O 操作，通过在内存中维护缓冲区来减少系统调用次数，提高 I/O 性能。

包导入：

import "bufio"

基本使用：

示例 1：使用 Reader 读取一行

// 创建缓冲读取器（从标准输入读取）
reader := bufio.NewReader(os.Stdin)

// 读取一行（直到遇到换行符）
line, err := reader.ReadString('\n')
if err != nil {
    fmt.Println("读取错误:", err)
    return
}

fmt.Println("你输入的是:", line)

示例 2：使用 Writer 写入数据

// 创建缓冲写入器（写入到标准输出）
writer := bufio.NewWriter(os.Stdout)

// 写入数据到缓冲区
writer.WriteString("hello\n")
writer.WriteString("world\n")

// ⚠️ 重要：必须调用 Flush() 将缓冲区数据写入底层
// 忘记 Flush 会导致数据丢失！
err := writer.Flush()
if err != nil {
    fmt.Println("刷新错误:", err)
    return
}

示例 3：使用 Scanner 逐行读取文件

// 打开文件
file, err := os.Open("data.txt")
if err != nil {
    fmt.Println("打开文件失败:", err)
    return
}
defer file.Close() // 确保文件被关闭

// 创建 Scanner
scanner := bufio.NewScanner(file)

// Scan() 返回 true 表示成功读取一行
// 返回 false 表示读取结束或发生错误
for scanner.Scan() {
    // Text() 返回当前行的内容（不包含换行符）
    fmt.Println("读取:", scanner.Text())
}

// 检查是否有错误
if err := scanner.Err(); err != nil {
    fmt.Println("读取文件错误:", err)
}

新手注意事项：

ReadString('\n') - 读取到换行符为止，返回的字符串包含换行符
writer.Flush() - 必须调用，否则数据会丢失
scanner.Scan() - 在循环中使用，返回 false 时结束
scanner.Text() - 获取当前行内容，不包含换行符
scanner.Err() - 循环结束后必须检查是否有错误

典型示例：

示例 1：读取文件并统计行数：

package main

import (
    "bufio"
    "fmt"
    "os"
)

func main() {
    file, err := os.Open("data.txt")
    if err != nil {
        fmt.Println("打开文件失败:", err)
        return
    }
    defer file.Close()

    scanner := bufio.NewScanner(file)
    lines := 0

    for scanner.Scan() {
        lines++
    }

    if err := scanner.Err(); err != nil {
        fmt.Println("读取错误:", err)
        return
    }

    fmt.Printf("总行数：%d\n", lines)
}

运行：

$ go run main.go
总行数：100

示例 2：高性能文件复制：

package main

import (
    "bufio"
    "io"
    "os"
)

func main() {
    src, _ := os.Open("source.txt")
    defer src.Close()

    dst, _ := os.Create("dest.txt")
    defer dst.Close()

    // 使用缓冲提高性能
    reader := bufio.NewReader(src)
    writer := bufio.NewWriter(dst)

    io.Copy(writer, reader)
    writer.Flush() // 必须刷新缓冲区
}

示例 3：自定义 Scanner 分词规则（CSV 解析）：

package main

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

func main() {
	data := "apple,banana,cherry,date"

	commaSplit := func(data []byte, atEOF bool) (advance int, token []byte, err error) {
		// 1. 先处理输入结束且无剩余数据的情况（最重要的修复！）
		if atEOF && len(data) == 0 {
			return 0, nil, nil // 正确终止
		}

		// 2. 查找逗号分隔符
		for i := 0; i < len(data); i++ {
			if data[i] == ',' {
				return i + 1, data[:i], nil
			}
		}
        
        /* 同上，不需要for循环，由index处理。可处理字节串
        if i := bytes.Index(data, []byte(",")); i >= 0 {
			return i + 1, data[:i], nil
		}   
		*/

		// 3. 如果已经到达流的末尾，返回剩下的所有数据（此时 data 非空）
		if atEOF {
			return len(data), data, nil
		}

		// 4. 还没到结尾，也没有找到逗号，需要更多数据
		return 0, nil, nil
	}

	scanner := bufio.NewScanner(strings.NewReader(data))
	scanner.Split(commaSplit)

	for scanner.Scan() {
		fmt.Println(scanner.Text())
	}
	if err := scanner.Err(); err != nil {
		fmt.Println("扫描错误:", err)
	}
}

运行：

$ go run main.go
apple
banana
cherry
date

一、错误变量

缓冲区已满错误

ErrBufferFull

说明：

当缓冲区无法容纳更多数据时返回
常见于 ReadSlice、ReadLine 方法
可通过增大缓冲区或使用 ReadBytes 解决

定义：

var ErrBufferFull = errors.New("bufio: buffer full")

示例：

package main

import (
    "bufio"
    "fmt"
    "os"
)

func main() {
    // 创建小缓冲区
    r := bufio.NewReaderSize(os.Stdin, 4)

    line, err := r.ReadSlice('\n')
    if err == bufio.ErrBufferFull {
        fmt.Println("缓冲区已满，请增大缓冲区或使用 ReadBytes")
    }

    _ = line
}

运行：

$ echo "hello world" | go run main.go
缓冲区已满，请增大缓冲区或使用 ReadBytes

Token 超长错误

ErrTooLong

说明：

Scanner 读取的 token 超过最大限制时返回
默认限制为 MaxScanTokenSize（64KB）
可通过 Scanner.Buffer() 方法扩大限制

定义：

var ErrTooLong = errors.New("bufio: token too long")

示例：

package main

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

func main() {
    // 构造超长字符串（100KB）
    data := strings.Repeat("a", 100000)

    scanner := bufio.NewScanner(strings.NewReader(data))

    for scanner.Scan() {
        fmt.Println("读取:", len(scanner.Text()))
    }

    if err := scanner.Err(); err == bufio.ErrTooLong {
        fmt.Println("错误：token 太长")
    }
}

运行：

$ go run main.go
错误：token 太长

解决方案：

scanner := bufio.NewScanner(reader)
buf := make([]byte, 0, 64*1024)
scanner.Buffer(buf, 1024*1024) // 扩大到 1MB

Advance 超出范围错误

ErrAdvanceTooFar

说明：

Scanner 的分词函数返回的 advance 值超出数据范围
通常由自定义 SplitFunc 实现错误导致

定义：

var ErrAdvanceTooFar = errors.New("bufio: advance too far")

示例：

// 错误的 SplitFunc 实现
badSplit := func(data []byte, atEOF bool) (int, []byte, error) {
    // advance 超出了数据长度
    return len(data) + 10, data, nil
}

scanner.Split(badSplit)
// 会触发 ErrAdvanceTooFar 错误

读取计数异常错误

ErrBadReadCount

说明：

内部读取计数出现异常
较少见，通常表示底层 Reader 实现有问题

定义：

var ErrBadReadCount = errors.New("bufio: bad read count")

非法 UnreadByte 错误

ErrInvalidUnreadByte

说明：

在未读取任何字节时调用 UnreadByte()
或连续调用多次 UnreadByte()

定义：

var ErrInvalidUnreadByte = errors.New("bufio: invalid use of UnreadByte")

示例：

r := bufio.NewReader(strings.NewReader("hello"))

// 未读取就回退
err := r.UnreadByte()
if err == bufio.ErrInvalidUnreadByte {
    fmt.Println("错误：未读取不能回退")
}

非法 UnreadRune 错误

ErrInvalidUnreadRune

说明：

在未读取任何 rune 时调用 UnreadRune()
或连续调用多次 UnreadRune()

定义：

var ErrInvalidUnreadRune = errors.New("bufio: invalid use of UnreadRune")

Advance 为负数错误

ErrNegativeAdvance

说明：

Scanner 的分词函数返回负的 advance 值
由自定义 SplitFunc 实现错误导致

定义：

var ErrNegativeAdvance = errors.New("bufio: negative advance")

读取计数为负数错误

ErrNegativeCount

说明：

内部读取返回负数的字节计数
表示底层 Reader 实现有严重错误

定义：

var ErrNegativeCount = errors.New("bufio: negative count")

Scanner 分词结束标记

ErrFinalToken

说明：

特殊的错误标记，用于自定义 SplitFunc
表示这是最后一个 token
不会导致 Scanner 报错

定义：

var ErrFinalToken = errors.New("bufio: final token")

示例：

// 自定义 SplitFunc 返回最后一个 token
split := func(data []byte, atEOF bool) (int, []byte, error) {
    if atEOF && len(data) == 0 {
        return 0, nil, bufio.ErrFinalToken
    }
    // ... 正常分词逻辑
    return advance, token, nil
}

二、常量

Scanner 默认最大 Token 大小

MaxScanTokenSize

说明：

Scanner 默认的 token 最大限制
值为 64 * 1024（64KB）
超过此限制会返回 ErrTooLong 错误
可通过 Scanner.Buffer() 方法调整

定义：

const MaxScanTokenSize = 64 * 1024

示例：

package main

import (
    "bufio"
    "fmt"
)

func main() {
    fmt.Println("默认最大 token 大小:", bufio.MaxScanTokenSize)
    // 输出：65536
}

扩大限制：

scanner := bufio.NewScanner(reader)
buf := make([]byte, 0, 64*1024)
scanner.Buffer(buf, 1024*1024) // 扩大到 1MB

说明： Split 方法用于设置自定义的分词函数，改变 Scanner 默认的按行分割行为。通过提供自定义的 SplitFunc，可以实现按单词分割、按字符分割、或者按照特定格式（如 CSV、JSON）解析数据。这个方法必须在第一次调用 Scan() 之前设置，否则会影响已经读取的数据。bufio 包提供了四个内置的分词函数：ScanLines（按行）、ScanWords（按单词）、ScanBytes（按字节）、ScanRunes（按字符）。

典型使用场景：

按单词分割文本进行词频统计（使用 ScanWords）
自定义分词规则解析 CSV 或 JSON 数据
实现特定格式的文本解析器
处理特殊数据格式（如固定宽度字段）

// 按单词分割
scanner := bufio.NewScanner(strings.NewReader("go is fun"))
scanner.Split(bufio.ScanWords)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：go, is, fun

6. Buffer - 设置缓冲区大小

说明： Buffer 方法用于设置 Scanner 的缓冲区和最大 token 大小。默认最大 token 为 64KB（MaxScanTokenSize），当读取的单行数据超过此限制时会返回 ErrTooLong 错误。通过此方法可以扩大限制，处理包含超长行的文件（如大型日志文件、数据库导出文件）。第一个参数是初始缓冲区切片，第二个参数是最大 token 大小。这个方法必须在第一次调用 Scan() 之前设置。

典型使用场景：

读取包含超长行的日志文件（超过 64KB）
处理大型数据库导出文件
避免 Token 太长错误导致读取失败
处理特殊格式的长数据行（如 Base64 编码数据）

scanner := bufio.NewScanner(file)

// 扩大缓冲区到 1MB
buf := make([]byte, 0, 64*1024)
scanner.Buffer(buf, 1024*1024)

for scanner.Scan() {
    line := scanner.Text()
    // 处理超长行...
}

使用场景：

1. 逐行读取文件

file, _ := os.Open("data.txt")
defer file.Close()

scanner := bufio.NewScanner(file)
lineNum := 0

for scanner.Scan() {
    lineNum++
    fmt.Printf("第%d行：%s\n", lineNum, scanner.Text())
}

if err := scanner.Err(); err != nil {
    fmt.Println("读取失败:", err)
}

2. 按单词分割

scanner := bufio.NewScanner(strings.NewReader("go is awesome"))
scanner.Split(bufio.ScanWords)

for scanner.Scan() {
    fmt.Println("单词:", scanner.Text())
}

3. 统计行数

scanner := bufio.NewScanner(file)
lines := 0

for scanner.Scan() {
    lines++
}

if err := scanner.Err(); err != nil {
    fmt.Println("读取失败:", err)
    return
}

fmt.Println("总行数:", lines)

4. 保存所有行

scanner := bufio.NewScanner(file)
var allLines []string

for scanner.Scan() {
    // Text() 返回的字符串已复制，可以安全保存
    allLines = append(allLines, scanner.Text())
}

注意事项：

❌ 忘记检查错误：

for scanner.Scan() {
    process(scanner.Text())
}
// 忘记检查 Err()！

✅ 正确做法：

for scanner.Scan() {
    process(scanner.Text())
}
if err := scanner.Err(); err != nil {
    fmt.Println("错误:", err)
}

⚠️ Token 长度限制：

默认最大 64KB（MaxScanTokenSize）
超过会返回 ErrTooLong 错误
使用 Buffer() 方法扩大限制

NewReadWriter - 创建读写组合

说明：

将 Reader 和 Writer 组合成 ReadWriter
同时提供读取和写入功能
适合需要双向通信的场景（如网络连接）

定义：

func NewReadWriter(r *Reader, w *Writer) *ReadWriter

示例：

r := bufio.NewReader(os.Stdin)
w := bufio.NewWriter(os.Stdout)

rw := bufio.NewReadWriter(r, w)

fmt.Print("输入内容：")
line, _ := rw.ReadString('\n')

rw.WriteString("你输入的是：" + line)
rw.Flush()

运行：

$ go run main.go
输入内容：hello
你输入的是：hello

使用场景：

// 网络连接中的双向通信
conn, _ := net.Dial("tcp", "localhost:8080")

rw := bufio.NewReadWriter(
    bufio.NewReader(conn),
    bufio.NewWriter(conn),
)

// 发送请求
rw.WriteString("GET / HTTP/1.1\r\n")
rw.Flush()

// 读取响应
response, _ := rw.ReadString('\n')
fmt.Println(response)

四、核心类型

缓冲读取器

Reader

定义：

type Reader struct {
    // 内部字段，不应直接访问
}

说明：

实现了 io.Reader、io.WriterTo、io.ByteReader、io.ByteScanner、io.RuneReader、io.RuneScanner 接口
内部维护缓冲区，减少系统调用
适合读取大量小数据块的场景

主要方法详解：

Read 方法

定义：

func (b *Reader) Read(p []byte) (n int, err error)

说明：

从底层读取器读取数据到缓冲区，再返回给调用者
优先从缓冲区返回数据，缓冲区空时才从底层读取
返回读取的字节数和可能的错误

示例：

r := bufio.NewReader(strings.NewReader("hello world"))
buf := make([]byte, 5)

n, err := r.Read(buf)
if err != nil {
    fmt.Println("读取错误:", err)
    return
}

fmt.Printf("读取了 %d 字节：%s\n", n, string(buf))
// 输出：读取了 5 字节：hello

ReadString 方法

定义：

func (b *Reader) ReadString(delim byte) (string, error)

说明：

读取数据直到第一次出现 delim 字节
返回的字符串包含 delim
常用于读取一行（delim = ‘\n’）

示例：

r := bufio.NewReader(strings.NewReader("line1\nline2\nline3"))

line1, _ := r.ReadString('\n')
line2, _ := r.ReadString('\n')

fmt.Println(line1) // line1\n
fmt.Println(line2) // line2\n

ReadBytes 方法

定义：

func (b *Reader) ReadBytes(delim byte) ([]byte, error)

说明：

类似 ReadString，但返回 []byte
避免不必要的字符串转换时使用
返回的字节切片包含 delim

示例：

r := bufio.NewReader(strings.NewReader("hello\nworld"))

data, _ := r.ReadBytes('\n')
fmt.Printf("读取：%s", data) // hello\n

// 转换为字符串（如果需要）
str := string(data)

ReadByte 方法

定义：

func (b *Reader) ReadByte() (byte, error)

说明：

读取并返回下一个字节
比 Read 更高效（针对单字节）
返回单个字节和可能的错误

示例：

r := bufio.NewReader(strings.NewReader("ABC"))

b1, _ := r.ReadByte()
b2, _ := r.ReadByte()
b3, _ := r.ReadByte()

fmt.Printf("%c %c %c\n", b1, b2, b3)
// 输出：A B C

ReadRune 方法

定义：

func (b *Reader) ReadRune() (r rune, size int, err error)

说明：

读取并返回下一个 rune（Unicode 字符）
自动处理 UTF-8 解码
返回 rune、占用的字节数、错误

示例：

r := bufio.NewReader(strings.NewReader("你好 Go"))

ch1, size1, _ := r.ReadRune()
ch2, size2, _ := r.ReadRune()
ch3, size3, _ := r.ReadRune()

fmt.Printf("%c (%d 字节)\n", ch1, size1) // 你 (3 字节)
fmt.Printf("%c (%d 字节)\n", ch2, size2) // 好 (3 字节)
fmt.Printf("%c (%d 字节)\n", ch3, size3) // G (1 字节)

Peek 方法

定义：

func (b *Reader) Peek(n int) ([]byte, error)

说明：

查看接下来的 n 个字节（不移动读取位置）
返回的字节切片在下一次读取时会失效
常用于预读协议头、魔数等

示例：

r := bufio.NewReader(strings.NewReader("HTTP/1.1 200 OK"))

// 查看前 4 字节判断协议
header, _ := r.Peek(4)
if string(header) == "HTTP" {
    fmt.Println("这是 HTTP 协议")
}

// 继续读取，仍然从开头开始
full, _ := r.ReadString(' ')
fmt.Println(full) // HTTP/1.1

Discard 方法

定义：

func (b *Reader) Discard(n int) (int, error)

说明：

跳过并丢弃 n 个字节
用于跳过不需要的数据（如文件头）
返回实际丢弃的字节数

示例：

// 假设文件前 128 字节是文件头
file, _ := os.Open("data.bin")
defer file.Close()

r := bufio.NewReader(file)

// 跳过文件头
discarded, _ := r.Discard(128)
fmt.Printf("跳过了 %d 字节\n", discarded)

// 读取实际数据
data, _ := io.ReadAll(r)

UnreadByte 方法

定义：

func (b *Reader) UnreadByte() error

说明：

回退一个字节（下次读取会再次返回该字节）
只能回退最近读取的一个字节
连续调用会返回错误

示例：

r := bufio.NewReader(strings.NewReader("12345"))

b1, _ := r.ReadByte()
fmt.Printf("%c\n", b1) // 1

// 回退
err := r.UnreadByte()
if err != nil {
    fmt.Println("回退失败:", err)
}

// 再次读取，仍然是 '1'
b2, _ := r.ReadByte()
fmt.Printf("%c\n", b2) // 1

UnreadRune 方法

定义：

func (b *Reader) UnreadRune() error

说明：

回退一个 rune（下次读取会再次返回该 rune）
只能回退最近读取的一个 rune
连续调用会返回错误

示例：

r := bufio.NewReader(strings.NewReader("你好"))

rune1, size, _ := r.ReadRune()
fmt.Printf("%c (%d 字节)\n", rune1, size) // 你 (3 字节)

// 回退
r.UnreadRune()

// 再次读取，仍然是 '你'
rune2, _, _ := r.ReadRune()
fmt.Printf("%c\n", rune2) // 你

Buffered 方法

定义：

func (b *Reader) Buffered() int

说明：

返回缓冲区中可读的字节数
用于检查还有多少数据可以立即读取

示例：

r := bufio.NewReader(strings.NewReader("hello world"))

// 先读取一些数据
r.ReadString(' ')

// 检查缓冲区还有多少数据
n := r.Buffered()
fmt.Println("缓冲区可读字节数:", n)

Reset 方法

定义：

func (b *Reader) Reset(rd io.Reader)

说明：

重置为读取新的 io.Reader
复用 Reader，避免重新分配
适合需要重复使用 Reader 的场景

示例：

// 创建一次
r := bufio.NewReader(nil)

// 多次复用
files := []string{"file1.txt", "file2.txt", "file3.txt"}
for _, filename := range files {
    f, _ := os.Open(filename)
    r.Reset(f)
    
    // 使用 r 读取文件...
    line, _ := r.ReadString('\n')
    fmt.Println(line)
    
    f.Close()
}

WriteTo 方法

定义：

func (b *Reader) WriteTo(w io.Writer) (n int64, err error)

说明：

将 Reader 中的所有数据写入到 w
返回写入的字节数和错误
实现了 io.WriterTo 接口

示例：

r := bufio.NewReader(strings.NewReader("hello world"))

// 直接写入到标准输出
n, _ := r.WriteTo(os.Stdout)
fmt.Printf("\n写入了 %d 字节\n", n)
// 输出：hello world
//       写入了 11 字节

综合示例：

r := bufio.NewReader(strings.NewReader("hello\nworld\n"))

line1, _ := r.ReadString('\n')
line2, _ := r.ReadString('\n')

fmt.Println(line1) // hello\n
fmt.Println(line2) // world\n

示例 2：Peek 预读：

r := bufio.NewReader(strings.NewReader("HTTP/1.1 200 OK"))

// 查看前 4 字节判断协议
header, _ := r.Peek(4)
if string(header) == "HTTP" {
    fmt.Println("HTTP 协议")
}

// 继续读取，仍然从开头开始
full, _ := r.ReadString(' ')
fmt.Println(full) // HTTP/1.1

示例 3：跳过文件头：

file, _ := os.Open("data.bin")
defer file.Close()

r := bufio.NewReader(file)

// 跳过 128 字节的文件头
r.Discard(128)

// 读取实际数据
data, _ := io.ReadAll(r)

示例 4：字节回退：

r := bufio.NewReader(strings.NewReader("12345"))

b1, _ := r.ReadByte()
fmt.Printf("%c\n", b1) // 1

// 回退
r.UnreadByte()

// 再次读取，仍然是 '1'
b2, _ := r.ReadByte()
fmt.Printf("%c\n", b2) // 1

示例 5：复用 Reader：

// 创建一次
r := bufio.NewReader(nil)

// 多次复用
for _, file := range files {
    f, _ := os.Open(file)
    r.Reset(f)
    
    // 使用 r 读取...
    f.Close()
}

缓冲写入器

Writer

定义：

type Writer struct {
    // 内部字段，不应直接访问
}

说明：

实现了 io.Writer、io.ByteWriter、io.StringWriter、io.RuneWriter、io.WriterTo 接口
内部维护缓冲区，减少系统调用
必须调用 Flush() 才能将数据写入底层

主要方法详解：

Write 方法

定义：

func (b *Writer) Write(p []byte) (n int, err error)

说明：

写入字节切片到缓冲区
缓冲区满时会自动 Flush 到底层
返回写入的字节数和错误

示例：

w := bufio.NewWriter(os.Stdout)

data := []byte("hello world")
n, err := w.Write(data)
if err != nil {
    fmt.Println("写入错误:", err)
    return
}

fmt.Printf("写入了 %d 字节\n", n)
w.Flush()

WriteString 方法

定义：

func (b *Writer) WriteString(s string) (n int, err error)

说明：

写入字符串到缓冲区
比 Write([]byte(s)) 更高效（避免内存分配）
返回写入的字节数和错误

示例：

w := bufio.NewWriter(os.Stdout)

w.WriteString("hello\n")
w.WriteString("world\n")

w.Flush()

WriteByte 方法

定义：

func (b *Writer) WriteByte(c byte) error

说明：

写入单个字节到缓冲区
最高效的写入方式（无内存分配）
只返回错误

示例：

w := bufio.NewWriter(os.Stdout)

// 逐字节写入
w.WriteByte('H')
w.WriteByte('e')
w.WriteByte('l')
w.WriteByte('l')
w.WriteByte('o')
w.WriteByte('\n')

w.Flush()

WriteRune 方法

定义：

func (b *Writer) WriteRune(r rune) (n int, err error)

说明：

写入单个 rune（Unicode 字符）到缓冲区
自动进行 UTF-8 编码
返回写入的字节数和错误

示例：

w := bufio.NewWriter(os.Stdout)

// 写入中文字符
w.WriteRune('你')
w.WriteRune('好')
w.WriteRune('，')
w.WriteRune('世')
w.WriteRune('界')
w.WriteRune('！')
w.WriteRune('\n')

w.Flush()
// 输出：你好，世界！

Flush 方法

定义：

func (b *Writer) Flush() error

说明：

将缓冲区所有数据写入底层 io.Writer
必须调用，否则数据可能丢失
应该在 defer 中调用确保刷新
可以多次调用（幂等）

示例：

file, _ := os.Create("output.txt")
defer file.Close()

w := bufio.NewWriter(file)
defer w.Flush() // 确保刷新

w.WriteString("重要数据\n")
// 程序退出前会自动 Flush

Buffered 方法

定义：

func (b *Writer) Buffered() int

说明：

返回缓冲区中已写入但未刷新的字节数
用于检查还有多少数据等待刷新

示例：

w := bufio.NewWriterSize(os.Stdout, 1024)

w.WriteString("hello")
w.WriteString("world")

n := w.Buffered()
fmt.Printf("已缓冲：%d 字节\n", n) // 已缓冲：10 字节

w.Flush()
fmt.Printf("已缓冲：%d 字节\n", w.Buffered()) // 已缓冲：0 字节

Available 方法

定义：

func (b *Writer) Available() int

说明：

返回缓冲区可用空间
等于 Size() - Buffered()

示例：

w := bufio.NewWriterSize(os.Stdout, 1024)

avail := w.Available()
fmt.Printf("可用空间：%d\n", avail) // 1024

w.WriteString("hello")
avail = w.Available()
fmt.Printf("可用空间：%d\n", avail) // 1019

AvailableBuffer 方法

定义：

func (b *Writer) AvailableBuffer() []byte

说明：

返回可用的缓冲区切片
直接写入该切片不会更新 Writer 状态
用于需要直接操作缓冲区的场景

示例：

w := bufio.NewWriterSize(os.Stdout, 1024)

// 获取可用缓冲区
buf := w.AvailableBuffer()
fmt.Printf("缓冲区大小：%d\n", len(buf))

// 注意：直接写入 buf 不会更新 w 的状态
// 应该使用 w.Write() 或 w.WriteString()

Size 方法

定义：

func (b *Writer) Size() int

说明：

返回缓冲区大小
创建时确定，不可更改

示例：

w1 := bufio.NewWriter(os.Stdout)
fmt.Println("默认大小:", w1.Size()) // 4096

w2 := bufio.NewWriterSize(os.Stdout, 8192)
fmt.Println("自定义大小:", w2.Size()) // 8192

Reset 方法

定义：

func (b *Writer) Reset(wr io.Writer)

说明：

重置为写入新的 io.Writer
复用 Writer，避免重新分配
适合需要重复使用 Writer 的场景

示例：

// 创建一次
w := bufio.NewWriter(nil)

// 多次复用
files := []string{"out1.txt", "out2.txt", "out3.txt"}
for _, filename := range files {
    f, _ := os.Create(filename)
    w.Reset(f)
    
    w.WriteString("内容\n")
    w.Flush()
    
    f.Close()
}

ReadFrom 方法

定义：

func (b *Writer) ReadFrom(r io.Reader) (n int64, err error)

说明：

从 r 读取所有数据并写入缓冲区
实现了 io.ReaderFrom 接口
返回读取的字节数和错误

示例：

// 从文件读取并写入到标准输出
file, _ := os.Open("input.txt")
defer file.Close()

w := bufio.NewWriter(os.Stdout)
defer w.Flush()

n, _ := w.ReadFrom(file)
fmt.Printf("复制了 %d 字节\n", n)

综合示例：

file, _ := os.Create("output.txt")
defer file.Close()

w := bufio.NewWriter(file)
defer w.Flush()

w.WriteString("hello world\n")
w.WriteByte('A')
w.WriteRune('中')

示例 2：高性能批量写入：

file, _ := os.Create("data.txt")
defer file.Close()

w := bufio.NewWriter(file)
defer w.Flush()

// 1000 次小写入合并为几次系统调用
for i := 0; i < 1000; i++ {
    w.WriteString(fmt.Sprintf("line %d\n", i))
}
// 最后一次性刷新

示例 3：网络传输优化：

conn, _ := net.Dial("tcp", "localhost:8080")
defer conn.Close()

w := bufio.NewWriter(conn)
defer w.Flush()

// 多次小写入合并为一次网络发送
w.WriteString("GET / HTTP/1.1\r\n")
w.WriteString("Host: localhost\r\n")
w.WriteString("\r\n")

示例 4：构建大字符串：

var buf strings.Builder
w := bufio.NewWriter(&buf)

for i := 0; i < 10000; i++ {
    w.WriteString(fmt.Sprintf("%d,", i))
}

w.Flush()
result := buf.String()

示例 5：检查缓冲区状态：

w := bufio.NewWriterSize(os.Stdout, 4096)

w.WriteString("hello")

fmt.Println("缓冲区大小:", w.Size())      // 4096
fmt.Println("已缓冲:", w.Buffered())      // 5
fmt.Println("可用空间:", w.Available())  // 4091

示例 6：复用 Writer：

// 创建一次
w := bufio.NewWriter(nil)

// 多次复用
for _, file := range outputFiles {
    f, _ := os.Create(file)
    w.Reset(f)
    
    // 使用 w 写入...
    w.Flush()
    f.Close()
}

注意事项：

❌ 忘记 Flush：

w := bufio.NewWriter(file)
w.WriteString("data")
// 数据丢失！

✅ 正确的 defer 用法：

w := bufio.NewWriter(file)
defer w.Flush() // 确保刷新

❌ 频繁 Flush 影响性能：

for i := 0; i < 1000; i++ {
    w.WriteString("line\n")
    w.Flush() // 每次都刷新，性能差
}

✅ 批量刷新：

for i := 0; i < 1000; i++ {
    w.WriteString("line\n")
}
w.Flush() // 最后一次性刷新

扫描器

Scanner

定义：

type Scanner struct {
    // 内部字段，不应直接访问
}

说明：

用于逐 token 读取文本
内部维护缓冲区，自动处理分词
适合简单的文本解析场景
不适合复杂解析（应使用 encoding/json 等专用包）

主要方法详解：

Scan 方法

定义：

func (s *Scanner) Scan() bool

说明：

读取下一个 token
返回 true 表示成功读取
返回 false 表示结束或错误
必须在循环中使用

示例：

scanner := bufio.NewScanner(strings.NewReader("line1\nline2\nline3"))

// 标准用法
for scanner.Scan() {
    // 成功读取一行
    fmt.Println(scanner.Text())
}
// Scan() 返回 false，循环结束

Text 方法

定义：

func (s *Scanner) Text() string

说明：

返回当前 token 的字符串
必须在 Scan() 返回 true 后调用
返回的字符串在下一次 Scan() 后会失效
需要长期保存时应复制到切片

示例：

scanner := bufio.NewScanner(strings.NewReader("hello\nworld"))

if scanner.Scan() {
    text := scanner.Text()
    fmt.Println("第一行:", text) // hello
}

if scanner.Scan() {
    text := scanner.Text()
    fmt.Println("第二行:", text) // world
}

Bytes 方法

定义：

func (s *Scanner) Bytes() []byte

说明：

返回当前 token 的字节切片
类似 Text()，但返回 []byte
避免字符串转换时使用
返回的切片在下一次 Scan() 后会失效

示例：

scanner := bufio.NewScanner(strings.NewReader("hello\nworld"))

for scanner.Scan() {
    data := scanner.Bytes()
    // 直接处理字节切片，避免转换
    fmt.Printf("读取：%s\n", data)
}

Err 方法

定义：

func (s *Scanner) Err() error

说明：

返回读取过程中的错误
循环结束后必须检查
可以区分正常结束和错误
如果返回 nil 表示正常结束

示例：

scanner := bufio.NewScanner(file)

for scanner.Scan() {
    process(scanner.Text())
}

// 必须检查错误
if err := scanner.Err(); err != nil {
    fmt.Println("读取错误:", err)
    return
}

fmt.Println("读取完成")

Split 方法

定义：

func (s *Scanner) Split(split SplitFunc)

说明：

设置分词函数
默认使用 ScanLines（按行分割）
可以自定义分词规则
必须在 Scan() 之前调用

示例：

// 按单词分割
scanner := bufio.NewScanner(strings.NewReader("go is fun"))
scanner.Split(bufio.ScanWords)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：go, is, fun

Buffer 方法

定义：

func (s *Scanner) Buffer(buf []byte, max int)

说明：

设置缓冲区和最大 token 大小
默认最大 64KB（MaxScanTokenSize）
读取超长行时必须扩大
必须在 Scan() 之前调用

示例：

scanner := bufio.NewScanner(file)

// 扩大缓冲区到 1MB
buf := make([]byte, 0, 64*1024)
scanner.Buffer(buf, 1024*1024)

for scanner.Scan() {
    line := scanner.Text()
    // 处理超长行...
}

综合示例：

file, _ := os.Open("data.txt")
defer file.Close()

scanner := bufio.NewScanner(file)

for scanner.Scan() {
    line := scanner.Text()
    fmt.Println(line)
}

if err := scanner.Err(); err != nil {
    fmt.Println("读取错误:", err)
}

示例 2：按单词分割：

scanner := bufio.NewScanner(strings.NewReader("go is awesome"))
scanner.Split(bufio.ScanWords)

for scanner.Scan() {
    fmt.Println("单词:", scanner.Text())
}
// 输出：
// 单词：go
// 单词：is
// 单词：awesome

示例 3：按字符分割：

scanner := bufio.NewScanner(strings.NewReader("你好"))
scanner.Split(bufio.ScanRunes)

for scanner.Scan() {
    fmt.Println("字符:", scanner.Text())
}
// 输出：
// 字符：你
// 字符：好

示例 4：读取超长行：

file, _ := os.Open("large.txt")
defer file.Close()

scanner := bufio.NewScanner(file)

// 扩大缓冲区到 1MB
buf := make([]byte, 0, 64*1024)
scanner.Buffer(buf, 1024*1024)

for scanner.Scan() {
    line := scanner.Text()
    // 处理超长行...
}

示例 5：自定义分词（CSV 解析）：

data := "apple,banana,cherry"

// 自定义分词函数
commaSplit := func(data []byte, atEOF bool) (int, []byte, error) {
    for i := 0; i < len(data); i++ {
        if data[i] == ',' {
            return i + 1, data[:i], nil
        }
    }
    if atEOF {
        return len(data), data, nil
    }
    return 0, nil, nil
}

scanner := bufio.NewScanner(strings.NewReader(data))
scanner.Split(commaSplit)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：apple, banana, cherry

示例 6：统计行数：

file, _ := os.Open("data.txt")
defer file.Close()

scanner := bufio.NewScanner(file)
lines := 0

for scanner.Scan() {
    lines++
}

if err := scanner.Err(); err != nil {
    fmt.Println("读取失败:", err)
    return
}

fmt.Println("总行数:", lines)

示例 7：保存所有行：

scanner := bufio.NewScanner(file)
var allLines []string

for scanner.Scan() {
    // Text() 返回的字符串已复制，可以安全保存
    allLines = append(allLines, scanner.Text())
}

注意事项：

❌ 忘记检查错误：

for scanner.Scan() {
    process(scanner.Text())
}
// 忘记检查 Err()！

✅ 正确做法：

for scanner.Scan() {
    process(scanner.Text())
}
if err := scanner.Err(); err != nil {
    fmt.Println("错误:", err)
}

⚠️ Token 长度限制：

默认最大 64KB（MaxScanTokenSize）
超过会返回 ErrTooLong 错误
使用 Buffer() 方法扩大限制

⚠️ Text() 返回值生命周期：

Text() 返回的字符串在下一次 Scan() 后会失效
需要长期保存时应复制到切片或变量

读写组合器

ReadWriter

定义：

type ReadWriter struct {
    *Reader
    *Writer
}

说明：

组合了 *Reader 和 *Writer
同时提供读取和写入功能
适合需要双向通信的场景

主要方法：

继承 Reader 的所有方法（Read、ReadString 等）
继承 Writer 的所有方法（Write、WriteString、Flush 等）

示例：

package main

import (
    "bufio"
    "fmt"
    "os"
)

func main() {
    rw := bufio.NewReadWriter(
        bufio.NewReader(os.Stdin),
        bufio.NewWriter(os.Stdout),
    )

    fmt.Print("输入：")
    text, _ := rw.ReadString('\n')

    rw.WriteString("输出：" + text)
    rw.Flush()
}

五、分词函数类型

Scanner 分词函数

SplitFunc

定义：

type SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error)

参数说明：

data []byte：当前缓冲区的数据
atEOF bool：是否已到达输入末尾
advance int：已处理的字节数（下次读取从此位置开始）
token []byte：返回的 token
err error：错误（可使用 ErrFinalToken 表示结束）

内置分词函数：

函数	说明	示例
`ScanLines`	按行分割（默认）	`scanner.Split(ScanLines)`
`ScanWords`	按单词分割	`scanner.Split(ScanWords)`
`ScanBytes`	按字节分割	`scanner.Split(ScanBytes)`
`ScanRunes`	按 rune 分割	`scanner.Split(ScanRunes)`

示例 1：ScanLines（默认）：

scanner := bufio.NewScanner(strings.NewReader("line1\nline2\nline3"))
// 默认使用 ScanLines

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：line1, line2, line3

示例 2：ScanWords：

scanner := bufio.NewScanner(strings.NewReader("go is fun"))
scanner.Split(bufio.ScanWords)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：go, is, fun

示例 3：ScanBytes：

scanner := bufio.NewScanner(strings.NewReader("abc"))
scanner.Split(bufio.ScanBytes)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：a, b, c

示例 4：ScanRunes：

scanner := bufio.NewScanner(strings.NewReader("你好"))
scanner.Split(bufio.ScanRunes)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：你，好

示例 5：自定义分词（按逗号分割）：

data := "a,b,c,d"

commaSplit := func(data []byte, atEOF bool) (int, []byte, error) {
    for i := 0; i < len(data); i++ {
        if data[i] == ',' {
            return i + 1, data[:i], nil
        }
    }
    if atEOF {
        return len(data), data, nil
    }
    return 0, nil, nil
}

scanner := bufio.NewScanner(strings.NewReader(data))
scanner.Split(commaSplit)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：a, b, c, d

示例 6：自定义分词（固定长度）：

// 每次读取 4 个字节
fixedSplit := func(data []byte, atEOF bool) (int, []byte, error) {
    if len(data) >= 4 {
        return 4, data[:4], nil
    }
    if atEOF {
        return len(data), data, nil
    }
    return 0, nil, nil
}

scanner := bufio.NewScanner(strings.NewReader("0123456789"))
scanner.Split(fixedSplit)

for scanner.Scan() {
    fmt.Println(scanner.Text())
}
// 输出：0123, 4567, 89

实现 SplitFunc 的规则：

返回 0, nil, nil：表示需要更多数据
返回 advance, token, nil：表示成功分词
返回 advance, token, err：表示错误（包括 ErrFinalToken）
advance 不能为负数
advance 不能超出 data 长度

六、快速参考

错误变量

错误	说明
`ErrBufferFull`	缓冲区已满
`ErrTooLong`	Token 超长
`ErrInvalidUnreadByte`	非法的 UnreadByte
`ErrInvalidUnreadRune`	非法的 UnreadRune
`ErrAdvanceTooFar`	Advance 超出范围
`ErrNegativeAdvance`	Advance 为负数
`ErrNegativeCount`	读取计数为负数
`ErrBadReadCount`	读取计数异常
`ErrFinalToken`	Scanner 分词结束标记

构造函数

函数	说明
`NewReader(rd)`	创建默认缓冲 Reader
`NewReaderSize(rd, size)`	创建指定大小 Reader
`NewWriter(wr)`	创建默认缓冲 Writer
`NewWriterSize(wr, size)`	创建指定大小 Writer
`NewScanner(r)`	创建 Scanner
`NewReadWriter(r, w)`	创建读写组合

核心类型

类型	说明
`Reader`	缓冲读取器
`Writer`	缓冲写入器（必须 Flush）
`Scanner`	逐 token 读取器
`ReadWriter`	读写组合器

分词函数

函数	说明
`ScanLines`	按行分割（默认）
`ScanWords`	按单词分割
`ScanBytes`	按字节分割
`ScanRunes`	按 rune 分割

常量

常量	值	说明
`MaxScanTokenSize`	65536	Scanner 默认最大 token 大小

最后更新：2026-04-24
Go 版本：Go 1.0+ 🟢

Keyboard shortcuts

Go 标准包使用指南